zylon-ai/private-gpt · 上手攻略

• 仓库：zylon-ai/private-gpt
• 链接：https://github.com/zylon-ai/private-gpt · 文档 https://docs.privategpt.dev/ · 官网 https://www.privategpt.dev/
• 分类：ai（本地推理代理层 / 私有 LLM 后端）
• 作者：spark
• 更新：2026-08-17

⚠️ 本稿数字与命令以 README 与 docs.privategpt.dev 抓取为准；命令中 qwen3.5:35b、mxbai-embed-large 等具体模型名取自 README Quickstart，未经独立复现，请按你的硬件与显存重新核对。

1. 是什么

PrivateGPT 是 Zylon 公司在 2023 年那个"本地聊天 PDF"爆款脚本基础上重写出来的 私有 AI 应用 API 层。它本身不跑模型，只是把任意一个 OpenAI 兼容的推理服务（Ollama、llama.cpp、vLLM、TGI、LM Studio…）包成一个 Anthropic / Claude 风格的 API，对外暴露 Messages、Tools、MCP、Files、RAG、Embeddings 等一等能力。你拿它当 Claude API 的本地替身来用就行——同一个协议、同一个请求格式，只是后端接的是你自己的机器。

仓库当前已经是 1.0 时代的成熟形态：内置 workbench UI（/ui）、Streaming、Async、Tools、MCP、Skills、内置数据库/CSV 结构化访问。商业版叫 Zylon，企业本地交付用的，AGPL-3.0 开源版本功能已经覆盖绝大部分 API 能力。

2. 解决什么问题

要在本地真正"做产品级 AI 应用"，只跑通 ollama run 远远不够——你需要：

• 文件上传 / chunk / ingest / 引用回显
• 流式输出和 token 计数
• 工具调用与流式并行工具
• 标准 MCP 接入
• 结构化输出与外部数据库查询
• 内置 Web Search / Web Fetch

每个能力单做都要花 2-4 周。PrivateGPT 把这块全做了，你只写业务：UI、agent prompt、workflow。当前 star 5.7 万+（认领段数据），问题就是"私有 AI 后端不要从零造"。

3. 快速安装

前置：Python ≥ 3.11、磁盘够装模型（35B 量级约 24 GB）、至少 Ollama 跑起来当 LLM 后端。

3.1 macOS

brew tap zylon-ai/tap
brew install private-gpt

3.2 Linux / Windows（用 uv）

# 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]"

⚠️ python 3.11 是 README 标注的推荐版本；3.12/3.13 的兼容性未在仓库 README 中显式声明，先按官方版本钉住。

3.3 启动 LLM 后端（Ollama 示例）

ollama pull qwen3.5:35b       # 主对话模型，README 给的样本，约 24 GB 显存
ollama pull mxbai-embed-large # 嵌入模型，约 670 MB
ollama serve                  # 默认监听 11434

3.4 启动 PrivateGPT

# macOS / Linux
OPENAI_API_BASE=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_EMBEDDING_API_BASE=http://localhost:11434/v1 \
private-gpt serve

# Windows PowerShell
$env:OPENAI_API_BASE = "http://localhost:11434/v1"
$env:OPENAI_API_KEY = "ollama"
$env:OPENAI_EMBEDDING_API_BASE = "http://localhost:11434/v1"
private-gpt serve

启动后：API 跑在 http://localhost:8080，Workbench UI 在 http://localhost:8080/ui。

4. 核心用法

4.1 Messages API（Anthropic 兼容）

curl -s http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5:35b",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"总结 README 三句话"}]
  }'

对，你没看错——接口是 Anthropic /v1/messages，不是 OpenAI /v1/chat/completions，这是 PrivateGPT 的设计取舍：它认为 Claude API 是当前"现代 AI 应用 API"的参考实现，把后端藏在 OPENAI_API_BASE 里。

4.2 文件摄取 + RAG 引用回显

# 上传文件
curl -X POST http://localhost:8080/v1/files \
  -F "file=@./manual.pdf"

