PrivateGPT v2：文档聊天机器人，100% 私密

#为什么选择 PrivateGPT v2 用于本地文档聊天机器人

需求很常见：能够以自然语言向内部文档集合（合同、薪资单、发票、会议纪要）提问，而无需将这些数据发送至 OpenAI、Anthropic 或 Google。这正是 PrivateGPT 自 2023 年首次发布以来一直致力于实现的目标

项目的 v2 版本做出了明确决定：不再内置 LLM 引擎，也不再在内部管理量化。取而代之的是，PrivateGPT v2 将生成任务交给外部后端——大多数情况下是 Ollama。这让项目更易于维护，也无需专门配置就能使用 Ollama 的整个模型库（Qwen、Gemma、Granite、Mistral 等）。

100% 本地

所有功能均运行在您的设备上。模型下载完成后，不会产生任何遥测数据或出站网络请求。

包含 Gradio 界面

一个网页界面会在localhost上打开，您可以直接与文档对话——无需自行搭建前端。

兼容 OpenAI 的 API

PrivateGPT 服务器也提供了类似 OpenAI 格式的 REST 接口，如果您希望将其集成到自家应用中，将非常有用。

支持的格式

PDF、DOCX、PPTX、MD、TXT、HTML、EPUB、CSV，以及通过底层 LlamaIndex 加载器支持的其他多种格式。

#先决条件

Python 3.11

PrivateGPT v2官方仅支持Python 3.11。使用3.12及以上版本时，部分依赖仍会出问题。

Poetry

该项目使用Poetry来管理依赖项，包含额外组件（ui、llms-ollama、embeddings-ollama、vector-stores-qdrant）。

Ollama 已安装并运行中

Ollama 守护进程可通过 http://localhost:11434 访问。如果尚未安装 Ollama，请先安装——安装过程需要 3 分钟。

至少 8 GB RAM

16 GB 内存用起来更宽裕。如果通过 Ollama 将 8B–9B Q4 模型加载到显存中，还需额外预留 5 到 7 GB 的 GPU 显存。

推荐GPU（可选）

RTX 3060 12 GB 或更高配置的显卡可运行 8B–14B 模型，响应时间也较为合理。没有 GPU 时，请使用 3B 模型（Granite 4.2 3B 或 Qwen 3.5 2B）。

#1. 安装 PrivateGPT v2

该项目托管在 GitHub 的 zylon-ai/private-gpt 仓库中。先克隆仓库，如果尚未安装 Poetry，就先安装它，然后安装依赖项，并选择与所用后端对应的可选依赖（extras）。

git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt

curl -sSL https://install.python-poetry.org | python3 -
# Ajoutez ~/.local/bin au PATH si ce n'est pas déjà fait

poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"

该命令安装四组可选依赖：Gradio 用户界面、用于 Ollama 的 LLM 客户端、用于 Ollama 的嵌入客户端，以及作为本地嵌入式向量数据库的 Qdrant。安装需要 5 至 15 分钟，具体取决于您的网络连接——其中包含大量科学计算依赖（numpy、scipy、transformers）。

#2. 配置 Ollama 作为LLM和嵌入向量的后端

PrivateGPT v2 使用位于 settings/ 目录中的 YAML 配置方案系统。通过环境变量 PGPT_PROFILES 启用 ollama 配置方案。

首先，拉取所需的两个模型：一个生成模型和一个嵌入模型。对于法语，Qwen 3.5 9B 是 2026 年合适的默认 LLM 选择（6.6 GB、256k 上下文、Apache 2.0 许可证），而 nomic-embed-text 仍是轻量级多语言嵌入模型的优秀选择。

# LLM de génération
ollama pull qwen3.5:9b

# Modèle d'embeddings (137M, ~280 Mo)
ollama pull nomic-embed-text

随后检查仓库中提供的 settings/settings-ollama.yaml 文件。它应指向正确的模型名称和 Ollama 的正确 URL :

llm:
  mode: ollama
  max_new_tokens: 512
  context_window: 8192

embedding:
  mode: ollama

ollama:
  llm_model: qwen3.5:9b
  embedding_model: nomic-embed-text
  api_base: http://localhost:11434
  embedding_api_base: http://localhost:11434
  request_timeout: 120.0

vectorstore:
  database: qdrant

qdrant:
  path: local_data/private_gpt/qdrant

#3. 启动服务器和界面

1. 01
   检查 Ollama 是否正在运行

   在终端中输入 "ollama list"。如果命令返回模型列表，说明守护进程已运行。否则，请在另一个终端中执行 "ollama serve"。
2. 02
   启用 ollama 配置方案

   在您将要启动 PrivateGPT 的终端中，导出变量 PGPT_PROFILES=ollama。这会指示项目在加载 settings.yaml 的基础上加载 settings-ollama.yaml，并用后者覆盖相应设置。
3. 03
   启动服务器

   在仓库根目录运行 "PGPT_PROFILES=ollama make run"。服务器在 8001 端口启动，Gradio 会在同一地址打开用户界面。
4. 04
   打开用户界面

   在浏览器中访问 http://localhost:8001。您将进入一个聊天界面，侧边栏可用于上传文档。

PGPT_PROFILES=ollama make run

首次启动时，您会在日志中看到 PrivateGPT 联系 Ollama，检查已声明的模型是否可用。如果缺少某个模型，服务器会停止并给出明确的信息——请使用 ollama pull 拉取缺失的模型，然后重新启动。

#4. 对文档进行索引

