PrivateGPT 全攻略：本地私有文档问答系统的安装、实操与部署

为什么需要 PrivateGPT：企业文档问答的本地化刚需

企业内部知识大量沉淀在 PDF、Word、Markdown 文档中。传统做法是人工翻阅，或依赖关键词全文搜索，无法回答“2023 年哪些供应商合同包含竞业条款”这类语义问题。把文档交给公有云 LLM（大语言模型）则有三条硬伤：法务、财务、研发文档高度敏感，数据出域有合规风险；通用模型不掌握企业内部上下文，直接提问只能得到泛泛回答；从零搭建 RAG 管线（切分、嵌入、检索、生成）涉及大量工程细节，普通团队动辄数周。

PrivateGPT 把这条管线打包成开箱即用的服务：上传文件后自动完成文本解析、切片（chunking，将长文档按语义拆成小块）、向量化（嵌入模型把文本转为语义向量）与存储；提供 OpenAI 兼容的 /v1/chat/completions 接口，回答时基于检索到的原文片段生成，并返回引用来源（sources）。部署形态上，既可以用 Ollama 让数据和推理全部留在内网，也可以接 OpenAI 兼容的远程模型以节省算力——隐私边界由你自己决定。配套的 Web UI 让非技术同事无需写代码即可使用。

与 LangChain、LlamaIndex 这类“组件库”不同，PrivateGPT 是“成品”，装完即有 API 和界面；与 AnythingLLM 这类桌面工具相比，它本质是一个服务，更适合内网多用户访问与二次开发。代价是定制自由度和组件生态不如框架型工具，特殊管线需求需要自己改代码。

安装与环境配置：4 步就绪

前置条件：Python 3.10 以上；源码方式需要 make 与 Poetry；使用本地推理模式需要先安装 Ollama（本地大模型运行工具）。

步骤一、选择安装路径。只调用 API 用 pip install "privategpt[server]"；需要内置 Web UI 则克隆源码并用 Poetry 安装（UI 为 Angular 前端，源码方式会自动构建）。步骤二、配置模型模式。默认以 mock 模式启动（不调用真实模型，用于验证链路）；做真实问答需切换到 ollama（本地）或 openai（远程兼容）模式，并通过环境变量或 settings.yaml 配置模型名。Ollama 模式要预先拉取对话模型与嵌入模型。步骤三、启动服务。源码方式执行 make run，然后访问 http://localhost:8001；纯 API 方式用 uvicorn 启动。步骤四、验证安装。请求健康检查接口返回 ok，并确认 Swagger 文档可访问。

# ① 安装（两条路径任选其一）pip install "privategpt[server]"                       # 仅 API 服务git clone https://github.com/zylon-ai/private-gpt      # 含 Web UI 的源码cd private-gpt && poetry install --with ui,local,server # ② 本地模式（Ollama）先拉取模型，再配置模式ollama pull llama3ollama pull nomic-embed-textexport PRIVATEGPT_LLM_MODE=ollamaexport PRIVATEGPT_LLM_MODEL=llama3export PRIVATEGPT_EMBEDDINGS_MODE=ollamaexport PRIVATEGPT_EMBEDDINGS_MODEL=nomic-embed-text # ③ 启动（源码方式推荐 make run，访问 http://localhost:8001）make run# 或纯 API 方式：# uvicorn privategpt.server.app:app --port 8001 # ④ 验证curl http://localhost:8001/v1/health

快速上手：10 分钟跑通第一个文档问答

最小闭环只有三步：导入文档、提问、核对引用来源。建议先用 PDF 或 Markdown 测试，避开复杂格式。接口方式适合开发集成，UI 方式适合非技术用户，两者共用同一套文档与问答能力。

• 步骤一：启动服务，确认 http://localhost:8001/v1/health 返回 ok。

• 步骤二：调用 POST /v1/ingest 上传一份测试文档（multipart 格式）。

• 步骤三：调用 POST /v1/chat/completions，将 use_context 设为 true 后提问。

• 步骤四：在响应的 sources 字段中核对模型引用的原文片段，确认回答确实来自文档而非模型自由发挥。

以下为 API 方式的完整可运行示例：

运行后，回答会基于刚导入的文档内容生成，sources 列出模型实际引用的段落与来源文件。进阶技巧：通过 context_filter.docs_ids 限定只在指定文档集内检索；开启 stream 参数获得流式输出；未导入文档就提问时，模型可能给出无关的通用回答，属预期行为。

import requests BASE = "http://localhost:8001" # 1) 导入文档（multipart 上传）with open("policy.pdf", "rb") as f:    r = requests.post(        f"{BASE}/v1/ingest",        files={"files": ("policy.pdf", f)},    )print("导入返回:", r.json()) # 2) 基于文档上下文提问，并要求返回引用来源r = requests.post(    f"{BASE}/v1/chat/completions",    json={        "messages": [{"role": "user", "content": "公司对远程办公有什么规定？"}],        "use_context": True,        "include_sources": True,    },)data = r.json()print("回答:", data["choices"][0]["message"]["content"])print("来源:", data.get("sources"))

