1. 为什么我要从零搭一个个人知识库问答机器人我手头攒了大概七八年的技术笔记、项目复盘、会议纪要散落在各种 Markdown 文件、PDF 和网页剪藏里。以前靠全文搜索还能凑合但搜索的前提是我得记得住关键词。很多时候我只记得“那个关于缓存穿透的解决方案”具体叫什么名字早忘了搜出来的东西驴唇不对马嘴。这就是我动手做这个 Agent 的直接动机——我要的是一个能听懂人话、能理解语义、能帮我从一堆杂乱文档里把答案捞出来的东西。这个项目本质上是一个RAG检索增强生成驱动的个人知识库问答机器人。说人话就是我把自己的文档喂给它它建好索引之后我用自然语言提问它先从我的文档里找到最相关的片段再让大模型基于这些片段组织出答案。它解决的核心问题是“知识检索的语义化”和“答案生成的自动化”适合所有手里有大量私有文档、又不想每次翻半天的人。不管你是刚接触 Agent 和 RAG 的新手还是已经用过一些现成工具但想搞清楚底层怎么跑的老手这篇内容都能给你一套可以直接抄作业的方案。我选择自己搭而不是直接用现成产品原因有三个。第一个人知识库涉及隐私文档不想上传到别人的服务器第二现成产品的检索策略和分块逻辑是黑盒遇到效果不好的情况没法调第三自己搭一遍才能真正理解 RAG 的瓶颈在哪后面做更复杂的 Agent 项目心里有底。整个方案我跑通并稳定用了几个月下面把设计思路、关键细节、实操过程和踩过的坑全部摊开讲。2. 整体架构设计与技术选型思路2.1 为什么是 RAG 而不是微调一开始我也纠结过要不要走微调路线。毕竟热词里“大模型微调”“大模型微调实战”一直很火。但冷静下来分析微调解决的是“让模型学会某种风格或特定任务格式”它并不擅长“记住我文档里的具体事实”。你拿几百篇笔记去微调模型顶多学到你写笔记的语气问它某个具体参数是多少它照样编。而且微调成本高、迭代慢文档一更新就得重新训。RAG 的逻辑完全不同文档存在外部向量库里模型每次回答前先去检索。文档更新只需要重新索引那部分不用动模型。对于个人知识库这种“内容频繁增补、事实性要求高”的场景RAG 是明显更合理的选择。微调可以作为后续补充比如让模型输出更贴合我的表达习惯但检索这件事必须交给 RAG。2.2 核心组件拆解整套系统我拆成四个核心模块每个模块的选型都经过实际对比。文档加载与分块这是最容易被低估的环节。我试过直接把整篇文档塞进去结果检索出来的片段太长模型抓不住重点也试过切得太碎一句话被切成三段语义直接断了。最后我采用的是按语义段落切分加滑动窗口重叠的策略具体参数后面细讲。向量化与向量库Embedding 模型负责把文本转成向量向量库负责存储和相似度检索。Embedding 模型我选的是本地可跑的中文效果较好的开源模型向量库用的是轻量级的本地方案不依赖外部服务数据全在自己机器上。检索与重排单纯靠向量相似度检索有个问题——它有时候会把“看起来像但实际不相关”的片段排前面。所以我加了一层重排先用向量召回一批候选再用重排模型精排把真正相关的顶上来。生成与 Agent 编排最后一步是把检索到的上下文和用户问题一起交给大模型生成答案。这里我用了一个轻量的 Agent 框架来编排整个流程让“检索—判断—生成”形成一个可控的链路而不是一次性把东西全丢给模型。2.3 技术选型对比表环节候选方案最终选择选择理由文档解析纯文本解析 / 通用文档解析库通用文档解析库能处理 PDF、Markdown、网页多种格式分块策略固定长度 / 语义段落 / 递归切分语义段落重叠保留语义完整性减少断句Embedding在线API / 本地开源模型本地开源模型隐私可控无调用成本向量库云端服务 / 本地轻量库本地轻量库数据不出本机部署简单重排无重排 / 交叉编码器重排交叉编码器重排显著提升Top结果相关性生成模型在线大模型 / 本地部署在线大模型API生成质量高个人用量成本可接受编排框架手写流程 / Agent框架Agent框架链路清晰便于扩展工具这个选型不是拍脑袋定的是我在实际跑的过程中反复调整出来的。比如一开始为了省事想全用在线 API结果发现 Embedding 调用量一大成本就上来了而且文档内容要传到外部心里不踏实所以 Embedding 换成了本地。生成环节因为对质量要求高本地小模型效果确实差一截就保留了在线 API。3. 核心细节解析与实操要点3.1 文档分块决定成败的第一步分块这件事我踩的坑最多。最开始我用固定长度切比如每 500 个字符一刀切。结果一篇讲数据库索引的笔记正好在“B树的结构是”这里被切断后半句跑到下一个块里去了。检索的时候用户问“B树结构”召回的是前半块模型看到的是半句话回答自然残缺。后来我改成按语义段落切优先在标题、空行、句号这些自然边界处断开。具体做法是先按 Markdown 标题层级切大块再在每个大块内按段落切如果某个段落还是太长再按句子切。同时加一个重叠窗口让相邻块之间有 10% 到 15% 的内容重叠这样即使边界处有信息也不会完全丢失。提示重叠比例不要太高否则向量库里会有大量重复内容检索时容易召回一堆相似的块反而稀释了有效信息。我实测 10% 到 15% 是比较舒服的区间。还有一个细节是块的长度。太短比如 100 字语义不完整太长比如 2000 字检索精度下降。我最后定在 300 到 500 字之间具体根据文档类型微调。技术笔记偏短叙事类文档偏长。3.2 Embedding 模型的选择与本地部署Embedding 模型的作用是把文本转成高维向量让语义相近的文本在向量空间里距离更近。我对比过几个中文效果不错的开源模型最后选了一个在中文语义相似度任务上表现稳定的。部署方式很简单用本地推理框架加载模型暴露一个本地接口索引和查询都走这个接口。这里有个关键点索引用的 Embedding 模型和查询用的必须是同一个。我见过有人索引时用 A 模型查询时换了 B 模型结果检索效果一塌糊涂。因为不同模型生成的向量空间不一样混用等于拿中文词典去查英文单词。本地部署的另一个好处是批量索引快。我几千个文档块本地模型跑一遍也就几分钟换成在线 API 得考虑限流和费用。而且本地模型没有网络延迟查询响应基本在毫秒级。3.3 向量库的搭建与索引策略向量库我选的是本地轻量级方案支持持久化存储和增量更新。建库的时候有几个参数需要调距离度量我用的是余弦相似度因为文本向量的方向比长度更重要。索引类型数据量小的时候用扁平索引就行召回率最高数据量上万之后可以换成近似索引牺牲一点召回率换速度。持久化一定要开持久化否则每次重启都要重新索引浪费时间。增量更新是我特别看重的一点。我的笔记是持续在写的不可能每次加一篇就全量重建索引。所以我在流程里做了判断如果文档是新增的就只索引新增部分如果文档被修改了就先删掉旧块再索引新块。这个逻辑用文档 ID 加内容哈希来实现改动过的文档哈希会变就能识别出来。3.4 重排环节把真正相关的顶上来向量检索有个天然缺陷它算的是整体语义相似度有时候一个块里大部分内容不相关但恰好有一句话和问题很像整体相似度就被拉高了。反过来一个块整体都在讲相关问题但没有哪句话和问题字面接近反而可能排后面。重排就是来解决这个问题的。它的原理是把“问题候选块”成对输入一个交叉编码器让模型直接判断这个块对这个问题到底有多相关。这个计算比向量相似度慢所以只对向量召回的前 N 个候选做重排比如前 20 个重排出前 5 个。实测下来加了重排之后答案的准确率有明显提升尤其是那些问题表述和文档表述不一致的情况。注意重排模型也要选中文效果好的而且要和 Embedding 模型配合调。我试过重排后反而变差的情况原因是重排模型对某些领域术语不敏感把相关块排掉了。所以重排后最好保留一个兜底策略比如重排结果和原始向量结果做加权融合。3.5 生成环节的提示词设计检索到相关块之后最后一步是让大模型基于这些块回答问题。这里的提示词设计直接决定答案质量。我的提示词结构是这样的系统角色设定明确告诉模型它是一个基于给定资料回答问题的助手。上下文注入把检索到的块按相关性排序后拼接进去每个块标注来源。回答约束要求模型只基于给定资料回答资料里没有的信息不要编如果资料不足以回答就明确说“根据现有资料无法确定”。引用要求让模型在答案里标注信息来自哪个块方便我回溯核对。这个约束非常重要。不加约束的话模型很容易用自己的先验知识去补全看起来回答得很流畅实际上掺杂了它自己编的内容。对于个人知识库这种要求事实准确的场景宁可它说“不知道”也不要它编。4. 完整实操流程与关键环节实现4.1 环境准备与依赖安装先把基础环境搭起来。我用的是 Python 生态主要依赖包括文档解析库、Embedding 推理框架、向量库客户端、Agent 编排框架。安装的时候建议用虚拟环境避免和系统里的其他包冲突。python -m venv venv source venv/bin/activate pip install document-parser embedding-runtime vector-db agent-framework这里不写具体包名是因为不同版本迭代快你按自己选型的实际包名装就行。关键是版本要匹配尤其是 Embedding 模型和推理框架的版本不匹配会报各种奇怪的错。4.2 文档加载与预处理我写了一个统一的加载器根据文件扩展名走不同的解析分支。Markdown 直接读文本PDF 用解析库抽文字网页剪藏先转成 Markdown 再读。解析完之后做一轮清洗去掉多余空行、统一标点、把连续空格压成一个。def load_document(path): ext path.suffix.lower() if ext .md: text path.read_text(encodingutf-8) elif ext .pdf: text parse_pdf(path) elif ext .html: text html_to_markdown(path) else: return None return clean_text(text)清洗这一步别偷懒。我一开始没做清洗结果 PDF 里抽出来的文字带一堆换行和页眉页脚分块之后全是噪音检索效果很差。后来加了清洗规则把重复出现的页眉页脚模式识别出来删掉效果立刻好转。4.3 分块与向量化入库分块函数我按前面说的语义段落加重叠来实现。核心逻辑是递归切分先按标题切再按段落切再按句子切直到每块都在目标长度内。def split_text(text, max_len500, overlap50): paragraphs text.split(\n\n) chunks [] current for para in paragraphs: if len(current) len(para) max_len: current para \n\n else: if current: chunks.append(current.strip()) current para \n\n if current: chunks.append(current.strip()) # 加重叠 overlapped [] for i, chunk in enumerate(chunks): if i 0: prev_tail chunks[i-1][-overlap:] chunk prev_tail chunk overlapped.append(chunk) return overlapped向量化就是把每个块过一遍 Embedding 模型拿到向量后连同原文、来源、块序号一起写进向量库。这里我建议给每个块生成一个唯一 ID用“文档路径块序号”的格式方便后续更新和删除。4.4 检索链路实现检索的时候先把用户问题用同一个 Embedding 模型转成向量去向量库召回 Top 20。然后把这 20 个候选和问题一起送进重排模型拿到精排后的 Top 5。最后把这 5 个块的原文拼成上下文。def retrieve(query, top_k5): query_vec embed(query) candidates vector_db.search(query_vec, top_n20) reranked rerank(query, candidates) return reranked[:top_k]这里有个实操细节召回数量不要设太小。我一开始只召回 5 个直接重排结果有时候真正相关的块在向量排名第 8根本没进重排环节。后来改成召回 20 个再重排召回率明显提升。代价是重排计算量增加但个人知识库这个量级完全扛得住。4.5 Agent 编排与生成Agent 编排这块我用框架把整个流程串起来。核心是一个“检索工具”加一个“生成节点”。用户提问后Agent 先调用检索工具拿到上下文再把上下文和问题一起交给生成节点。def answer(query): context_blocks retrieve(query) context \n\n.join([b.text for b in context_blocks]) prompt build_prompt(query, context) response llm.generate(prompt) return response提示词模板我单独抽出来管理方便调优。模板里明确写了“只基于以下资料回答”“资料不足时说明无法确定”“标注信息来源”。这几条约束加上之后答案的可靠性提升非常明显。4.6 参数选择与计算过程分块长度和重叠比例这两个参数我是这么定的。先统计我所有文档的段落长度分布发现大部分段落在 200 到 400 字之间。所以块长度定在 500 字能容纳一个完整段落加一点上下文。重叠比例定在 10%也就是 50 字刚好是一两句话的长度能在边界处保留语义衔接。召回数量 20 和重排后 5 这两个数是我做了一轮小规模评测定下来的。我准备了 30 个问题人工标注了每个问题的正确答案在哪些块里然后测不同召回数量下的召回率。召回 20 个的时候正确答案基本都在候选里了再往上加召回率提升很小但重排耗时线性增长。重排后取 5 个是因为生成模型的上下文窗口有限5 个块大概 2500 字加上问题和提示词控制在合理范围内。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是最常见的问题。排查顺序我一般是这样的先看分块是不是把相关内容切散了如果是调整分块参数再看 Embedding 模型是不是不适合你的领域如果是换一个在你领域数据上表现更好的模型最后看是不是需要加或调重排。我遇到过一次典型情况问“缓存雪崩的解决方案”检索出来的全是“缓存穿透”的内容。原因是这两个概念在我的笔记里经常出现在同一篇文档里向量相似度区分不开。后来加了重排重排模型能更好地区分这两个概念的细微差别问题就解决了。5.2 答案里出现资料中没有的内容这是模型幻觉。解决办法是在提示词里加强约束并且降低生成模型的“创造性”参数。我一般把温度调到很低让模型尽量保守地基于资料回答。另外要求模型标注来源也有帮助因为一旦要求标注模型就不太敢编了编了它自己都对不上来源。5.3 索引更新后检索结果变差有一次我批量更新了一批文档更新完发现检索效果反而下降了。排查后发现是旧块没删干净新块和旧块同时存在检索时召回了一堆过时的内容。后来我在更新逻辑里加了“先按文档 ID 删除旧块再插入新块”的步骤问题解决。所以增量更新一定要处理好删除不能只加不删。5.4 常见问题速查表问题现象可能原因排查方向解决办法检索结果不相关分块不合理/模型不匹配检查分块边界和模型调分块参数或换模型答案含资料外内容提示词约束不足检查提示词和温度加强约束、降低温度更新后效果变差旧块未清理检查向量库块数量更新前先删旧块响应慢召回数量过大检查召回和重排参数降低召回数量答案残缺分块切断语义检查边界处内容增加重叠比例重复召回相似块重叠比例过高检查块间相似度降低重叠比例5.5 独家避坑技巧第一个技巧先小规模验证再全量索引。我一开始直接把几千个文档全索引了跑完发现效果不好又得全量重来。后来改成先拿 20 篇文档做小规模测试调好参数再全量跑省了大量时间。第二个技巧保留原始块和重排结果的映射。调试的时候我会把每次检索的原始召回列表和重排后列表都打日志这样效果不好的时候能直接看到是召回阶段的问题还是重排阶段的问题。第三个技巧定期做检索评测。我每个月会抽 20 个问题人工看检索结果对不对。这样能及时发现文档更新或模型变化带来的效果波动不至于等到用的时候才发现不好使。第四个技巧文档来源要标注清楚。我在每个块里都存了来源路径和块序号生成答案时让模型带上来源。这样我核对答案的时候能直接定位到原文也方便发现哪些文档质量差、需要整理。6. 后续可扩展的方向这套东西跑通之后我发现可扩展的地方很多。比如可以加一个“多轮对话”能力让 Agent 记住上下文支持追问。也可以加“工具调用”让 Agent 在检索不到的时候去查外部资料。还可以把图片和表格也纳入索引做多模态检索。不过这些都是后话核心的 RAG 链路先跑稳后面加东西才有意义。我个人在实际操作中的体会是RAG 这东西看起来简单真正决定效果的全是细节——分块怎么切、模型怎么选、重排怎么加、提示词怎么写。每一个环节差一点最后答案的质量就差很多。所以别急着堆功能先把这条链路调到自己满意再考虑扩展。 从零搭建RAG个人知识库问答机器人：分块、向量化与重排实战
1. 为什么我要从零搭一个个人知识库问答机器人我手头攒了大概七八年的技术笔记、项目复盘、会议纪要散落在各种 Markdown 文件、PDF 和网页剪藏里。以前靠全文搜索还能凑合但搜索的前提是我得记得住关键词。很多时候我只记得“那个关于缓存穿透的解决方案”具体叫什么名字早忘了搜出来的东西驴唇不对马嘴。这就是我动手做这个 Agent 的直接动机——我要的是一个能听懂人话、能理解语义、能帮我从一堆杂乱文档里把答案捞出来的东西。这个项目本质上是一个RAG检索增强生成驱动的个人知识库问答机器人。说人话就是我把自己的文档喂给它它建好索引之后我用自然语言提问它先从我的文档里找到最相关的片段再让大模型基于这些片段组织出答案。它解决的核心问题是“知识检索的语义化”和“答案生成的自动化”适合所有手里有大量私有文档、又不想每次翻半天的人。不管你是刚接触 Agent 和 RAG 的新手还是已经用过一些现成工具但想搞清楚底层怎么跑的老手这篇内容都能给你一套可以直接抄作业的方案。我选择自己搭而不是直接用现成产品原因有三个。第一个人知识库涉及隐私文档不想上传到别人的服务器第二现成产品的检索策略和分块逻辑是黑盒遇到效果不好的情况没法调第三自己搭一遍才能真正理解 RAG 的瓶颈在哪后面做更复杂的 Agent 项目心里有底。整个方案我跑通并稳定用了几个月下面把设计思路、关键细节、实操过程和踩过的坑全部摊开讲。2. 整体架构设计与技术选型思路2.1 为什么是 RAG 而不是微调一开始我也纠结过要不要走微调路线。毕竟热词里“大模型微调”“大模型微调实战”一直很火。但冷静下来分析微调解决的是“让模型学会某种风格或特定任务格式”它并不擅长“记住我文档里的具体事实”。你拿几百篇笔记去微调模型顶多学到你写笔记的语气问它某个具体参数是多少它照样编。而且微调成本高、迭代慢文档一更新就得重新训。RAG 的逻辑完全不同文档存在外部向量库里模型每次回答前先去检索。文档更新只需要重新索引那部分不用动模型。对于个人知识库这种“内容频繁增补、事实性要求高”的场景RAG 是明显更合理的选择。微调可以作为后续补充比如让模型输出更贴合我的表达习惯但检索这件事必须交给 RAG。2.2 核心组件拆解整套系统我拆成四个核心模块每个模块的选型都经过实际对比。文档加载与分块这是最容易被低估的环节。我试过直接把整篇文档塞进去结果检索出来的片段太长模型抓不住重点也试过切得太碎一句话被切成三段语义直接断了。最后我采用的是按语义段落切分加滑动窗口重叠的策略具体参数后面细讲。向量化与向量库Embedding 模型负责把文本转成向量向量库负责存储和相似度检索。Embedding 模型我选的是本地可跑的中文效果较好的开源模型向量库用的是轻量级的本地方案不依赖外部服务数据全在自己机器上。检索与重排单纯靠向量相似度检索有个问题——它有时候会把“看起来像但实际不相关”的片段排前面。所以我加了一层重排先用向量召回一批候选再用重排模型精排把真正相关的顶上来。生成与 Agent 编排最后一步是把检索到的上下文和用户问题一起交给大模型生成答案。这里我用了一个轻量的 Agent 框架来编排整个流程让“检索—判断—生成”形成一个可控的链路而不是一次性把东西全丢给模型。2.3 技术选型对比表环节候选方案最终选择选择理由文档解析纯文本解析 / 通用文档解析库通用文档解析库能处理 PDF、Markdown、网页多种格式分块策略固定长度 / 语义段落 / 递归切分语义段落重叠保留语义完整性减少断句Embedding在线API / 本地开源模型本地开源模型隐私可控无调用成本向量库云端服务 / 本地轻量库本地轻量库数据不出本机部署简单重排无重排 / 交叉编码器重排交叉编码器重排显著提升Top结果相关性生成模型在线大模型 / 本地部署在线大模型API生成质量高个人用量成本可接受编排框架手写流程 / Agent框架Agent框架链路清晰便于扩展工具这个选型不是拍脑袋定的是我在实际跑的过程中反复调整出来的。比如一开始为了省事想全用在线 API结果发现 Embedding 调用量一大成本就上来了而且文档内容要传到外部心里不踏实所以 Embedding 换成了本地。生成环节因为对质量要求高本地小模型效果确实差一截就保留了在线 API。3. 核心细节解析与实操要点3.1 文档分块决定成败的第一步分块这件事我踩的坑最多。最开始我用固定长度切比如每 500 个字符一刀切。结果一篇讲数据库索引的笔记正好在“B树的结构是”这里被切断后半句跑到下一个块里去了。检索的时候用户问“B树结构”召回的是前半块模型看到的是半句话回答自然残缺。后来我改成按语义段落切优先在标题、空行、句号这些自然边界处断开。具体做法是先按 Markdown 标题层级切大块再在每个大块内按段落切如果某个段落还是太长再按句子切。同时加一个重叠窗口让相邻块之间有 10% 到 15% 的内容重叠这样即使边界处有信息也不会完全丢失。提示重叠比例不要太高否则向量库里会有大量重复内容检索时容易召回一堆相似的块反而稀释了有效信息。我实测 10% 到 15% 是比较舒服的区间。还有一个细节是块的长度。太短比如 100 字语义不完整太长比如 2000 字检索精度下降。我最后定在 300 到 500 字之间具体根据文档类型微调。技术笔记偏短叙事类文档偏长。3.2 Embedding 模型的选择与本地部署Embedding 模型的作用是把文本转成高维向量让语义相近的文本在向量空间里距离更近。我对比过几个中文效果不错的开源模型最后选了一个在中文语义相似度任务上表现稳定的。部署方式很简单用本地推理框架加载模型暴露一个本地接口索引和查询都走这个接口。这里有个关键点索引用的 Embedding 模型和查询用的必须是同一个。我见过有人索引时用 A 模型查询时换了 B 模型结果检索效果一塌糊涂。因为不同模型生成的向量空间不一样混用等于拿中文词典去查英文单词。本地部署的另一个好处是批量索引快。我几千个文档块本地模型跑一遍也就几分钟换成在线 API 得考虑限流和费用。而且本地模型没有网络延迟查询响应基本在毫秒级。3.3 向量库的搭建与索引策略向量库我选的是本地轻量级方案支持持久化存储和增量更新。建库的时候有几个参数需要调距离度量我用的是余弦相似度因为文本向量的方向比长度更重要。索引类型数据量小的时候用扁平索引就行召回率最高数据量上万之后可以换成近似索引牺牲一点召回率换速度。持久化一定要开持久化否则每次重启都要重新索引浪费时间。增量更新是我特别看重的一点。我的笔记是持续在写的不可能每次加一篇就全量重建索引。所以我在流程里做了判断如果文档是新增的就只索引新增部分如果文档被修改了就先删掉旧块再索引新块。这个逻辑用文档 ID 加内容哈希来实现改动过的文档哈希会变就能识别出来。3.4 重排环节把真正相关的顶上来向量检索有个天然缺陷它算的是整体语义相似度有时候一个块里大部分内容不相关但恰好有一句话和问题很像整体相似度就被拉高了。反过来一个块整体都在讲相关问题但没有哪句话和问题字面接近反而可能排后面。重排就是来解决这个问题的。它的原理是把“问题候选块”成对输入一个交叉编码器让模型直接判断这个块对这个问题到底有多相关。这个计算比向量相似度慢所以只对向量召回的前 N 个候选做重排比如前 20 个重排出前 5 个。实测下来加了重排之后答案的准确率有明显提升尤其是那些问题表述和文档表述不一致的情况。注意重排模型也要选中文效果好的而且要和 Embedding 模型配合调。我试过重排后反而变差的情况原因是重排模型对某些领域术语不敏感把相关块排掉了。所以重排后最好保留一个兜底策略比如重排结果和原始向量结果做加权融合。3.5 生成环节的提示词设计检索到相关块之后最后一步是让大模型基于这些块回答问题。这里的提示词设计直接决定答案质量。我的提示词结构是这样的系统角色设定明确告诉模型它是一个基于给定资料回答问题的助手。上下文注入把检索到的块按相关性排序后拼接进去每个块标注来源。回答约束要求模型只基于给定资料回答资料里没有的信息不要编如果资料不足以回答就明确说“根据现有资料无法确定”。引用要求让模型在答案里标注信息来自哪个块方便我回溯核对。这个约束非常重要。不加约束的话模型很容易用自己的先验知识去补全看起来回答得很流畅实际上掺杂了它自己编的内容。对于个人知识库这种要求事实准确的场景宁可它说“不知道”也不要它编。4. 完整实操流程与关键环节实现4.1 环境准备与依赖安装先把基础环境搭起来。我用的是 Python 生态主要依赖包括文档解析库、Embedding 推理框架、向量库客户端、Agent 编排框架。安装的时候建议用虚拟环境避免和系统里的其他包冲突。python -m venv venv source venv/bin/activate pip install document-parser embedding-runtime vector-db agent-framework这里不写具体包名是因为不同版本迭代快你按自己选型的实际包名装就行。关键是版本要匹配尤其是 Embedding 模型和推理框架的版本不匹配会报各种奇怪的错。4.2 文档加载与预处理我写了一个统一的加载器根据文件扩展名走不同的解析分支。Markdown 直接读文本PDF 用解析库抽文字网页剪藏先转成 Markdown 再读。解析完之后做一轮清洗去掉多余空行、统一标点、把连续空格压成一个。def load_document(path): ext path.suffix.lower() if ext .md: text path.read_text(encodingutf-8) elif ext .pdf: text parse_pdf(path) elif ext .html: text html_to_markdown(path) else: return None return clean_text(text)清洗这一步别偷懒。我一开始没做清洗结果 PDF 里抽出来的文字带一堆换行和页眉页脚分块之后全是噪音检索效果很差。后来加了清洗规则把重复出现的页眉页脚模式识别出来删掉效果立刻好转。4.3 分块与向量化入库分块函数我按前面说的语义段落加重叠来实现。核心逻辑是递归切分先按标题切再按段落切再按句子切直到每块都在目标长度内。def split_text(text, max_len500, overlap50): paragraphs text.split(\n\n) chunks [] current for para in paragraphs: if len(current) len(para) max_len: current para \n\n else: if current: chunks.append(current.strip()) current para \n\n if current: chunks.append(current.strip()) # 加重叠 overlapped [] for i, chunk in enumerate(chunks): if i 0: prev_tail chunks[i-1][-overlap:] chunk prev_tail chunk overlapped.append(chunk) return overlapped向量化就是把每个块过一遍 Embedding 模型拿到向量后连同原文、来源、块序号一起写进向量库。这里我建议给每个块生成一个唯一 ID用“文档路径块序号”的格式方便后续更新和删除。4.4 检索链路实现检索的时候先把用户问题用同一个 Embedding 模型转成向量去向量库召回 Top 20。然后把这 20 个候选和问题一起送进重排模型拿到精排后的 Top 5。最后把这 5 个块的原文拼成上下文。def retrieve(query, top_k5): query_vec embed(query) candidates vector_db.search(query_vec, top_n20) reranked rerank(query, candidates) return reranked[:top_k]这里有个实操细节召回数量不要设太小。我一开始只召回 5 个直接重排结果有时候真正相关的块在向量排名第 8根本没进重排环节。后来改成召回 20 个再重排召回率明显提升。代价是重排计算量增加但个人知识库这个量级完全扛得住。4.5 Agent 编排与生成Agent 编排这块我用框架把整个流程串起来。核心是一个“检索工具”加一个“生成节点”。用户提问后Agent 先调用检索工具拿到上下文再把上下文和问题一起交给生成节点。def answer(query): context_blocks retrieve(query) context \n\n.join([b.text for b in context_blocks]) prompt build_prompt(query, context) response llm.generate(prompt) return response提示词模板我单独抽出来管理方便调优。模板里明确写了“只基于以下资料回答”“资料不足时说明无法确定”“标注信息来源”。这几条约束加上之后答案的可靠性提升非常明显。4.6 参数选择与计算过程分块长度和重叠比例这两个参数我是这么定的。先统计我所有文档的段落长度分布发现大部分段落在 200 到 400 字之间。所以块长度定在 500 字能容纳一个完整段落加一点上下文。重叠比例定在 10%也就是 50 字刚好是一两句话的长度能在边界处保留语义衔接。召回数量 20 和重排后 5 这两个数是我做了一轮小规模评测定下来的。我准备了 30 个问题人工标注了每个问题的正确答案在哪些块里然后测不同召回数量下的召回率。召回 20 个的时候正确答案基本都在候选里了再往上加召回率提升很小但重排耗时线性增长。重排后取 5 个是因为生成模型的上下文窗口有限5 个块大概 2500 字加上问题和提示词控制在合理范围内。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是最常见的问题。排查顺序我一般是这样的先看分块是不是把相关内容切散了如果是调整分块参数再看 Embedding 模型是不是不适合你的领域如果是换一个在你领域数据上表现更好的模型最后看是不是需要加或调重排。我遇到过一次典型情况问“缓存雪崩的解决方案”检索出来的全是“缓存穿透”的内容。原因是这两个概念在我的笔记里经常出现在同一篇文档里向量相似度区分不开。后来加了重排重排模型能更好地区分这两个概念的细微差别问题就解决了。5.2 答案里出现资料中没有的内容这是模型幻觉。解决办法是在提示词里加强约束并且降低生成模型的“创造性”参数。我一般把温度调到很低让模型尽量保守地基于资料回答。另外要求模型标注来源也有帮助因为一旦要求标注模型就不太敢编了编了它自己都对不上来源。5.3 索引更新后检索结果变差有一次我批量更新了一批文档更新完发现检索效果反而下降了。排查后发现是旧块没删干净新块和旧块同时存在检索时召回了一堆过时的内容。后来我在更新逻辑里加了“先按文档 ID 删除旧块再插入新块”的步骤问题解决。所以增量更新一定要处理好删除不能只加不删。5.4 常见问题速查表问题现象可能原因排查方向解决办法检索结果不相关分块不合理/模型不匹配检查分块边界和模型调分块参数或换模型答案含资料外内容提示词约束不足检查提示词和温度加强约束、降低温度更新后效果变差旧块未清理检查向量库块数量更新前先删旧块响应慢召回数量过大检查召回和重排参数降低召回数量答案残缺分块切断语义检查边界处内容增加重叠比例重复召回相似块重叠比例过高检查块间相似度降低重叠比例5.5 独家避坑技巧第一个技巧先小规模验证再全量索引。我一开始直接把几千个文档全索引了跑完发现效果不好又得全量重来。后来改成先拿 20 篇文档做小规模测试调好参数再全量跑省了大量时间。第二个技巧保留原始块和重排结果的映射。调试的时候我会把每次检索的原始召回列表和重排后列表都打日志这样效果不好的时候能直接看到是召回阶段的问题还是重排阶段的问题。第三个技巧定期做检索评测。我每个月会抽 20 个问题人工看检索结果对不对。这样能及时发现文档更新或模型变化带来的效果波动不至于等到用的时候才发现不好使。第四个技巧文档来源要标注清楚。我在每个块里都存了来源路径和块序号生成答案时让模型带上来源。这样我核对答案的时候能直接定位到原文也方便发现哪些文档质量差、需要整理。6. 后续可扩展的方向这套东西跑通之后我发现可扩展的地方很多。比如可以加一个“多轮对话”能力让 Agent 记住上下文支持追问。也可以加“工具调用”让 Agent 在检索不到的时候去查外部资料。还可以把图片和表格也纳入索引做多模态检索。不过这些都是后话核心的 RAG 链路先跑稳后面加东西才有意义。我个人在实际操作中的体会是RAG 这东西看起来简单真正决定效果的全是细节——分块怎么切、模型怎么选、重排怎么加、提示词怎么写。每一个环节差一点最后答案的质量就差很多。所以别急着堆功能先把这条链路调到自己满意再考虑扩展。