Gradio 界面提供一个“Ingest”选项卡，可将文件拖放到其中。后台的 PrivateGPT 会将每个文档切分成文本片段（默认每段约 1024 个 token，重叠部分为 200 个 token），通过 Ollama 计算嵌入向量，并将这些内容全部存储到 Qdrant 中。

PDF

通过 pypdf 提取的文本。扫描件（仅图像）的 PDF 未进行 OCR 处理——请在导入前使用如 ocrmypdf 等工具进行处理。

DOCX / PPTX

LlamaIndex 加载器原生支持这些格式。表格和列表会以纯文本形式保留。

Markdown / TXT / HTML

即时索引，这是实际 RAG 应用中表现最佳的格式。

CSV

每一行都会成为一个文本块。适用于 FAQ 数据库或业务数据摘录。

# Depuis la racine du repo private-gpt
python scripts/ingest_folder.py /chemin/vers/mes/documents \
  --watch  # surveille en continu les nouveaux fichiers

#具体业务应用场景

#人力资源：查询工资单和集体合同

典型场景：一个人力资源部门有200份以PDF格式归档的月度工资单，以及所在行业的集体协议（通常有100多页）。PrivateGPT v2让人力资源员工能够提出这样的问题：“杜邦女士在2025年的薪级系数是多少？”或“集体协议对于照顾生病子女的请假天数有哪些规定？”

推荐模型

Qwen 3.5 9B Q4 足以用于事实提取。若要对协议进行法律解释，可在显存足够的情况下改用 Mistral Small 24B（法语表现良好，14 GB）或 Qwen 3.8 27B（18 GB，262k 上下文）。

分割

对于工资单（1页），一个 chunk 即为一个文档；对于劳动合同，按章节（H2/H3 标题）分块效果优于按 token 分块

隐私

正是 PrivateGPT v2 发挥优势的场景：工资单绝不能通过云服务传输，即使在企业模式下也是如此。

#法律：分析一组合同

典型场景：一个法务部门，有几百份客户或供应商合同，格式为 PDF，其中有些是扫描件。常见问题包括：“哪些合同将在未来 6 个月内到期？”、“ACME 合同适用哪项终止条款？”、“哪些合同包含排他性条款？”。

预处理

在导入之前，请使用 ocrmypdf 对扫描件进行处理。没有 OCR 处理，这些 PDF 文件将无法被检索到。

推荐模型

若看重法语法律推理的质量，可选择 Mistral Small 24B 或 Qwen 3.8 27B。仅用于检索时，Qwen 3.5 9B 就足够了。

系统提示

设置系统提示，强制要求每次回复都引用合同名称和条款编号——否则模型往往会概括内容而不注明来源。

#会计：查询一组发票和对账单资料

典型场景：一家会计事务所希望查询某位客户的供应商发票和银行对账单资料集（PDF + CSV）。目标问题：“2025 年 Free Mobile 的发票总额是多少？”、“供应商 X 是否有尚未付款的发票？”。

需了解的限制

RAG 本身并不擅长聚合：它能检索相关段落，但面对大量数据时，无法完全准确地求和。对于要求严格准确性的分析，请将发票的 CSV 文件导入专用工具，并使用 PrivateGPT 获取定性背景信息。

推荐格式

会计的 CSV 文件会逐行进行索引——这有利于单条记录的检索，但不利于计算。若希望 LLM 能获得整体视图，请附上每月的综合 PDF 文件。

模型

与小型 3B 模型相比，Qwen 3.5 9B 在数字处理和表格阅读方面表现很强，甚至可以采用 Q8 量化版本（11 GB）。如果您有 RTX 4070 12 GB 或更高配置的显卡，这里默认推荐它。

#常见故障排除

启动时出现"Connection refused"

Ollama 守护进程未启动。请运行 "curl http://localhost:11434" 检查——您应当看到 "Ollama is running"。

响应非常缓慢

要么 Ollama 运行在 CPU 上（请使用 "ollama ps" 检查——PROCESSOR 列），要么您的 context_window 过大。建议将其降低至 4096 进行测试。

"Model not found"

settings-ollama.yaml文件中模型名称必须与"ollama list"命令列出的模型名称完全一致。请注意量化标签：qwen3.5:9b ≠ qwen3.5:9b-q8_0。

数据导入与查询时使用的嵌入向量不同

如果在导入后更换嵌入模型，需要重新索引。请删除 local_data/private_gpt/qdrant/ 目录并重新运行导入。

Gradio 界面无法访问

如果您在远程设备上运行，请使用命令 "PGPT_PROFILES=ollama python -m private_gpt" 启动，并在 settings.yaml 中修改 host 配置（server.host: 0.0.0.0）。

#深入了解

PrivateGPT v2 是本地文档 RAG（检索增强生成）的优秀入门选择，但它只是其中一个组件。以下是一些进一步拓展的方向：

无需编程即可使用 Open WebUI 或 AnythingLLM 实现 RAG

如果您觉得 PrivateGPT 安装起来较为繁琐（Poetry、Python 3.11），Open WebUI 提供的 RAG 体验与之相近，而且更容易通过 Docker 部署。

高性能的法语嵌入向量

nomic-embed-text 能满足基本需求，但 Solon 或 BGE-M3 等专门针对法语的模型，在法国法律或行政内容上的效果更好。

高级分块策略

对于结构化语料库，按章节分块（依据 Markdown 标题、DOCX 结构）远优于按固定 token 数分块——这是一种轻松提升相关性的方法。