PrivateGPT

PrivateGPT 快速入门

自托管的「Claude 风格」应用 API：消息、文件摄取、带引用检索、工具调用、MCP、数据库问答一次给全，模型和数据都留在他自己的机器上。

这是什么?适合谁?

PrivateGPT 是 zylon-ai/private-gpt 维护的开源应用 API 层：它自己不跑模型，而是架在任意 OpenAI 兼容推理服务（Ollama、llama.cpp、vLLM、LM Studio…）之上，对外提供现代 AI 应用需要的上层积木——标准 messages API（含流式、异步、token 计数）、文件与产物摄取、带引用的检索与 Agentic RAG、内置工具（联网搜索、网页抓取、代码执行）、自定义工具、MCP 连接器、结构化数据库与 CSV/tabular 访问、embeddings 与编排。

它的接口以 Claude API 为参照设计，官方给出逐项对照表：大多数能力对齐，少数明确未做（prompt caching、OAuth/组织管理），Skills 处于 basic 阶段，结构化输出与视觉能力取决于所选模型。

它解决的痛点：本地跑起来一个模型只是第一步。要真做应用，你还得自己攒一套 messages 协议、文档切分与向量化、引用回链、工具定义与调度、MCP 客户端、数据库查询——这些胶水代码每个团队都要重写一遍。PrivateGPT 把这一层做成成品。

适合谁：

• 数据不能出内网/不能上云，但又想给团队做 AI 助手的团队（金融、医疗、政府、军工等合规场景常见）
• 想让 Claude Code、Claude Desktop、OpenCode 这类客户端改跑自己的本地模型的开发者
• 需要在自托管环境里做「文档问答 + 带引用检索 + 数据库问答」的工程团队
• 想自建一份可审计、可替换推理后端的 AI 应用底座的技术选型者

不适合：只想开箱即用聊天、不想碰推理服务的非技术用户（这类需求看 Onyx / Open WebUI 更直接）；完全不想准备 GPU/内存的人；指望它自带企业级多租户治理的团队（RBAC、LDAP、SIEM 审计在企业版 Zylon 里，不在开源层）。

使用前提：一台能跑目标模型的机器（GPU 或足够内存）；一个 OpenAI 兼容推理服务；Python 3.11（走 uv 安装）或 Docker；基本命令行能力。

准备工作

• 软件：macOS 用 Homebrew；Linux / Windows 用 uv 安装 Python 3.11 工具；也提供 Docker 方式
• 推理后端（自选其一）：Ollama、llama.cpp、vLLM、LM Studio，或任意实现 /v1/chat/completions 与 /v1/models 的服务（本地或远程都行）
• 模型：一个对话模型 + 一个 embedding 模型。官方 README 的示例是 qwen3.5:35b（约 24 GB）+ mxbai-embed-large（约 670 MB）
• 费用：PrivateGPT 本体 Apache-2.0，软件零成本；真实开销在硬件、电力和你投入的运维时间
• 前置知识：环境变量配置、HTTP API 调用（curl 或任意 SDK）、基本的 RAG 概念
• 替代方案：Onyx / Open WebUI（应用优先，自带完整界面）、Dify（低代码编排）、AnythingLLM（桌面一体化）；想直接跑模型而不需要上层 API 的话，Ollama / LM Studio 本身已足够

3 步快速上手

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

第 2 步：先把推理服务跑起来

PrivateGPT 不托管模型，你必须先有一个 OpenAI 兼容端点。以 Ollama 为例：

ollama pull qwen3.5:35b         # 对话模型（约 24 GB）
ollama pull mxbai-embed-large   # 嵌入模型（约 670 MB）
ollama serve

第 3 步：启动并验证

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 serve

服务默认监听 8080：UI 在 http://localhost:8080/ui，API 在 http://localhost:8080，遵循 Anthropic API 规范。成功判定：打开 /ui 能正常加载，并在里面完成一次「上传文档 → 提问 → 拿到带引用来源的回答」的闭环。官方文档称 Quickstart 可在 5 分钟内跑通（不含模型下载时间）。

初级用法

• 文档问答：把 PDF/文本投进文件摄取接口，检索时会返回带出处的回答，便于人工复核
• 用 UI 先探边界：/ui 是官方提供的测试台，先在里面把模型、检索、工具各试一遍，确认行为再写代码
• 用 curl 打通 API：文档的 API Guide 有 messages、files、retrieval 的分步示例，照着改 payload 最快
• 接现成客户端：官方给了 Claude Code、Claude Desktop/Cowork、Microsoft 365（Word/Excel/Outlook/PowerPoint）、OpenCode 的集成指南，把本地模型变成这些工具的后端

高级玩法

• 只当后端用：不上任何界面，把 PrivateGPT 作为自有产品的 API 层，前面接你自己的鉴权与计费
• Agentic RAG + 自定义工具：用内置工具的接口形态写自己的工具，让模型在检索之外还能调内部系统
• MCP 扩展生态：通过 MCP 连接器挂远程 MCP 服务器，把外部工具集接进同一条调用链
• 数据库/CSV 直问：用结构化数据库访问和 tabular 分析能力做「业务数据问答」，不必先把数据导出成文档
• 混搭推理后端：对话走本地大模型、嵌入走轻量服务，或按任务把 OPENAI_API_BASE 指向不同端点以平衡延迟与成本
• 文档索引即服务：把 docs.privategpt.dev/llms.txt（及任意页面加 .md）喂给编码 Agent，让它按官方口径帮你写集成代码

