手把手搭建本地教材知识库：从 Python 环境到向量索引，一个坑都不让你踩
公众号系列 · 第二期（共三期）上一期：[我把 748 页的软考教材喂给了本地 AI，现在查任何知识点只要 3 秒]下期预告：给知识库装上"大脑"——本地大模型 + 网页聊天界面
写在前面
上一期说了为什么做、做出来长什么样。这一期是纯干货：把搭建过程一步一步写出来，命令可以直接复制。
先说清楚，这一期的目标产物是检索版：问一句人话，3 秒返回教材页码和原文。不带大模型，不生成答案——那是第三期的事。
别小看这个检索版，它已经能解决"翻书翻到崩溃"的问题，而且普通办公电脑就能跑，不需要显卡。
一、先想清楚整个流程
动手之前，脑子里要有这张图：
教材 PDF → 提取文字 → 切成小块 → 变成向量 → 存进 FAISS 索引
↓
提问 → 问题也变成向量 → 索引里找最近邻 → 返回页码 + 原文
用到的东西就四样，全部免费开源：
| 组件 | 干什么用 |
|---|
| PyMuPDF | 从 PDF 里提取文字 |
| PaddleOCR | 扫描版 PDF 的文字识别（备用） |
| BGE-Large 中文模型 | 把文字变成向量（语义指纹） |
| FAISS | 向量检索，毫秒级找最近邻 |
二、环境准备（第一个坑就在这）
1. 装 Python 3.10，不要装新版
这是第一个坑，也是最容易犯的：不要装最新的 Python。
OCR 组件 PaddleOCR 对版本很敏感，Python 3.14 直接不兼容。老老实实用 3.10：
装完验证：
python--version
# 必须显示 Python 3.10.x，多了少了都不行
2. 建项目目录，创建虚拟环境
mkdirC:\zhangpc\local-rag-kag
cdC:\zhangpc\local-rag-kag
python-mvenvvenv
后面所有操作都用 venv 里的 Python，跟系统环境完全隔离。
3. 装依赖
# 基础依赖
.\venv\Scripts\pip.exeinstallPyMuPDFnumpytqdm
# 向量化 + 检索
.\venv\Scripts\pip.exeinstallsentence-transformersfaiss-cpu
# OCR（扫描版 PDF 才需要，纯文本版可以跳过）
.\venv\Scripts\pip.exeinstallpaddlepaddle==2.6.2paddleocr==2.9.1
pip 慢的话换清华镜像：
.\venv\Scripts\pip.exeinstall<包名>-ihttps://pypi.tuna.tsinghua.edu.cn/simple
4. 把教材 PDF 放好
C:\zhangpc\local-rag-kag\data\教材.pdf
三、一键构建知识库
脚本我已经写好（获取方式见文末），核心流程一条命令：
.\venv\Scripts\python.exescripts\rebuild_all.py
它会让你选模式：
怎么选？ 先跑快速模式。如果查询结果明显缺内容（说明你的 PDF 是扫描版，文字层是空的），再上 OCR。
构建完成后，cache/ 目录里会多出两个文件：
cache/faiss.index # 向量索引，748 页教材只有约 6MB
cache/metadata.json # 文字内容 + 页码对应表
整个知识库就这两个文件，拷到别的电脑上都能直接用。
四、查一下试试
.\venv\Scripts\python.exescripts\query.py--q"挣值管理的公式"
返回结果长这样：
📄 结果 1 | 第 358 页 | 相关度: 0.8923
挣值管理（EVM）中，成本偏差 CV = EV - AC……
不带 --q 参数直接运行，就进入交互模式，可以连续提问。
【截图占位：实际查询效果的命令行截图】
到这里，检索版就搭完了。如果你不急，到这已经够用。下面的部分是避坑大全，建议收藏，用到再翻。
五、五个坑，一个一个说
坑 1：OCR 跑着跑着进程没了
跑 748 页 OCR 要十几二十个小时。千万别在 IDE 里跑，也别开着终端窗口跑——IDE 会杀后台任务，关一下终端窗口进程就没了，电脑休眠也会断。
正确姿势是用 Windows 计划任务挂机：
$action=New-ScheduledTaskAction-Execute"cmd.exe"`
-Argument'/c "C:\zhangpc\local-rag-kag\venv\Scripts\python.exe C:\zhangpc\local-rag-kag\scripts\ocr_pages.py > C:\zhangpc\local-rag-kag\cache\ocr_run.log 2>&1"'`
-WorkingDirectory"C:\zhangpc\local-rag-kag"
Register-ScheduledTask-TaskName"RAG_OCR"-Action$action-Force
Start-ScheduledTask-TaskName"RAG_OCR"
同时把电源选项设成"永不休眠"。
坑 2：OCR 进度卡住不动
这是管道死锁：程序的报错输出把缓冲区塞满了，整个进程挂起，看起来就像卡死。
解法就藏在上面的命令里——> log 2>&1 把所有输出重定向到文件，不给缓冲区堵的机会。已经卡住的，杀进程重跑。
坑 3：十几小时的 OCR，中断了得重来？
不用。脚本每识别完一页就立刻写缓存（cache/ocr_pages/page_xxx.txt，一页一个文件）。中断后重新运行，会自动跳过已完成的页，从断点继续。
随时可以看进度：
# 已完成多少页
(Get-ChildItem"cache\ocr_pages\page_*.txt").Count
坑 4：中文路径报错
FAISS 底层是 C 代码，读写文件走 GBK 编码，路径里有中文可能直接炸。两个办法：
如果你自己写，记住这个点就行。
坑 5：模型下载失败
BGE 向量模型首次要下载约 1GB，从 huggingface.co 直连经常失败，甚至出现过 Python 报 SSL 错误但 curl 正常的怪事。
解法：用 curl 从国内镜像 hf-mirror.com 把模型文件手动下载下来，放到 models/bge-large-zh-v1.5/ 目录，脚本会优先用本地模型，全程无需联网。
六、搭完之后怎么用
日常就一个动作：
遇到不懂的概念 → query.py → 3 秒出结果 → 翻到对应页码精读
考前突击可以批量查：
Get-Contentquestions.txt|ForEach-Object{
.\venv\Scripts\python.exescripts\query.py--q"$_"
}七、现在还缺点什么
检索版有个明显的不足：它返回的是原文片段，不是人话答案。
问"数据库三范式分别是什么要求"，它给你三段原文，你得自己读、自己归纳。对备考来说够用，但体验上还差一口气。
所以第三期，我们给这个知识库装上大脑：
用一张 RTX 2080 Ti 22G 显卡，在本地跑 35B 参数的大模型
检索到原文后，让大模型读原文、组织成通顺的答案，页码出处照挂
再套一个网页聊天界面，像用 ChatGPT 一样用自己的教材
全程 0 元 API 费用，教材和问题都不出你的电脑。下期见。
上期回顾：为什么把 748 页教材喂给本地 AI下期预告：《给知识库装上大脑：2080 Ti 本地跑 35B 大模型 + 网页聊天界面》
