PrivateGPT 保姆级部署教程：把本地模型变成生产级 AI 应用 API

PrivateGPT（zylon-ai 出品，GitHub 约 5.7 万 Star）是 2023 年那个「离线 Chat with your documents」爆火项目的 1.0 重写版。官方定位已经从「聊天脚本」升级为「open-source API layer that turns local models into production AI applications」：它不跑模型本身，而是接在 Ollama / vLLM / llama.cpp 等 OpenAI 兼容推理服务器前面，提供消息 API、文档摄入、带引用的 RAG、工具调用、MCP 连接器。本文基于官方 README 的 Quickstart 章节。

一、项目介绍与适用场景

PrivateGPT 是一个API 层：它自己不加载模型，通过 OPENAI_API_BASE 连接任意 OpenAI 兼容服务。它在 Claude API 模型之上提供消息、文件摄入、检索引用、工具、数据库访问等能力，让你直接用本地模型构建生产级应用。

官方架构图：

Your app / agent / workflow / UI
              |
        PrivateGPT API
              |
OpenAI-compatible inference server (Ollama, llama.cpp, vLLM, ...)

典型场景：

• 给 Claude Desktop / n8n / Cline 接本地模型：官方提供原生集成。
• 构建私有 RAG API：文档上传后通过 API 查询。
• 企业内网 AI 应用后端：数据不出内网。

二、核心功能逐条拆解

1. 标准消息 API：流式、异步、token 计数。
2. 文件与工件摄入：PDF、文档上传。
3. 带引用的检索与 Agentic RAG：回答可追溯原文。
4. 内置工具：网页搜索、网页抓取、代码执行。
5. 自定义工具与 MCP 连接器：接外部工具服务器。
6. 数据库与 CSV 结构化访问：内置 SQL/表格分析。
7. 内置 Workbench UI：/ui 路径提供调试界面。

三、全套官方链接

四、硬件与环境前置要求

官方 README Quickstart 明确：

• 前置：一个已在运行的 OpenAI 兼容 LLM 服务器（Ollama 最简单）。
• Python：官方安装命令使用 Python 3.11。
• 内存：取决于背后的模型；Ollama 跑 7B 模型约 8GB。
• 磁盘：2GB 起步。

五、多平台部署步骤

以下命令逐条来自官方 README Quickstart。

5.1 macOS 安装

官方原文：

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

逐段解释：添加官方 Homebrew tap，安装 private-gpt。

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

逐段解释：先装 uv（Astral 的 Python 包管理器）；再用 uv tool install 安装 private-gpt 核心包，Python 固定 3.11。

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

5.4 启动 LLM 服务器（Ollama 示例）

官方 README 原文：

ollama pull qwen3.5:35b         # LLM (~24 GB)
ollama pull mxbai-embed-large   # Embeddings (~670 MB)
ollama serve

逐段解释：拉取对话模型和 embedding 模型，启动 Ollama 服务。

5.5 启动 PrivateGPT

官方原文（macOS/Linux）：

OPENAI_API_BASE=http://localhost:<llm-port>/v1 \
  OPENAI_EMBEDDING_API_BASE=http://localhost:<embedding-port>/v1 \
  private-gpt serve

逐段解释：通过环境变量告诉 PrivateGPT LLM 和 embedding 服务地址；private-gpt serve 启动 API 服务。官方说明：UI 在 http://localhost:8080/ui ，API 在 http://localhost:8080。

Windows PowerShell 版本：

$env:OPENAI_API_BASE = "http://localhost:<llm-port>/v1"
$env:OPENAI_EMBEDDING_API_BASE = "http://localhost:<embedding-port>/v1"
private-gpt serve

六、配置文件全部参数解释

官方 README 核心环境变量：

官方说明：任何实现 /v1/chat/completions 和 /v1/models 的服务都能接。

七、启动、后台常驻与开机自启

7.1 启动

private-gpt serve 启动；预期日志显示 API 监听 8080。

7.2 后台常驻

nohup 或 systemd 托管。

7.3 开机自启

写 systemd unit。

7.4 修改端口

官方未在 README 中给出端口参数，详见 docs.privategpt.dev。

八、功能实操教程

第 1 步：按 5.1~5.5 安装并启动。

第 2 步：浏览器访问 http://localhost:8080/ui 。

第 3 步：从模型下拉框选择 Ollama 提供的模型。

第 4 步：上传一个 PDF 文档。

第 5 步：提问，观察带引用的回答。

第 6 步：在 UI 里启用网页搜索工具，再问需要联网的问题。

第 7 步：用 curl 调 API：

curl http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5:35b","messages":[{"role":"user","content":"你好"}]}'

九、全套报错故障排查

1. 报错原文：private-gpt: command not found 原因分析：uv 安装的二进制未在 PATH。 解决方案：uv tool update-shell 或重开终端。

2. 报错原文：连接 Ollama 失败 原因分析：Ollama 未启动或地址不对。 解决方案：ollama serve 启动；确认 OPENAI_API_BASE 末尾是 /v1。

3. 报错原文：embedding 报错 原因分析：未单独拉 embedding 模型。 解决方案：ollama pull mxbai-embed-large。

4. 报错原文：UI 打开是空白 原因分析：服务未 ready。 解决方案：看终端日志，等初始化完成。

5. 报错原文：Python 版本错误 原因分析：未用 3.11。 解决方案：重装时加 --python 3.11。

十、升级、回滚与卸载

升级：uv tool upgrade private-gpt 或 brew upgrade private-gpt。

卸载：uv tool uninstall private-gpt 或 brew uninstall private-gpt。

十一、商用许可与合规风险提示

PrivateGPT 采用 Apache-2.0，商用友好。它本身不绑定任何模型权重，商用前需核对你接的 Ollama 模型 License。

参考链接：

• PrivateGPT GitHub README：https://github.com/zylon-ai/private-gpt
• 官方文档：https://docs.privategpt.dev
• 完整 Quickstart：https://docs.privategpt.dev/getting-started/quickstart