PrivateGPT 知识库配置：把本地文档变成可问答的索引
PrivateGPT 知识库配置的目标很明确：让本地文档被切分、向量化并写入索引，之后提问时能检索到相关内容。
整个流程在 PrivateGPT 项目目录内完成，前提是 Python 环境和模型文件已经就绪。
如果还没装过 PrivateGPT，先按官方仓库的安装说明完成依赖安装，再回到本文做知识库配置。
先确认三样东西就位
配置失败多数不是代码问题，而是模型路径或文档目录没对上。
动手前检查以下三项：
- 模型文件：PrivateGPT 需要本地 LLM 和嵌入模型。确认模型文件已下载到磁盘，并记住绝对路径。不同版本对模型格式要求不同，以你所用版本的
settings.yaml或.env示例为准。 - 文档目录：默认源文档放在
source_documents目录。把 PDF、TXT、Markdown 等要问答的文件放进去，避免混入无关大文件。 - 运行环境：在项目根目录激活虚拟环境，执行
python --version确认 Python 版本符合项目要求；执行pip list | grep -i private确认依赖已安装。
建议先放一份小文档做首次测试，确认链路通了再批量导入。
修改配置：路径和参数要对上
PrivateGPT 的配置入口通常是项目根目录的 .env 文件（部分版本用 settings.yaml）。
用编辑器打开后，重点核对以下几项：
# 示例：查看当前配置中的模型与文档路径
cd ~/private-gpt
grep -E "MODEL|EMBEDDING|SOURCE" .env需要关注的配置项一般包括：
PERSIST_DIR：向量库持久化目录，保持默认或改成你有写权限的路径。MODEL_PATH：本地 LLM 文件路径，必须是实际存在的文件，不能用相对路径猜。EMBEDDINGS_MODEL或嵌入模型相关项：指向嵌入模型文件或模型名。SOURCE_DOCUMENTS：源文档目录，默认source_documents。
改完后保存，不要急着导入大文件。
先确认路径存在：
ls -lh "$MODEL_PATH"
ls source_documents/如果命令报错，说明路径写错或文件没下载完整，先解决路径问题再继续。
执行 ingest 生成知识库索引
配置确认后，在项目根目录运行导入命令。
不同版本命令名称可能略有差异，常见形式如下：
python ingest.py或者使用项目提供的入口：
python -m private_gpt.ingest运行后观察终端输出。
正常流程会依次出现：读取文档、切分文本、加载嵌入模型、写入向量库。
首次运行需要加载模型，耗时取决于机器性能，不要在中途强制中断。
预期结果是 PERSIST_DIR 指向的目录下出现索引文件，且终端没有报错退出。
可以用以下命令检查：
ls -lh "$PERSIST_DIR"如果目录为空或命令提前退出，先看完整报错，常见原因包括模型文件损坏、内存不足、文档格式无法解析。
用提问验证检索是否生效
索引建好后，启动问答入口验证。
常见方式是运行查询脚本：
python private_gpt.py进入交互后，问一个只有你文档里才有的细节，例如某份 PDF 里的专有名词或数字。
判断标准不是回答是否流畅，而是回答中是否出现了文档里的具体信息。
如果回答明显在编造，先检查：
- 文档是否确实在
source_documents下且被 ingest 读取； - 提问是否和文档内容相关；
- 嵌入模型和 LLM 是否指向了正确文件。
可以重新执行一次 ingest，观察日志里列出的文件数量是否和预期一致。
容易踩坑的几个地方
模型路径写相对路径。
PrivateGPT 从不同工作目录启动时相对路径会失效，配置里优先写绝对路径。
文档太大导致切分后检索不到。
超长文档切分后单块信息密度低，提问容易匹配不到关键段。
建议把大文档拆成主题明确的多个文件再导入。
内存不足。
本地 LLM 和嵌入模型同时加载对内存要求较高。
如果 ingest 或查询时进程被系统杀掉，先换小模型测试，确认流程通了再换大模型。
重复 ingest 前没清理旧索引。
部分版本重复导入会追加内容，导致索引膨胀。
需要重建时，先备份并清空 PERSIST_DIR，再重新执行 ingest。
什么时候需要重建索引
文档内容更新后，旧索引不会自动同步。
只要源文档有增删改，就需要重新执行 ingest。
如果只是换提问方式，不需要重建。
判断依据很简单：回答里出现已删除文档的内容，或者新加的文档问不到，就说明该重建了。
PrivateGPT 知识库配置本身不复杂，关键是路径、模型和文档三者对齐，再用一个具体问题验证检索结果。
按上面的顺序检查一遍，大多数配置问题都能定位到具体环节。