核心能力详解：4 大支柱

支柱一、文档摄取与管理。POST /v1/ingest 接收 multipart 文件，后台完成文本抽取、切片、向量化并写入向量库（存储文档语义向量、用于相似度检索的数据库）；GET /v1/ingest 列出已导入文档，DELETE /v1/ingest/{doc_id} 按 ID 删除。原生支持 PDF、TXT、Markdown 等文本类格式，扫描件与复杂表格需先做 OCR 或格式转换。注意默认内存向量库不持久化，服务重启后需重新导入文档。

支柱二、检索增强问答。/v1/chat/completions 请求体采用 OpenAI 兼容的 messages 格式。三个关键参数：use_context 决定是否把检索结果拼入提示词（设为 true 即“回答仅基于文档”）；include_sources 让响应携带引用片段与元数据，支持溯源核对；context_filter 按已导入文档 ID 集合限定检索范围，实现“只在这个文档集里问”。多轮对话时需自行维护历史消息列表。

支柱三、多后端灵活切换。LLM 与嵌入模型独立配置，各有本地（Ollama/本地嵌入模型）与远程（OpenAI 兼容）模式，另有 mock 模式用于无模型联调。这带来三种典型组合：推理与嵌入全本地＝数据完全不出内网；推理走云模型、嵌入留本地＝混合架构；mock 模式＝只验证 API 链路，不产生真实回答。切换模式只需改环境变量或 settings.yaml，无需改业务代码。

支柱四、Web UI 与 API 一体化。同一服务端口同时输出 Angular 前端、REST API 与 Swagger 文档（http://localhost:8001/docs）。UI 提供文档上传、对话问答与 Sources 引用查看，非技术用户可直接使用；API 面向系统集成，便于对接内部 OA、工单系统。二者共享同一配置与向量存储，部署一套即可。

生产部署与监控：从上线到运维

部署方式一、systemd + uvicorn 托管纯 API 服务。适合只需被业务系统调用的场景：编写 systemd 单元文件托管 uvicorn 进程，实现开机自启与崩溃拉起；日志经 journalctl 统一采集；在服务配置中启用 server.auth（Bearer Token 鉴权）保护内网接口，前端通过 Nginx/Caddy 终结 TLS。

部署方式二、Docker 容器化 + 反向代理。仓库内置 Dockerfile，可构建镜像并映射 8001 端口；文件卷（已导入文档）与向量库目录必须挂载到宿主机，避免容器重建导致数据丢失；前端网关配置内网域名、TLS 与访问控制。多用户场景注意并发：推理在本地 GPU 时，多路并发会排队，建议按用户组拆分实例或限制请求频率。

可观测性。GET /v1/health 返回 ok，供负载均衡或监控探活；uvicorn 访问日志与应用日志记录请求与异常；对 ingest 与 chat 接口自行埋点统计耗时与成功率，Ollama 侧可观察推理时间。系统本身不内置指标面板，生产环境建议接入 Prometheus + Grafana 或自建日志平台。关键指标：导入成功率、问答响应耗时、检索命中率（回答中引用来源的合理性）。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>默认内存向量库不持久化：v2.x 默认把向量存在进程内存，服务重启后检索索引全部丢失，需重新导入。生产环境应配置持久化向量库（如官方支持的 Chroma 方案）或做文档自动重导。</li><li>首次运行需联网下载嵌入模型：使用 sentence-transformers 本地嵌入时，首次会从 Hugging Face 拉取模型文件（如 all-MiniLM-L6-v2）。严格离线环境要提前缓存模型，或改用 Ollama 嵌入模式。</li><li>网上教程大量停留在 0.x：0.x 的 privateGPT.py、ingest.py、.env、GGML 模型等用法在 v2.0 后全部废弃，照抄旧教程会报模块找不到或参数不识别，先确认教程对应的版本分支。</li></ul>

版本迭代

PrivateGPT 2023 年 5 月由独立开发者发布，以“文档不用上传、全部本地跑”迅速走红；2023 年夏因与商业站点 private-gpt.com 的商标争议短暂改名，事件平息后恢复。0.x 期间还有 0.2 及此后多个小版本，主要围绕模型兼容与工程细节。2024 年项目转入 zylon-ai 组织并重写，v2.0 起从脚本式应用变为服务化产品，官方不再维护 0.x。本文版本信息截至 2024 年 11 月的 v2.2.1，此后请以 GitHub Releases 为准。

AI 应用场景

常见误区

面试题

参考来源

• webpageGitHub 仓库源码、README 与安装文档
• doc官方文档安装、配置与 API 参考
• webpageGitHub Releases版本发布记录与更新日志
• webpage官网 privategpt.io产品介绍与团队信息