# 触发检索（messages API 内置 tools）
curl -s http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model":"qwen3.5:35b",
    "messages":[{"role":"user","content":"manual 里第 3 章说了什么？"}],
    "tools":[{"type":"retrieval"}]
  }'

返回里会带 citations 数组，每条带 document_id / start / end / 引文片段，省掉自己写 RAG 评价。

4.3 MCP 接入

PrivateGPT 直接当 MCP Host，把外部 MCP Server 通过配置接进来，模型在工具调用时会自动路由。内置工具包含 Web Search、Web Fetch、Code Execution、Database Query、CSV 分析。

4.4 上层集成（README 给的官方集成清单）

promo citation 中位 6（围绕本仓库攻略的累计引用统计）—— 这套集成让它立刻具备"换上 URL 就能跑"的产品体感。

4.5 Tools 流式 + Async

Messages API 原生支持流式（stream: true）、异步批处理（x-pgpt-async: true）、token 计数（count_tokens 子端点），不要求工程侧自己实现 SSE 长连接管理。

5. 典型适用场景

• 企业内部 AI 平台：合规要求数据不出网，Anthropic API 又必须有的产品特性——PrivateGPT 直接顶替。
• 个人 / 小团队的 ChatGPT 替代：不想数据过 OpenAI 服务器，又不想自己写 RAG、UI、流式。
• Agent 后端：需要"OpenAI 兼容 → Anthropic 兼容 → MCP → Tools"四件套的本地代理，否则就要自己写。
• Claude API 风格的协议网关：把企业多个 LLM 后端统一对外暴露一个 Claude API 形状。

6. 坑与注意

• 不是"一键离线 ChatGPT"：它是个 API 层。你必须自己装 Ollama 或 vLLM，再装模型（约 24 GB+），再加 chat 前端。起步成本比想象中的"PDF 聊天"高。
• 协议选 Anthropic 而非 OpenAI：虽然 OPENAI_API_BASE 指向后端，但对外 API 是 /v1/messages。如果你已经在用 OpenAI 客户端 SDK（如 openai-python），需要换成 anthropic SDK 或适配层。
• 模型能力上限 = 你的后端模型：35B 级别的本地模型在长 reasoning、多工具并发、agentic loop 上和云端 frontier 差距明显。README 推荐的 qwen3.5:35b 是"够用"而不是"够强"。
• Prompt caching × OAuth / Organizations：Claude 平台能力矩阵显示 PrivateGPT 对 prompt caching 与多组织 OAuth 显式 ❌；如果你依赖这两项，需要前置自建缓存层 + 单租户策略。
• Skills 仍在 ⚙️ 部分支持：Claude 的 Skills 概念在 PrivateGPT 是 "basic" 状态，复杂 skill 定义需要自己实现 router。
• 文档站点与代码可能错位：本文档基于 README 当前可见版本（docs.privategpt.dev），版本号、模型名、命令都可能迭代，使用前先 git log 看最近 commit。

7. 与同类对比

如果你的目标是"让本地的 LLM 立刻能当 Claude API 用"，PrivateGPT 是当前最直接的开源答案；如果你要的是"给员工一个 ChatGPT 风格 UI"，Open WebUI 更划算。

8. 一句话推荐

要自建私有 AI 后端、想要 Claude API 形状 + 文档完整 + MCP/RAG 一体化，PrivateGPT 1.0 已经是少有的"装上就能跑生产"的本地代理层；唯一需要掂量的是协议形状（Anthropic vs OpenAI）和后端模型能力天花板。

来源

• README：https://github.com/zylon-ai/private-gpt（web_fetch, 2026-08-17）
• 文档：https://docs.privategpt.dev/
• 官网对比说明：https://www.privategpt.dev/

⚠️ qwen3.5:35b / mxbai-embed-large 为 README Quickstart 中的示例命令，未在本地核验显存占用；命令已用 OPENAI_API_BASE 标准环境变量，Ollama 默认端口 11434。