PrivateGPT：开源本地 AI 应用 API 层，Claude API 兼容，外接 Ollama / vLLM 即开｜部署与使用全指南
仓库：https://github.com/zylon-ai/private-gpt 维护方：Zylon 形态：本地 AI 应用 API 层（不是模型推理服务），端口 8080 核心定位：把任意 OpenAI 兼容推理服务器包装成 Claude API 兼容的私有应用后端
1. 项目简介
PrivateGPT 是 Zylon 开源的"本地 AI 应用 API
层"：它自己不跑模型，而是通过 OPENAI_API_BASE 连接到任意
OpenAI 兼容的推理服务器（Ollama、llama.cpp、vLLM 等），对外提供一套遵循
Claude API 规范的本地 API，覆盖消息、文件摄取、检索带引用、Agentic
RAG、内置工具、MCP、数据库与 CSV 访问、嵌入与编排。它内置一个 Workbench
UI（/ui）用于测试与演示，但 API 才是真正的产品。
你的应用 / Agent / 工作流 / UI
|
PrivateGPT API
|
OpenAI 兼容推理服务器（Ollama、llama.cpp、vLLM …）⚠️ PrivateGPT 不跑模型本身。只要某个服务实现了
/v1/chat/completions与/v1/models，它就能接。
1.1 核心信息一览
| 项目 | 说明 |
|---|---|
| 名称 | PrivateGPT |
| 仓库 | zylon-ai/private-gpt |
| 定位 | 开源本地 AI 应用 API 层，Claude API 兼容 |
| 维护方 | Zylon（商业平台 Zylon 与开源 PrivateGPT 同源） |
| 语言 / 框架 | Python（uv 安装） |
| 部署方式 | brew / uv 工具安装；Docker 见官方文档 |
| 默认端口 | 8080 |
| 系统入口 | UI：http://localhost:8080/ui；API：http://localhost:8080 |
1.2 适用场景
- 已经在用 Ollama / llama.cpp / vLLM 跑模型，想在上面加一层消息、检索、工具、MCP、数据库访问能力。
- 想把本地模型接到 Claude Code / Claude Desktop / Cowork / Microsoft 365 / OpenCode / n8n / Cline 等工具上。
- 想要一个 API-first 的本地后端，而不是一个开箱即用的聊天应用（如 Open WebUI / Onyx）。
- 企业需要私有、本地、不依赖云 API 的 AI 应用底座。
1.3 能力边界（官方口径）
- PrivateGPT 本身不跑模型；必须先有一个 OpenAI 兼容推理服务器（Ollama 最易上手）。
- 内置 Workbench UI 是演示与内部试点用，不是最终产品；开发者应基于 API 自建应用。
- 与 Zylon 的关系：PrivateGPT 是开源 API 层，Zylon 是在其之上加了 K8s 编排、RBAC、LDAP、审计、air-gapped 等企业能力的商业平台。
2. 功能特性
- 💬 标准 Messages API：流式、异步、token 计数，完全对齐 Claude API。
- 📎 文件与 Artifact 摄取：上传 PDF / 文档做私有 RAG。
- 🔎 带引用的检索与 Agentic RAG：回答带出处，可追溯。
- 🛠️ 内置工具：Web 搜索、网页抓取、代码执行，与 Claude API 对齐。
- 🧩 自定义工具与 MCP：既可挂远程 MCP server，也可注册自己的工具。
- 🗄️ 数据库与 CSV 结构化访问：内置 SQL / 表格分析能力，不依赖外部工具。
- 🧠 嵌入与编排：自带嵌入与工作流编排。
- 🖥️ Workbench UI：发消息、选模型、上传文档、试检索、按聊天启用工具、配 MCP / 数据库、API Debugger。
- 🔌 即插即用集成：Claude Code、Claude Desktop / Cowork、Microsoft 365、OpenCode、n8n、Cline、VS Code、Hermes Agent 等。
3. 官方界面预览
图为官方 README 中的 PrivateGPT Workbench UI：左侧为会话与工具配置，右侧为消息、模型选择与 API Debugger。
4. 官方跳转链接汇总
- 仓库：https://github.com/zylon-ai/private-gpt
- 文档：https://docs.privategpt.dev/
- Quickstart：https://docs.privategpt.dev/getting-started/quickstart
- Discord：https://discord.gg/F8KCFeZbkx
- X：https://twitter.com/ZylonPrivateGPT
- Zylon 商业平台：https://www.zylon.ai/
- Claude Code 集成：https://docs.privategpt.dev/integrations/claude-code
- Claude Desktop 集成：https://docs.privategpt.dev/integrations/claude-desktop
- API 参考：https://docs.privategpt.dev/api-reference/api-reference
5. 前置要求与服务器配置
5.1 软件前提
- 一个正在运行的 OpenAI 兼容 LLM 服务器：Ollama 最易上手。
- macOS：Homebrew。
- Linux / Windows：uv（Python 包管理器）。
- Python 3.11（uv 自动管理）。
5.2 硬件与系统建议
- 跑 PrivateGPT 本身很轻；资源消耗主要在它背后的 LLM 服务器（Ollama 等）。
- 示例命令中 LLM 用
qwen3.5:35b（约 24 GB），嵌入用mxbai-embed-large（约 670 MB）；按自己硬件选更小模型。
5.3 端口分配
| 端口 | 服务 | 说明 |
|---|---|---|
| 8080 | PrivateGPT API + Workbench UI | UI 在 /ui |
| 11434 | Ollama（默认） | 仅当用 Ollama 时 |
5.4 磁盘与模型
- PrivateGPT 代码本身小；模型权重由 Ollama 管理。
- 上传的文档、向量索引需要预留磁盘。
6. 方式一：brew / uv 工具安装（推荐）
6.1 安装 PrivateGPT
# macOS
brew tap zylon-ai/tap
brew install private-gpt# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install --python 3.11 \
--find-links https://wheels.privategpt.dev/packages/ \
"private-gpt[core]"# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install --python 3.11 `
--find-links https://wheels.privategpt.dev/packages/ `
"private-gpt[core]"6.2 启动 LLM 服务器（示例：Ollama）
ollama pull qwen3.5:35b # LLM（约 24 GB）
ollama pull mxbai-embed-large # Embeddings（约 670 MB）
ollama serve6.3 启动 PrivateGPT
# macOS / Linux
OPENAI_API_BASE=http://localhost:11434/v1 \
OPENAI_EMBEDDING_API_BASE=http://localhost:11434/v1 \
private-gpt serve# Windows PowerShell
$env:OPENAI_API_BASE = "http://localhost:11434/v1"
$env:OPENAI_EMBEDDING_API_BASE = "http://localhost:11434/v1"
private-gpt serve6.4 打开 UI
浏览器访问 http://localhost:8080/ui。API
根地址为 http://localhost:8080，遵循 Anthropic
API 规范。
完整 Docker 与其他安装方式见官方 Quickstart。
7. 方式二：源码 / 自定义
git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt
# 按仓库 README 与 docs.privategpt.dev 配置PrivateGPT 与 Ollama / LM Studio / LocalAI / vLLM / llama.cpp 是"互补关系"：那些是"怎么跑模型"，PrivateGPT 是"在模型之上怎么搭应用"。
8. 配置项说明
| 环境变量 | 用途 | 示例 |
|---|---|---|
OPENAI_API_BASE |
指向 LLM 推理服务器的 OpenAI 兼容 endpoint | http://localhost:11434/v1 |
OPENAI_EMBEDDING_API_BASE |
指向嵌入模型 endpoint | http://localhost:11434/v1 |
| LLM 模型名 | 在 Workbench /ui 中从 /v1/models 选择 |
qwen3.5:35b |
| Embedding 模型名 | 检索 / 摄取时使用 | mxbai-embed-large |
| 端口 | 默认 8080 | 见官方文档 |
完整配置项（数据库、MCP、工具、权限、审计等）以 docs.privategpt.dev 为准。
9. 常用运维命令
# 启动
private-gpt serve
# 停止
# 在终端 Ctrl+C
# 升级
brew upgrade private-gpt # macOS
uv tool upgrade private-gpt # Linux / Windows
# 查看 Ollama 模型
ollama list
ollama ps
# 查看日志
private-gpt serve # 日志直接打到终端
# 卸载
brew uninstall private-gpt
uv tool uninstall private-gpt备份：上传的文档与向量索引（具体路径见官方文档）。
10. 常见故障排查
private-gpt: command not found：确认 uv 安装后把~/.local/bin加进 PATH；macOS brew 路径自动生效。- UI 打开但模型列表为空：确认 Ollama 已
ollama serve且ollama list有模型；OPENAI_API_BASE指向正确端口。 - 文档上传后无结果：确认 embedding
模型已拉取（
mxbai-embed-large或同类）；文档摄取是异步过程，看 Workbench 进度。 - Claude Code 连不上：参考 Claude Code 集成指南，把 base URL 与 API Key 指向 PrivateGPT。
- 8080 被占用：改端口或停掉占用进程；具体端口变量见官方文档。
- 想接 OpenAI 官方 API：也可以把
OPENAI_API_BASE指向 OpenAI，但那就失去"私有本地"意义；PrivateGPT 的价值在接本地推理服务器。 - 与 Zylon 关系混淆：PrivateGPT 是开源 API 层；Zylon 是企业平台，二者不要混为一谈。
11. 风险与合规说明
- 许可证：以仓库根 LICENSE 为准（Zylon 开源）；商用前请核对最新版本。
- 数据隐私：PrivateGPT
本身本地运行，文档与请求数据默认不出你的基础设施；但它背后的 LLM
服务器若指向远端 API，数据仍会外发，请确保
OPENAI_API_BASE指向本地。 - 模型版权：Ollama / vLLM 等推理服务器上的权重（Qwen、Llama、DeepSeek 等）由对应模型发布方授权，商用前请核对。
- Workbench UI 是演示：不要把它直接当生产前端暴露公网；生产应基于 API 自建应用。
- 对外暴露：
8080若公网可达，需自行加鉴权 / 反向代理，避免被滥用。 - 商业平台边界：需要 LDAP / AD、RBAC、审计、air-gapped、K8s 编排时，Zylon 商业平台才提供；PrivateGPT 开源版不包含这些企业能力。