这阵子一直在啃RAG相关的东西刚好把wow-rag这个入门项目完整过了一遍边看边练边踩坑觉得是时候把笔记整理出来。先说结论RAGRetrieval-Augmented Generation检索增强生成本身不是个多玄乎的概念说穿了就是给大模型外挂一个可检索的资料库让它在回答问题之前先去你的文档里翻资料再基于翻到的内容组织答案。但你真正动手跑一个RAG项目的时候会发现加载、拆分、向量化、检索、重排、注入上下文、生成每一个环节都藏着不少细节任何一个地方做得糙最后出来的答案质量都会直接打折。这篇文章基本上就是我学习wow-rag的完整记录包含RAG的核心原理梳理、本地部署过程、关键参数怎么定以及我在实操中遇到的一堆问题和排查思路。适合刚接触RAG、想搭一个本地知识库或者想弄明白RAG到底是怎么工作的这类问题的朋友。1. 为什么大家都在学RAG先搞清楚它解决了什么问题1.1 大模型的知识硬伤幻觉、截止日期和数据隐私我之所以跑去学RAG起因特别实际。之前直接用大模型做内部文档问答模型一本正经地给我编了个不存在的功能说明一问出处它开始胡诌。这就是业界常说的幻觉问题模型不知道就是不知道但它很少会说我不知道而是会顺着你的问题把话圆下去。就算换成参数更大的模型幻觉也只是减轻不会消失。另一个硬伤是知识截止时间。模型训练完的那一天它的知识就停滞了你问它最近发布的新版本、新政策它要么答不上来要么瞎编。再有一个很多人忽视的问题企业也好个人也好很多知识库内容是私有的不适合拿去微调模型也不方便送进外部API。这三个问题叠在一起光靠换模型是解决不了的RAG的出现就是冲着这些痛点去的。RAG的思路其实很朴素像一个开卷考试的考生大模型就是那个记忆力不太行的考生RAG负责提供参考资料它每次回答前先翻资料再落笔作答。这样答案有依据幻觉少了新知识也能通过更新资料库注入进去私有数据也不用拿去训练模型——这三点正好精准对应前面的三大硬伤。1.2 一条链路看懂RAG加载、切块、向量化、检索、生成RAG的标准流程入门阶段只需要记住这条链路加载文档把你的PDF、Word、Markdown、TXT等资料读取出来。文本拆分长文档太长塞不进模型的上下文拆成若干个小块。向量化对每一块文本用Embedding模型生成一个向量一串数字。存储索引把向量和原文一起存进向量数据库。检索召回用户提问时同样把问题转成向量去库里找最相似的几个文本块。重排与注入把召回的文本块按相关性排序填充到大模型的Prompt中。生成回答让模型结合提供的上下文回答问题并附上引用来源。这七步里前四步是做知识入库后三步是做问答推理两段都有讲究。wow-rag这个项目让我比较喜欢的一点是它把每一步都拆成了独立的模块代码逻辑很清楚非常适合照着改成自己的业务流程而不是包了一个黑盒给你调。1.3 wow-rag项目定位一个为看懂RAG而生的教学实现wow-rag不是什么特别复杂的生产级框架它的定位更像是一份能跑起来的RAG参考实现。官方文档里也写得很直白项目目标是让你理解RAG的每一步是怎么运作的而不是封装一堆晦涩的抽象概念。整个项目采用模块化设计数据加载、文本拆分、向量化、检索、生成等环节都有独立封装好的模块可以单独调用。它默认支持Ollama本地部署方案也就是说你可以完全离线跑通整个流程不用把文档内容发给外部API这一点对内部知识库场景很重要。我在本地按项目跑通以后又把里面几个核心模块抽出来改了改套进了自己的笔记问答场景整个理解深度比之前干看文章要扎实得多。如果说有什么不足就是wow-rag对工程化能力比如增量更新、权限控制、高并发没有太多覆盖但这是合理的取舍——入门项目先把链路讲清楚工程化问题后面可以看LangChain、LlamaIndex这类的成熟框架。2. 核心细节解析决定RAG效果好坏的关键都在这里2.1 文档加载与文本拆分的隐藏学问很多人以为RAG流程里最不重要的就是加载和拆分实际上我实测下来这两个环节对最终效果的影响不亚于模型选择。加载阶段遇到最多的问题是格式解析PDF可能是扫描件根本抽不出文字Word可能有复杂的表格Markdown本身就带格式。一个比较实在的做法是初始阶段优先用txt和markdown这类纯文本格式做测试跑通后再逐步加PDF、Word等复杂格式否则你很难分清问题出在解析还是后面的检索。文本拆分是重头戏。最开始我用的是最简单的固定长度切分每300个字符切成一块。结果就是一句话被从中间劈开语义不连续后续检索召回的准确率惨不忍睹。后来换成递归字符分割器它优先按段落、句子、标点这些自然边界来切切出来的文本块语义完整性明显好很多。这里有几个我实测下来比较好用的参数区间块大小一般在200到500个token之间中文场景下差不多是几百个字符。太小一个完整语义可能被拆散找不到上下文太大向量化后的语义容易被稀释。块重叠chunk_overlap一般取块大小的10%到20%一头一尾留一点重叠防止关键信息恰好落在两块交界处被切断。先按段落分再按句子分不要在句子中间硬切这是默认规则。我分享一个调试经验每做一次拆分策略调整最好人工盯着看几个切出来的样本判断这一块如果单独给模型它能不能看懂。这一步比参数调优更直觉也更有效。2.2 Embedding选型的取舍不是越贵越好Embedding模型的作用是把文本变成向量向量之间的相似度决定了检索能不能找到真正相关的内容。对中文场景来说我建议优先考虑对中文支持好的模型。像Ollama自带的nomic-embed-text虽然轻量但中文效果只能说及格bge-m3这类针对多语言优化的模型中文语义理解明显更强但显存占用和推理耗时也会上来。另外一个新手容易忽略的问题Embedding分词在向量空间里的比较很依赖文本质量。如果你的文档里带大量HTML标签、重复的页眉页脚、乱码符号这些噪声都会污染向量语义降低检索精准度。很多人一上来就使劲换Embedding模型反而忽略了加载阶段的清洗工作这是本末倒置的。实际选型时可以按这个思路走硬件有限、追求速度用nomic-embed-text或zh轻量模型先跑通文档量大、中文为主、效果优先上bge-m3如果预算充足且有GPU资源可以测试商用的向量接口。向量模型一旦确定全流程的向量维度也就锁定了中途换模型会面临旧向量全部重新计算的问题所以不要在项目中期随意更换。2.3 向量检索与重排序召回不等于准确检索环节决定了模型能看到什么而模型只能基于看到的内容作答所以检索质量是RAG效果的上限。最常见的检索方式是用余弦相似度或内积在向量库里找top-k相似的文本块。k值怎么定我起步用k5到8太大容易把不相关的内容塞进上下文太小则容易漏掉关键信息。但光靠向量检索有一个非常现实的坑语义相似不一定等于答案正确尤其当文本块很长、包含大量信息时向量相似度会被综合语义带偏反而召回一些泛泛相关但没用的段落。解决思路是加一层重排序rerank。重排序阶段用一个Cross-Encoder模型对召回的若干个候选块逐条打分输出更精确的相关性排序。我自己的测试里加了重排序之后回答准确率明显提升特别是top-3答案的可用性变化很大。代价是多一次推理开销但效果值得。还有一点需要专门提一句hit rate。这是评估召回质量的常用指标指的是正确答案对应的文本块是否被成功召回。如果你正在调试检索环节先别看最终答案好不好先把hit rate跑上去。这个指标上去了答案质量才有基本的保证。2.4 Prompt构造用上下文约束大模型别乱说话检索到位之后最后的发挥空间在Prompt设计上。RAG的Prompt核心就一句让模型优先基于提供的资料作答资料不足时明确表示不知道不要胡编。你可以写得更具体一些比如要求模型引用原文、整理成符合提问角度的结构、将专业术语做通俗解释等。我试过完全不约束Prompt直接把资料拼上去让模型自由发挥答案虽然大致正确但经常夹杂幻觉。后来改成强制约束之后效果大不一样。我自己常用的一段Prompt框架是先设定角色和任务再说明资料格式然后给出硬性规则只能基于资料、不能编造、资料不足时直说最后把检索到的文本块按编号贴上。放在wow-rag里我用LangChain的Prompt模板替换了默认模板改动量不大但效果明显。3. 实操过程记录在本地把wow-rag完整跑通3.1 环境准备与依赖安装我本地的环境是Windows系统Python 3.10没有独立GPU全靠Ollama调用CPU跑小模型。这套配置跑RAG链路完全够用只是速度会慢一些。依赖安装很简单核心就是langchain相关库、faiss向量库和ollama客户端pip install langchain langchain-community langchain-ollama faiss-cpu如果想把代码写得简单一些也可以直接用wow-rag项目里自带的requirements。注意faiss-cpu在Windows上的安装有时会抽风如果装不上换用conda装或者退而求其次用chromadb也能实现同样的效果。Ollama的模型拉取要提前准备。我用的组合是nomic-embed-text做Embeddingqwen2.5:7b做生成模型。直接用命令拉取ollama pull nomic-embed-text ollama pull qwen2.5:7b7b模型在CPU上生成速度不快但胜在够用。如果你想跑得快一点可以试试qwen2.5:3b效果会打折但响应速度能接受。这个选择原则上没有绝对标准取决于你的硬件和实际场景。3.2 构建一个最小可用的本地知识库我用的测试文档是一批自己写的Markdown笔记内容涉及项目管理、技术选型和一些零散的工作心得。文档不大总共也就几万字。加载和拆分这一步我直接用了wow-rag里推荐的方式在LangChain基础上组合了一个链路from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_ollama import OllamaEmbeddings from langchain_community.vectorstores import FAISS loader TextLoader(notes.md, encodingutf-8) documents loader.load() text_splitter RecursiveCharacterTextSplitter( chunk_size300, chunk_overlap50, separators[\n\n, \n, 。, , , , , , ] ) chunks text_splitter.split_documents(documents) embeddings OllamaEmbeddings(modelnomic-embed-text) vectorstore FAISS.from_documents(chunks, embeddings) vectorstore.save_local(faiss_index)这段代码就是把所有笔记变成向量存进本地FAISS索引。第一次运行会花一点时间因为每条文本块都要过Embedding模型。跑完之后我专门翻了一下切出来的文本块发现chunk_overlap50确实有效很多跨段的关键信息没有被切断。但我也发现一个问题Markdown里的代码块会被拆到多个块里代码注释和正文混在一起时向量语义会比较混乱。这种情况后续可以针对代码块单独处理不过那是优化方向不影响第一步跑通。3.3 问答链路检索、注入、生成知识库构建完成之后问答链路就水到渠成了。我用LangChain的RetrievalQA连了一条最简链路from langchain_ollama import OllamaLLM from langchain.chains import RetrievalQA retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 5} ) llm OllamaLLM(modelqwen2.5:7b, temperature0.2) qa RetrievalQA.from_chain_type( llmllm, retrieverretriever, chain_typestuff ) result qa.invoke(我在项目复盘里提到的最重要的三个改进点是什么) print(result[result])temperature设到0.2是为了让模型尽量贴合资料回答减少自由发挥。RetrievalQA的chain_type默认是stuff也就是把所有召回的文本块都塞进Prompt里文本量不大时完全够用文本量大了可以考虑map_reduce或refine模式但那些会带来额外的开销和复杂度入门阶段先不用管。我实测问了好几个问题其中有一个问题踩了坑我问我踩过哪些技术选型的坑模型回答得比较空泛翻了一下检索出来的被召回文本发现相关记录确实被拆散了分布在不同的文本块里导致模型只看到了部分内容。这就是典型的知识割裂问题后面我在第五部分会展开讲。3.4 调参心得一个参数一个参数地试跑通以后我开始做调参实验。我的做法是固定其他变量每次只改一个参数对比同一组问题的回答质量。先说chunk_size我从200试到800发现300到500之间效果最好。200太碎上下文不完整800太大向量检索精度下降。然后是top-kk3时答案很精准但偶尔漏信息k10时上下文过于冗长模型容易被不相关内容干扰k5到8是比较稳的区间。再说temperature0到0.3之间模型越接近照本宣科模式但也不是越低越好有些开放式总结类问题太低会让答案变得机械。重排序的收益我前面提过这里补充一下具体操作用bge-reranker-base或bge-reranker-v2-m3都可以输入是query加候选文本块输出是相关性分数然后按分数重新取top-k。集成方式不复杂但需要多维护一个模型下载和加载时间都要算进去。做完重排序后我同一组问题的hit rate从70%左右提到了85%以上这个提升幅度放到问答场景里体感差别非常明显。4. 常见问题与排查技巧实录4.1 问题速查表我把学习和实操中遇到的典型问题整理成一个表格方便你排查时对照。问题现象可能原因解决建议检索结果明显不相关Embedding模型不适合中文/文档清洗不到位换中文优化模型先清理HTML标签等噪声再重建向量库答案仍然胡说八道Prompt约束不足/上下文被无关信息污染加硬性只能基于资料回答指令做重排序收紧召回质量关键信息被拆散回答不完整chunk_size过小/知识横跨多个文本块调大chunk_size加overlap或尝试父子分块策略向量维度不一致报错前后使用了不同的Embedding模型统一模型更换模型后必须重新生成全部向量中文乱切句子语义断裂切分器没有识别中文标点在separators中加入。等中文标点本地生成速度太慢CPU推理/模型偏大换小参数量模型开Ollama并发限制或对提示做精简检索结果看起来都对答案却差生成模型能力不足/上下文顺序不对调整文档块排序重要内容前置或换更强生成模型新增文档后旧答案变了增量更新未处理/向量分布变化建立增量索引旧索引和新索引分开管理再合并查询4.2 两个必须单独拎出来说的坑第一个坑是知识割裂。大多数场景是用户问的答案分散在多个段落甚至多个文档里只靠向量检索很难一次性把所有相关片段召回。我踩过不少次尝试过几种方案最直接有效的是在拆分时让chunk_size大一点比如500同时把这个块的前后文也一并存下来作为上下文补充更进一步可以做父子块结构——父块大、子块小检索时用子块精确匹配拿父块补全上下文。这个方案在LangChain里已经有一套现成实现比你想的简单。第二个坑是换模型后旧向量失效。我一开始用nomic-embed-text生成了全套向量后来想换bge-m3直接切换后发现检索结果变成一团浆糊。原因很好解释不同Embedding模型产出的向量空间不统一新模型生成的query向量和旧模型生成的文档向量之间根本没有可比性。所以这里要记住一条血泪教训Embedding模型选定后尽量不要中途更换如果非要换必须重新生成整个文档库的向量这一步的成本需要提前评估。4.3 排查思路从指标到答案的层层定位如果你发现问答效果不理想我建议按这个顺序排查而不是凭感觉瞎改先看hit rate确认正确答案对应的文本块有没有被检索出来。再看召回文本块的排序是否把真正相关的内容排在前面。然后看Prompt里注入的上下文是否够完整是否被无关文本干扰。最后看生成模型的输出判断是否严格约束了不编造规则。这个顺序背后的逻辑是检索是源头源头错了后面再优化也没用重排是把真正有用的内容挑出来Prompt是把挑出来的内容用好生成是最后一环但它的发挥空间被前面的环节限制死了。按这个思路排查基本能定位到80%以上的问题而不是在无效参数上反复折腾。5. RAG的进阶方向从入门到知道天花板在哪5.1 为什么会出现GraphRAG、Agentic RAG这些变体RAG快被聊烂了同时也快被卷烂了。基础版RAG的效果上限很清晰它只是一种单跳检索策略一次检索命中一个或几个相关片段然后拼给模型。问题恰好出在这里——如果问题需要多步推理、需要把多个来源的信息综合或者需要处理高度结构化关系的数据比如这个项目里谁负责了哪个模块和哪个bug相关基础版RAG就力不从心了。于是出现了几个核心方向的演进GraphRAG在文本块的基础上额外构建实体关系图谱推理时沿着关系链做多跳查询能有效解决知识割裂问题Agentic RAG则是让智能体自主决定什么时候检索、检索几轮、用什么工具把固定流程变成策略性的多步决策ontology RAG则更强调领域本体的构建用结构化的概念关系约束检索和推理的方向。wow-rag里对基础RAG的实现很清晰读完以后再看这些进阶方向你会更清楚它们到底改进了哪个环节、代价又是什么。5.2 RAG的瓶颈与评估别只盯着能不能答对RAG或者整个检索增强体系目前公认的瓶颈是召回质量的天花板。不论生成模型有多强如果召回的文本里根本没有正确答案模型再怎么生成也无济于事。这也是业界一直在强调hit rate等召回评估指标的原因。我自己的体会是评估RAG不能只看一两个demo问答就下结论。做一个相对固定的评测集包含几十个问题覆盖简单事实类、综合分析类、跨文档推理类三种难度然后持续跟踪hit rate、答案准确率、拒绝率模型正确说不知道的比例这几个指标。特别是拒绝率很多人忽视它但一个能正确说不知道的RAG系统比一个硬着头皮编答案的系统要可靠得多。如果你在入门阶段我强烈建议先不要碰重型框架而是像我一样用LangChain加Ollama把基础流程亲手过一遍。你对每个环节的感性认识和排查能力会在后面用其他框架时转化成巨大的效率优势。最后分享一个我在实操里觉得最值钱的习惯每次改参数都先明确这次改的是哪一环、预期是什么、怎么验证。RAG的链条太长今天改个切分、明天换个模型如果不记录不验证最后效果变了你都不知道是哪个变量起的作用。我为此专门建了个测试问题和指标的小表格每个改动跑一遍对比。这个习惯帮我省掉了大量反复试错的成本也让我把wow-rag的代码吃得更透。