中级 18 分钟RAG

PrivateGPT v2:文档聊天机器人,100% 私密

PrivateGPT v2:100% 保护隐私的文档聊天机器人

PrivateGPT v2 是一个 100% 私有的文档聊天机器人,用于与 PDF、Word、Markdown 文件交互,且没有任何一个字节离开机器。v2 版本放弃了其内置的 LLM 引擎,转而依赖 Ollama:我们保留了高质量 RAG 的优势,受益于通过 Ollama 可用的所有模型,并极大地简化了技术栈。本指南涵盖安装、连接 Ollama 以及三个具体的业务场景(人力资源、法律、会计)。

作者: Mohamed Meguedmi·更新于 2026-08-27·已在 Windows、macOS 和 Linux 上测试

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

需求很典型:能够用自然语言向内部文档语料库(合同、工资单、发票、会议纪要)提问,同时不将这些数据发送给 OpenAI、Anthropic 或 Google。这正是 PrivateGPT 自 2023 年首次发布以来一直致力于实现的目标。

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

100% 本地
所有内容都在你的机器上运行。模型下载完成后,不会有任何遥测,也不会发起任何出站调用。
包含 Gradio UI
一个网页界面会在localhost上打开,您可以直接与文档对话——无需自行搭建前端。
兼容 OpenAI 的 API
PrivateGPT 服务器还提供了接近 OpenAI 格式的 REST 端点,适合在你想将其接入自研应用时使用。
支持的格式
PDF、DOCX、PPTX、MD、TXT、HTML、EPUB、CSV,以及通过底层 LlamaIndex 加载器支持的其他多种格式。
i
双模块架构
PrivateGPT v2 = RAG 流水线(分块、嵌入、向量存储、检索、提示词组装)+ Gradio UI。Ollama = LLM 推理引擎。两者通过本地 HTTP 在端口 11434 上通信。

#先决条件

打造专属本地 RAG 的完整套件。

借助我们的经验和引导式路径,搭建你的本地 RAG,用你自己的文档工作。

  • 在线空间,终身可用
  • PDF + 文件
  • 30 天内退款
Python 3.11
PrivateGPT v2官方仅支持Python 3.11。使用3.12及以上版本时,部分依赖仍会出问题。
Poetry
该项目使用 Poetry 通过 extras(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)。
→
没有安装 Ollama?
请先按照我们针对您所用操作系统的 Ollama 安装指南进行安装,然后再回到这里。PrivateGPT v2 的前提是 "ollama run" 命令已经能够正常运行。

#1. 安装 PrivateGPT v2

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

克隆仓库
git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt
安装 Poetry(如尚未安装)
curl -sSL https://install.python-poetry.org | python3 -
# Ajoutez ~/.local/bin au PATH si ce n'est pas déjà fait
安装 PrivateGPT,并启用 Ollama 可选依赖项
poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"

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

!
Python 3.12 和 3.13:需谨慎
撰写本文时,某些原生依赖项(尤其是 llama-index 和 tokenizers 组件)适用于 Python 3.12 及更高版本的构建产物尚未全部发布。如果 Poetry 报编译错误,请创建专用的 Python 3.11 虚拟环境:"pyenv install 3.11.9 && pyenv local 3.11.9"。

#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 仍是轻量级多语言嵌入模型的优秀选择。

在 Ollama 中准备模型
# 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:

settings/settings-ollama.yaml
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
→
上下文窗口
context_window: 8192 是开始使用 Qwen 3.5 9B 时的合理折中(该模型的上下文窗口最高可达 256k)。如果 GPU 的显存更多,可以改为 16384 或 32768,以处理更长的文档,而不必将文档切得过碎。注意:KV 缓存占用的显存会迅速增加。

#3. 启动服务器和 UI

  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 数据库或业务数据摘录。
!
需要提前考虑索引时间
文档导入时会调用 Ollama,逐份文档计算嵌入向量。仅使用 CPU 时,每页 PDF 预计需要约 5 秒;使用 GPU 时,几乎可以瞬间完成。如果要导入 500 份 PDF,请预留充足时间,并通过 API 批量处理,而不是拖拽上传。
通过 CLI 脚本批量摄取
# 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 标题)进行 chunking,比按 token 进行 chunking 效果更好。
隐私
这正是 PrivateGPT v2 发挥作用的场景:工资单绝不应经过云服务,包括“企业”模式。

#法律:分析一组合同

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

预处理
在摄取之前对扫描件运行 ocrmypdf。没有 OCR,这些 PDF 对检索来说是不可见的。
推荐模型
若看重法语法律推理的质量,可选择 Mistral Small 24B 或 Qwen 3.8 27B。仅用于检索时,Qwen 3.5 9B 就足够了。
系统提示词
设置系统提示,强制要求每次回复都引用合同名称和条款编号——否则模型往往会概括内容而不注明来源。
i
始终核查来源
PrivateGPT v2 的 Gradio 界面会在回答下方显示检索到的片段。对于严肃的法律用途,请将回答视为线索,并始终核查源文片段——RAG 是辅助检索,而不是自动生成的法律意见。

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

典型场景:一家会计事务所希望查询某位客户的供应商发票和银行对账单资料集(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 UI 无法访问
如果使用远程计算机,请使用 "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 部署。
高性能法语 Embeddings
nomic-embed-text 能满足基本需求,但 Solon 或 BGE-M3 等专门针对法语的模型,在法国法律或行政内容上的效果更好。
高级分块策略
对于结构化语料库,按章节分块(依据 Markdown 标题、DOCX 结构)远优于按固定 token 数分块——这是一种轻松提升相关性的方法。
这份指南对您有帮助吗?

有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。