常见踩坑

踩坑 1：以为装上就能直接用

• 现象：private-gpt serve 起来了，一发请求就报连不上模型
• 原因：PrivateGPT 不含推理能力，OPENAI_API_BASE 必须指向一个已经在跑的兼容服务
• 解决：先单独确认 curl http://localhost:<port>/v1/models 有正常返回，再启动 PrivateGPT

踩坑 2：embedding 端点忘了配

• 现象：对话能用，一上传文档/检索就失败
• 原因：对话和嵌入是两条独立配置（OPENAI_API_BASE 与 OPENAI_EMBEDDING_API_BASE），只配一个不够
• 解决：两个环境变量都指向提供 embeddings 的端点，并确认该服务已拉取 embedding 模型

踩坑 3：照抄 0.x 的教程和代码

• 现象：老的 PrivateGPT 示例跑不通，接口对不上
• 原因：1.0 是破坏性大版本，旧 API 不向前兼容，官方还专门提供了迁移指南
• 解决：只参考 docs.privategpt.dev 上 1.0 之后的文档；老项目按迁移指南改造

踩坑 4：模型太大把自己劝退

• 现象：加载模型就 OOM，或响应慢到不可用
• 原因：README 示例的 35B 级模型光权重就约 24 GB，还没算 KV cache 和嵌入模型
• 解决：按显存/内存选更小的模型先跑通链路，需要效果再往上换；量化版本能显著降门槛

踩坑 5：以为开源版就有企业治理能力

• 现象：找不到 LDAP、RBAC、SIEM 审计、OAuth 组织管理
• 原因：官方对照表里 OAuth/组织是明确不支持的；LDAP、SIEM、网关、多租户这些属于商业版 Zylon 的能力
• 解决：开源层用 token 认证加自建前置代理；确实需要完整治理再评估商业版

踩坑 6：把「Claude 兼容」当成 100% 等价

• 现象：按 Claude API 文档写的某些参数在本地不生效
• 原因：官方对照表里 prompt caching 标 ❌，Skills 标 ⚙️ basic，结构化输出与视觉依赖所选模型
• 解决：上线前逐项对照官方 parity 表，把依赖这些特性的逻辑改成降级实现或换模型

小技巧

• 先跑通「最小模型 + 最小文档」的链路，再换大模型，排错成本低一个数量级
• 用官方文档的 .md 后缀技巧批量取干净 Markdown，比抓 HTML 再清洗省事
• 把 OPENAI_API_BASE 指向局域网里的推理机，笔记本上只跑 PrivateGPT，硬件利用率更高
• 检索类问题一定要看返回的引用出处，这是它相对「直接问模型」的核心价值
• 装机前先用 v1/models 探测端点，能省掉一半「配置类」故障

进阶学习建议

要吃透它，按「跑 → 接 → 拆」三层推进：

1. 跑：读 docs.privategpt.dev 的 Quickstart 与 How it works（启动流程、profiles、环境变量），把 messages / files / retrieval 三个 API Guide 各手打一遍 curl，建立对「API 层」而非「聊天应用」的心智模型。
2. 接：从官方集成指南里挑一个你天天用的客户端（Claude Code 或 OpenCode 最直观），把它的后端换成你的本地端点；然后写一个自定义工具并挂一个远程 MCP 服务器，体会工具调用链路怎么串起来。
3. 拆：进仓库读实现，重点看 API 层与组件层如何解耦——它把 LLM、Embedding、VectorStore 都做成可替换抽象，这正是「换后端不动上层」的架构依据。想更进一步，对照 zylon-ai/pgpt-python 与 privategpt-ts 两个官方 SDK 看同一套 API 的两种客户端封装。

FAQ

Q1: PrivateGPT 免费吗？

A: 本体 Apache-2.0 完全免费，源码可审计可自改；成本只有你自己的硬件与运维。商业版 Zylon 才是收费产品。

Q2: 它和 Ollama / LM Studio 是什么关系？

A: 互补而非替代。Ollama 们解决「怎么把模型跑起来」，PrivateGPT 解决「怎么在模型之上做出一个应用」——它是本地推理层之上的应用 API 层，两者叠着用。

Q3: 和 Onyx、Open WebUI 比怎么选？

A: 要一个能直接用的自托管 AI 应用/企业搜索界面，选 Onyx 或 Open WebUI；要一层标准化、可嵌进自己产品的 API 底座，选 PrivateGPT。它的 UI 只是测试台，API 才是产品。

Q4: 能完全离线/气隙部署吗？

A: 可以，这正是它的主线场景；官方说明强调不依赖云 API，推理与数据都在你的环境内。安装与模型分发环节需要按内网条件自行规划。

Q5: 能接 Claude Code 这类工具吗？

A: 能。因为按 Anthropic API 规范实现，官方提供了 Claude Code、Claude Desktop / Cowork、Microsoft 365 插件和 OpenCode 的接入指南，让这些客户端把请求打到你的本地实例。

免责声明

本文基于官方文档和公开资料整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

• GitHub 仓库 zylon-ai/private-gpt
• 官方文档 docs.privategpt.dev
• 官网 PrivateGPT 页面（Zylon）
• Zylon 官方博客：Introducing PrivateGPT 1.0