手把手搭建本地教材知识库：从 Python 环境到向量索引，一个坑都不让你踩

公众号系列 · 第二期（共三期）上一期：[我把 748 页的软考教材喂给了本地 AI，现在查任何知识点只要 3 秒]下期预告：给知识库装上"大脑"——本地大模型 + 网页聊天界面

写在前面

上一期说了为什么做、做出来长什么样。这一期是纯干货：把搭建过程一步一步写出来，命令可以直接复制。

先说清楚，这一期的目标产物是检索版：问一句人话，3 秒返回教材页码和原文。不带大模型，不生成答案——那是第三期的事。

别小看这个检索版，它已经能解决"翻书翻到崩溃"的问题，而且普通办公电脑就能跑，不需要显卡。

一、先想清楚整个流程

动手之前，脑子里要有这张图：

教材 PDF → 提取文字 → 切成小块 → 变成向量 → 存进 FAISS 索引
                                              ↓
提问 → 问题也变成向量 → 索引里找最近邻 → 返回页码 + 原文

用到的东西就四样，全部免费开源：

二、环境准备（第一个坑就在这）

1. 装 Python 3.10，不要装新版

这是第一个坑，也是最容易犯的：不要装最新的 Python。

OCR 组件 PaddleOCR 对版本很敏感，Python 3.14 直接不兼容。老老实实用 3.10：

• 下载地址：https://www.python.org/downloads/release/python-31011/

• 安装时一定勾选 "Add Python to PATH"

装完验证：

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 自带的文字层，3 分钟搞定

• 高精度模式：OCR 逐页识别，748 页要跑 15~30 小时

怎么选？ 先跑快速模式。如果查询结果明显缺内容（说明你的 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 编码，路径里有中文可能直接炸。两个办法：

• 项目路径尽量纯英文（我的 C:\zhangpc\local-rag-kag 没问题，但 PDF 文件名"教材.pdf"在读写索引时绕了一下）

• 脚本里已经做了规避：在 Python 层读写二进制流，再喂给 FAISS，不让 C 代码碰路径

如果你自己写，记住这个点就行。

坑 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 大模型 + 网页聊天界面》