1. 为什么我要从零搭一个个人知识库问答机器人
手里攒了七八年的技术笔记、PDF 文档、网页剪藏和会议纪要，总量大概在 3000 多份，分散在好几个文件夹和笔记软件里。以前靠全文搜索还能凑合，但搜索的前提是我得记得住关键词。很多时候我脑子里只有一个模糊的问题，比如"之前那个处理时区转换的方案是怎么写的"，全文搜索根本帮不上忙。这就是我决定动手做一个个人知识库问答机器人的直接原因。
这个项目的核心目标很明确：把本地散落的文档喂给一个Agent，让它基于RAG（检索增强生成）的架构，用自然语言回答我的问题，并且给出答案的出处。技术选型上我用了LangChain做编排、FAISS做向量检索，整体跑在本地，不依赖外部服务。适合谁参考？如果你有一定的 Python 基础，想搞明白 RAG 到底是怎么跑起来的，或者你已经看过一堆概念但没真正落地过，那这篇内容应该能帮你少走弯路。
我先把结论摆出来：一个能用的个人知识库问答机器人，难点从来不在"调用大模型"这一步，而在于文档怎么切、向量怎么存、检索怎么召回、答案怎么溯源这四个环节。大模型 API 调用是整条链路里最简单的一环，真正决定效果的是前面那些看起来不起眼的工程细节。下面我按实际搭建的顺序，把每个环节的取舍和踩过的坑都摊开讲。
2. 文档加载与切分：决定问答质量的第一道关卡
2.1 我的文档类型盘点与加载器选择
动手写代码之前，我先花了一个下午把手里所有文档过了一遍，按格式分了类。这一步很多人会跳过，直接上来就写加载逻辑，结果跑到一半发现某种格式解析出来全是乱码。我的文档大致分这么几类：
| 文档类型 | 数量占比 | 加载方式 | 主要坑点 |
|---|---|---|---|
| Markdown 笔记 | 约 45% | 直接读取文本 | 代码块会被当正文切碎 |
| PDF 技术文档 | 约 25% | PDF 解析库 | 扫描版无文字层，解析为空 |
| 网页剪藏 HTML | 约 20% | HTML 解析提取正文 | 导航栏、广告混入正文 |
| 纯文本/日志 | 约 10% | 直接读取 | 编码不统一，有 GBK 混入 |
Markdown 和纯文本最好处理，直接读就行。PDF 是重灾区，我遇到的最大问题是扫描版 PDF 没有文字层，解析出来是空的。判断方法很简单：用解析库读一遍，如果某份 PDF 提取出的字符数远小于预期，基本就是扫描版。这类文档我最后是单独挑出来，要么手动转文字，要么直接放弃，不要指望 OCR 能完美还原技术文档里的代码和公式。
HTML 剪藏的问题在于正文提取。我一开始图省事直接读整个 HTML 的文本，结果检索出来的答案里经常混着"点击这里订阅""相关阅读"这种导航文字，非常影响体验。后来我改用正文提取的方式，只保留文章主体部分，效果立刻好了很多。
2.2 切分策略：为什么我放弃了固定长度切分
文档切分（Chunking）是 RAG 里最容易被低估的环节。我最初用的是最朴素的固定字符数切分，比如每 500 个字符切一块，块之间重叠 50 个字符。跑起来是能跑，但检索质量很差。原因很直观：固定长度切分会把一段完整的逻辑硬生生截断，比如一个函数的说明被切成两半，检索到上半段时，下半段的关键信息就丢了。
后来我换成了按语义结构切分，具体做法是：
- Markdown 文档按标题层级切，一级标题下的内容作为一个大块，如果超过阈值再按二级标题细分
- 普通文本按段落切，段落是最小的语义单元，尽量不跨段落切
- 代码块整体保留，绝不从中间切断
这里有个参数需要权衡：块的大小。块太小，检索精度高但上下文不足，模型回答时信息不够；块太大，检索时容易召回一堆无关内容，还会浪费 token。我实测下来，中文技术文档比较合适的范围是300 到 800 字符，具体取决于文档的信息密度。信息密度高的（比如 API 文档）可以小一点，叙述性的（比如教程）可以大一点。
还有一个细节是重叠区。块之间保留一定的重叠，是为了防止关键信息正好落在切分边界上被割裂。我一般设置 10% 到 15% 的重叠，比如块大小 500，重叠就设 50 到 75。重叠太多会导致重复内容变多，检索时同一段信息被召回好几次，反而干扰排序。
提示：切分参数没有万能值，一定要拿你自己的文档做小批量测试。我的做法是准备 20 个已知答案的问题，用不同的切分参数跑一遍，看哪个参数下召回的内容最完整，这个土办法比任何理论都管用。
2.3 元数据：让答案能溯源的关键
很多人做 RAG 只存文本内容，不存元数据，结果模型给出答案后你根本不知道它从哪来的。我在每个块上都附加了元数据，包括来源文件名、原始路径、块在文档中的位置、文档修改时间。这些信息在检索时不一定用得上，但在展示答案出处时是必需的。
元数据的另一个用处是过滤。比如我只想在某一个项目文件夹里搜索，就可以在检索时按路径前缀过滤，避免召回了其他项目的无关内容。这个功能在文档量大之后特别有用，相当于给检索加了一层范围限定。
3. 向量化与 FAISS 索引：把文本变成可检索的数字
3.1 嵌入模型的选择：本地还是调用
文本要能被检索，先得转成向量，这一步靠嵌入模型（Embedding Model）。选型上有两条路：调用外部嵌入接口，或者用本地模型。我最后选了本地模型，原因有三个：一是文档涉及个人笔记，不想往外传；二是本地模型没有调用次数限制，批量处理几千份文档不用担心费用；三是离线可用，断网也能跑。
本地嵌入模型的选择上，我优先考虑中文支持和模型体积的平衡。有些模型英文很强但中文拉胯，检索中文文档时召回率明显下降。我的建议是拿一段中文技术文档做测试，看不同模型生成的向量在相似度计算上是否合理——语义相近的句子相似度应该明显高于无关句子，如果区分度不明显，说明这个模型不适合你的场景。
嵌入维度也是个要考虑的点。维度越高，表达能力越强，但存储和计算成本也越高。个人知识库这个量级，几百到一千多维都够用，没必要追求超高维度。
3.2 FAISS 索引类型：我为什么先用最朴素的
FAISS是 Facebook 开源的向量检索库，它的核心优势是快，能在毫秒级从百万级向量里找到最相似的几个。FAISS 提供了多种索引类型，从最简单的暴力检索到各种近似检索。我一开始纠结要不要直接上高级索引，后来决定先用最朴素的扁平索引（Flat Index）。
理由是这样的：个人知识库的向量规模通常在几千到几万条，这个量级下暴力检索完全扛得住，一次查询也就几十毫秒。扁平索引的好处是结果精确，不会有近似检索的精度损失。等文档量涨到几十万条、查询明显变慢时，再考虑换成带量化的近似索引也不迟。过早优化索引类型，反而会因为近似检索的精度损失影响体验。
索引的持久化也很重要。FAISS 支持把索引存到磁盘，下次启动直接加载，不用重新对所有文档做嵌入。我实测下来，几千份文档重新嵌入要花十几分钟，而加载已有索引只要一两秒，这个差距在反复调试阶段非常关键。
3.3 增量更新：新增文档怎么处理
知识库不是一次建完就完事了，我每周都会新增笔记。如果每次新增都全量重建索引，既慢又浪费。我的做法是增量更新：维护一个已处理文档的记录，新增文档只做嵌入并追加到索引，删除文档则标记失效（FAISS 本身不直接支持删除，我用了一个有效位标记的方式绕过）。
这里有个坑要提醒：文档修改后要重新嵌入。我一开始只判断文件是否存在，结果改了内容的老文档不会被更新，检索出来的还是旧内容。后来改成用文件的修改时间加内容哈希来判断是否需要重新处理，这个问题才解决。
4. 检索与生成：Agent 编排的核心逻辑
4.1 检索策略：相似度检索够不够用
最基础的检索是向量相似度检索，把问题转成向量，在 FAISS 里找最相似的几个块。这个方式对语义匹配很有效，但有个明显短板：对精确关键词不敏感。比如我问"某个具体的函数名怎么用"，向量检索可能召回一堆语义相关但没提到这个函数名的内容。
我的解决方案是混合检索：向量检索和关键词检索各跑一遍，然后把结果融合。关键词检索用最朴素的方式就行，把问题里的关键词提取出来，在文本里做匹配。两路结果合并时，我给向量检索的结果更高权重，因为它对语义的理解更好，关键词检索作为补充。
检索返回的数量（Top-K）也需要调。K 太小，可能漏掉关键信息；K 太大，会引入噪声，还会让模型处理更长的上下文。我一般设 K 在 4 到 8 之间，配合一个相似度阈值，低于阈值的结果直接丢弃，避免把完全不相关的内容塞给模型。
4.2 用 LangChain 串起整条链路
LangChain在这个项目里扮演的是"胶水"的角色，把加载、切分、嵌入、检索、生成这几个环节串起来。它的价值在于提供了统一的抽象，比如文档加载器、文本切分器、向量存储接口，我不用自己从头写这些。
但 LangChain 也有让人头疼的地方：版本迭代快，API 经常变。我踩过的坑是照着半年前的教程写代码，结果一堆接口已经废弃了。我的建议是，遇到报错先去看当前版本的官方文档，不要死磕旧教程。另外，LangChain 的抽象层有时候会掩盖细节，比如它默认的切分参数可能不适合中文，需要手动覆盖。
整条链路的编排逻辑大致是这样：用户提问 → 问题向量化 → FAISS 检索相关块 → 把问题和检索到的上下文拼成提示词 → 交给大模型生成答案 → 附上来源。这个流程用 LangChain 的链式调用可以写得很清晰，但每一步的参数都要自己调，不能全用默认值。
4.3 提示词设计：让模型基于检索内容回答
提示词（Prompt）设计直接决定模型会不会"胡说"。RAG 的核心价值就是让模型基于检索到的内容回答，而不是凭自己的记忆瞎编。所以提示词里必须明确要求：只根据提供的上下文回答，如果上下文里没有相关信息，就直说不知道，不要编造。
我用的提示词结构大概是：先给一段系统指令，说明角色和回答规则；然后把检索到的文档块按相关度排序贴进去，每块标注来源；最后是用户的问题。这里有个细节，文档块之间要有清晰的分隔，否则模型可能把不同块的内容混在一起理解。
还有一个实用技巧：要求模型在答案里标注引用来源。比如答案里提到某个信息时，注明来自哪个文档。这样我一眼就能判断答案可不可信，也能顺着来源去核对原文。
5. 实测中暴露的问题与我的处理方式
5.1 答非所问：检索召回不准的排查
项目跑起来后，最先暴露的问题是答非所问。我问 A，它回答 B。排查下来，根因基本都在检索环节。我的排查链路是这样的：
- 先看检索召回了哪些块，如果召回的内容本身就答非所问，那问题在检索，不在生成
- 检查问题向量化是否正常，有时候问题太短或太口语化，向量表达不准
- 检查切分是否合理，如果关键信息被切碎，检索自然召回不到
- 检查嵌入模型是否适合中文，用相似度测试验证
我遇到过一次典型情况：问题里有个专业术语，但文档里用的是同义词，向量检索没匹配上。后来我在检索前加了一步查询改写，把用户问题里的口语化表达和同义词扩展一下，召回率明显提升。
5.2 上下文超长：token 超限怎么办
另一个常见问题是上下文超长。检索回来的块加起来超过了模型的上下文窗口，要么报错，要么被截断。我的处理方式是动态控制上下文长度：先按相关度排序，从最相关的块开始累加，累加到接近上限就停，保证最相关的信息一定在上下文里。
如果单个块本身就超长，那说明切分参数有问题，得回去调小块大小。还有一种情况是问题本身需要跨多个文档综合，这时候可以分两轮检索，第一轮先定位相关文档，第二轮在文档内部细查。
5.3 幻觉：模型编造不存在的内容
即使有检索内容，模型偶尔还是会编造。我遇到过模型把检索到的两个不相关事实强行关联，得出一个文档里根本没有的结论。对付幻觉，我的经验是：
- 提示词里反复强调"只基于上下文"，并给出"不知道"的示例
- 降低生成温度（Temperature），让输出更保守
- 要求标注来源，没有来源支撑的句子一眼就能看出来
温度这个参数值得说一下。温度越高，输出越多样但也越容易跑偏；温度越低，输出越稳定保守。知识库问答这种场景，我一般把温度设得很低，宁可答案平淡一点，也不要它自由发挥。
6. 关于 Agent 化的一些思考
6.1 从固定链路到 Agent 的差别
我最初做的是一个固定链路的问答系统：问题进来，检索，生成，结束。后来我尝试把它往Agent方向改，核心差别在于 Agent 能自主决定下一步做什么。比如问题比较复杂时，Agent 可以先判断需不需要检索，检索一次不够可以再检索一次，甚至可以把问题拆成几个子问题分别查。
这个能力在简单问答上体现不出优势，但遇到"对比 A 和 B 两个方案的差异"这类问题时，Agent 可以分别检索 A 和 B 的资料再综合，效果比一次性检索好很多。不过 Agent 也带来了新的复杂度：决策步骤多了，出错的机会也多了，而且调试起来更麻烦，因为每一步的决策都是模型自己做的，不像固定链路那样可控。
6.2 个人知识库场景下 Agent 的边界
我的体会是，个人知识库这个场景，Agent 化要适度。不是所有问题都需要 Agent 的多步推理，大部分问题一次检索加一次生成就够了。盲目上 Agent，只会让系统变慢、变复杂，还增加不确定性。
我现在的做法是分层：简单问题走固定链路，快且稳；复杂问题才触发 Agent 的多步流程。判断简单还是复杂，可以先用一个轻量的分类步骤，或者干脆让用户自己选。这个取舍没有标准答案，取决于你的问题分布——如果你的问题大多是"某个东西是什么"，固定链路足够；如果经常需要综合对比、多跳推理，那 Agent 才有价值。
6.3 并发与性能：个人场景要不要考虑
热词里有个"AI Agent 怎么扛并发"，我一开始觉得个人知识库根本用不上。但实际用下来发现，并发问题在个人场景也会出现，只是规模小。比如我一边在网页端提问，一边在脚本里批量测试，两个请求同时打到嵌入模型上，如果模型不是线程安全的，就会出问题。
我的处理比较简单：给嵌入和检索加个简单的锁，保证同一时间只有一个请求在跑。个人场景下这点延迟完全可以接受，没必要上复杂的并发架构。等真的有多人使用需求时，再考虑把嵌入服务独立出来做并发处理也不迟。
7. 我踩过的几个具体坑和绕行方案
7.1 编码问题：GBK 文档导致的解析失败
我有一批早期的笔记是 GBK 编码的，读取时直接报错。处理方式是先探测编码再读取，不要假设所有文件都是 UTF-8。探测可以用现成的编码检测库，读出来之后统一转成 UTF-8 再往下走。这个坑不大，但如果不处理，整批文档都会被跳过。
7.2 索引与文档不同步
前面提过，我一开始没做增量更新的判断，导致改了内容的文档检索出来还是旧的。后来我加了一个文档指纹机制：用文件路径加修改时间加内容哈希生成一个指纹，指纹变了才重新处理。这个机制还顺带解决了重复文档的问题——内容完全相同的文档只处理一次。
7.3 检索结果排序不稳定
FAISS 返回的相似度分数在不同查询之间不完全可比，导致有时候排序看起来很奇怪。我的处理是在检索后加一层重排，用一个更精细的相似度计算对候选结果重新排序。重排这一步会增加一点延迟，但对最终答案质量的提升很明显，值得。
8. 这套东西还能怎么扩展
跑通基础版本之后，我陆续加了一些扩展。一个是多知识库隔离，把工作笔记和个人笔记分成两个独立的索引，检索时指定用哪个，避免串味。另一个是对话记忆，让机器人记住上下文，支持追问，比如我问完一个问题后接着问"那它的缺点呢"，它能知道"它"指的是什么。
再往深了走，可以考虑知识图谱和 RAG 的结合。纯向量检索擅长语义匹配，但对实体之间的关系无能为力。如果能把文档里的实体和关系抽出来建成图谱，检索时就能做多跳推理，回答" A 和 B 通过什么关联"这类问题会强很多。不过这属于进阶方向，个人知识库这个量级，先把基础 RAG 打磨好，收益比盲目上图谱大得多。
最后分享一个我自己的使用习惯：我会定期拿一批新问题去测这个机器人，把答得不好的案例记下来，分析是检索的问题还是生成的问题，然后针对性调参。这个过程有点像养一个助手，用得越多，调得越准。知识库问答机器人不是搭完就完事的项目，它是一个需要持续打磨的工具。
