去年在做一个RAG知识库项目时我连续踩了一个星期的坑。最终定位到的核心问题不在大模型也不在向量数据库而在PDF解析——表格里的内容总被切碎检索出来的上下文和问题完全对不上。把解析层重写之后效果立刻好转。这件事给我的体感很直接RAG的难点从来不是“怎么把大模型接进去”而是整个数据链路能不能扛住真实场景的复杂度。最近系统梳理Udemy那门《AI LLM Engineering Mastery: GenAI, RAG Complete Guide》Part 2的学习笔记时这个感受又被反复印证。Part 2的重点不是基础概念而是从文档解析到评估指标、再到Agent化的完整工程链路。很多教程喜欢把RAG讲成一个“三步走”方案加载文档、向量化、交给大模型。但真实项目里这三步每一步都能裂变成一堆细节。这篇文章不打算复述课程目录而是结合项目实战经验把RAG链路按“解析→分块→索引→评估→精度→Agent化”的顺序拆一遍。适合那些已经跑通过demo、正准备把RAG放进真实业务的读者。1. RAG入门之后真正的分水岭在工程化1.1 为什么demo能跑生产却问题不断很多人第一次接触RAG用的都是现成例子一个PDF放进去按固定长度切块embedding之后存到向量库再用LangChain或LlamaIndex把检索结果拼进Prompt最后让模型生成答案。这一套在演示环境里通常很丝滑因为样例文档干净、问题经过筛选、没有并发压力、也不会有人问知识库边界之外的事情。一旦换成真实业务文档问题立刻涌现。常见的有PDF里的表格跨页切块后语义断裂。扫描件没有OCR层检索质量急剧下降。Word文档带批注、文本框、页眉页脚解析出来全是噪音。不同来源的文档元数据不统一过滤时无从下手。用户问法和知识库原文的表述差异太大直接向量检索召不回内容。这些问题的共性是它们都不在模型层而在数据工程层。RAG系统的上限首先由数据管道的质量决定其次才是模型能力。Part 2花了大量篇幅讲“文档加载解析详细全流程”原因就在这里——它不是最显眼的部分但它是决定成败的部分。这里先给一个核心判断任何RAG项目都应该把大部分精力花在“让检索之前的一切变得可靠”上而不是反复调Prompt和换模型。理由很直接——检索喂进去的内容本身就是错乱的再强的生成能力也只是建立在错误上下文之上。1.2 RAG完整链路从文档到生成既然要谈工程化就要先把链路拆开。一个完整的RAG系统通常包含下面几个环节环节主要任务常见工具/方法文档加载读取不同格式的文件PDF、Word、Markdown、HTML解析器内容清理去页眉页脚、去噪音、保留表格结构文本清洗、OCR、版面分析分块把长文本切成适合向量化的片段固定长度、递归分割、语义分块向量化将文本块转成向量Embedding模型索引建向量索引、元数据索引向量数据库开源或云端检索根据问题召回相关片段向量检索、混合检索、重排序生成把检索结果组装成Prompt交给LLMPrompt模板、模型推理评估验证检索和生成的质量评估集、自动化指标这个链路里每一个环节都有“能做”和“能做好”的差距。比如文档加载能读到文字和能保留版面结构是两回事分块能切出片段和能切出语义完整的片段是两回事检索能返回相似内容与能返回当前问题真正需要的上下文也是两回事。Part 2的重点就在这些“两回事”上。它不是教你怎么调通一个RAG而是教你怎么把RAG调到可以交付给业务方使用。这个认知转变是从“会用工具”走向“能做工程”的分水岭。1.3 该先掌握框架还是先理解数据链路现在市面上RAG相关框架很多有LangChain、LlamaIndex这类开发框架也有Dify这类低代码平台还有Spring AI这种把大模型能力整合进Java生态的尝试。工具选型很容易让人陷入纠结但对初学者来说框架本身不是关键。我的建议是先手写一个最小链路不用任何重量级框架。用最朴素的代码完成从文档解析到向量化再到检索生成的过程。这个过程中你会被迫理解每一步在干什么解析器返回了什么结构分块之后文本变成了什么形态embedding之后的向量如何比较相似度检索到的片段又如何拼进Prompt。理解完这些底层机制再上手LangChain或Dify你会像看地图一样清晰框架只不过是把这些环节封装成了配置项和调用链。框架会更新、会变化但数据链路的底层问题一直都在。如果你已经完全理解链路直接用Dify这类平台做业务原型也完全合理。它的价值在于把重复劳动简化尤其适合快速验证。但要注意平台化工具降低了上手门槛并不意味着工程问题会自动消失。数据质量、评估闭环、权限管理这些事平台不会替你做。2. 文档加载与解析是RAG最容易被低估的环节2.1 PDF、Word、扫描件三类格式各有各的坑RAG项目中文档解析是第一个隐藏瓶颈。很多教程的代码只有三五行把PDF文件传给某个解析器得到文本完事。但真实场景里文本的版式、层级、表格信息一旦丢失后面的检索和生成都跟着失真。先说最常见的PDF。PDF本身不是一种“文档”格式而是一种“版面描述”格式。它记录的是一行行文字该放在哪里而不是“标题是什么”“表格有几行几列”。所以直接抽取文本时经常碰到标题层级丢失标题和正文混在一起。表格被按行读取单元格之间的关系被拆散。多栏排版的文档文字顺序错乱。页眉页脚和正文混入同一文本块。这会导致什么后果举个例子一个产品规格表里有“型号A支持10W快充”和“型号B支持50W快充”切块后可能变成两个互不关联的片段。用户问“哪款支持50W快充”模型检索到的内容里缺少“型号B”和“50W”的关联上下文答案自然不准。Word文档的问题也不小。它本身有结构但很多解析器没有把段落、表格、批注、文本框区分开。扫描件则是另一类问题——没有OCR层图片里的文字完全无法被检索到。现实业务中大量历史合同和票据恰恰是扫描件。2.2 解析流程的通用拆解从工程经验看一个稳定的解析流程通常包含四步格式识别按扩展名或文件头判断文档类型。内容提取调用对应解析器拿到粗文本。结构还原尽量还原标题、段落、表格、列表等结构。清洗过滤去掉页眉页脚、重复空行、乱码字符、无关批注。这里给一个通用示例结构表示文本解析脚本的主干。具体解析库需要结合你的环境选择代码只是骨架。def extract_document(file_path): file_type detect_file_type(file_path) # pdf / docx / md / html if file_type pdf: content extract_pdf_with_layout(file_path) # 尽量保留表格和层级 elif file_type docx: content extract_docx_with_structure(file_path) else: content extract_markdown_or_html(file_path) cleaned_content remove_noise(content) return cleaned_content注意这只是一个示例结构不是可以直接复制使用的代码。落地前要结合自己的文档库样本确认解析器对表格、多栏和字体大小的处理效果。不同解析库在版面还原能力上差异很大遇到复杂文档时宁可多花时间选型也不要盲目相信默认输出。2.3 小样本验证法文档解析这块我见过最多的错误是“没有验证直接批量跑”。结果几千份文档喂进去事后才知道一半都解析错了清洗成本和返工成本非常高。更稳妥的做法是五步从真实文档库里随机挑30份覆盖PDF、Word、扫描件等不同来源。把这30份全部解析一遍人工检查输出质量。统计失败率定位最常见的解析问题。针对问题调整解析器配置或增加预处理步骤。30份确认稳定之后再扩大到几百份做灰度验证。判断标准也很简单一份文档解析完标题层级是否保留、表格结构是否完整、正文顺序是否正确、噪音是否除净。这些表面上看起来和响应速度无关但决定了后续检索质量的基线。注意不要用样例文档验证解析流程一定要用真实业务文档。真实文档里的版式混乱程度通常远超样例数据。2.4 解析常见的排查顺序如果解析结果不理想不要急着换工具。先按下面的顺序排查看原始文件本身是否正常编码、缺损、加密、扫描清晰度。看解析器输出是完全是空还是文本错乱还是结构丢失。看是否涉及特殊版面表格、多栏、文本框、公式、图片。看清洗步骤是否过度有些清洗规则会把表格分隔符或者关键标点一起删掉。看文件规模和并发超过解析器单文件限制时结果可能被截断。这个排查顺序的核心思想是从“文件不可用”到“解析器不行”再到“清洗规则误伤”逐层缩小范围。如果不加区分很容易把解析问题误判成embedding或模型问题。3. 分块、向量化与索引决定召回质量的三块拼图3.1 分块策略怎么定文档解析完下一步是分块。分块直接影响检索质量因为它决定了向量化之后每个片段是否“语义完整”。常见的分块方式大致有几种分块方式基本思路适用场景固定长度分块按字符数或token数切分快速验证、通用场景递归字符分割先按段落再按句子逐级切分大部分文本型文档语义分块利用embedding或模型判断语义边界内容复杂、主题切换频繁的文档结构分块按标题、表格、章节等结构切分手册、合同、法规等强结构文档固定长度分块是很多教程默认推荐的因为它简单。但它的缺点是经常把一句话、一个表格、一组对照关系切成两半。递归字符分割会好一些因为它会根据段落和句子来切。实践中更建议分层处理有明确结构的文档优先按结构分块。没有结构的长文本用递归分割再设置合理的块大小和重叠。块大小要根据embedding模型的上下文长度来确定。对同一文档可以保留多种块策略检索时按元数据选择。这部分没有标准答案因为分块是否合理最终要用检索效果来验证。重要的是先建立“分块效果可以观察”的意识而不是套一个固定参数就完事。3.2 向量化模型选型和使用分块之后是向量化也就是用embedding模型把文本转成向量。这一步有四个关键点模型上下文长度。如果embedding模型支持的最大输入长度是512个token那你的块就不要无脑设成1000个token。文本规范化。同一批文档的大小写、标点、换行格式最好统一避免无意义的向量漂移。批量向量化。大规模场景不要一条条调接口要批量提交能明显降低耗时和成本。向量化结果的缓存。同一份文档如果只改了后续版本可以复用未变化部分的向量减少重复计算。很多项目的第一步和第二步都会出问题。比如分块大小和模型上下文不匹配文本被截断导致语义信息丢失比如同一份文档在不同版本里格式不一致向量检索时出现不可解释的偏差。embedding模型选型时还要注意语言的匹配度。如果你的知识库以中文为主就要优先选择中文效果好的模型并针对自己的业务术语做小规模检索测试。不要只看公开榜单分数要拿自己的问题去测。3.3 元数据过滤与索引设计RAG项目做到后面单纯靠向量相似度往往不够。一个常见的改善手段是“元数据过滤”。比如只从某一类文档里检索。只检索最近一段时间内的内容。只检索某个部门或某个产品线的知识。根据文档类型过滤掉FAQ或公告。这些都需要在向量化时保留元数据并在检索时把元数据条件作为过滤器。常见的做法是把元数据和向量放在同一行记录里例如{ id: doc_001_chunk_003, text: 型号B支持50W快充……, embedding: [...], metadata: { source: product_spec_2025.pdf, doc_type: spec, category: charger, updated_at: 2025-01-15 } }有了这样的结构检索时就可以先按metadata过滤再算向量相似度也可以在向量相似度基础上加一层重排序。很多RAG项目召回质量差不是embedding模型不够强而是没有利用好元数据这个“先验条件”。3.4 为什么调了embedding模型效果还是不稳定这是RAG项目中非常普遍的现象换了更强的embedding模型检索结果却没有明显变好。原因通常不在embedding模型本身而在前面的步骤。最常见的情况是分块方式没有跟着变。比如之前是固定512字换了embedding模型后模型能处理的上下文长度变了块大小却没有同步调整结果长尾句被截断语义信息照旧丢失。另一种情况是文档解析质量不稳定。同样一份文档解析器不同得到的文本结构不同向量化后的空间分布也就不同。这种情况下embedding模型的差异被解析噪声掩盖了。所以遇到检索效果不好优先排查的是“输入到embedding模型的那段文本是不是干净的、语义完整的”而不是立刻怀疑模型选型。这条经验在多个项目里都验证过。4. RAG评估指标不能靠“看着不错”4.1 检索层指标RAG效果好不好不能只看“模型回答得顺不顺”。因为即使检索到的内容完全无关大模型也能编出一段看起来很流畅的答案。所以要建立一套系统化的评估指标。检索层关注的是“召回的片段是否真的对”。常用指标有RecallK前K个结果里包含多少个相关文档。PrecisionK前K个结果里真正相关的比例。MRR第一个正确结果排在第几位。NDCG考虑排序位置的相关性折损。实践里我建议先盯RecallK。因为RAG生成答案的前提是相关上下文被召回。如果相关片段根本没进前几名后面的生成质量基本无从谈起。4.2 生成层指标生成层的指标目前常用的有指标关注点通俗解释Faithfulness / Groundedness答案是否忠于检索到的上下文有没有在知识库之外瞎编Answer Relevance答案是否对应用户的问题答非所问会拉低分数Context Relevance检索到的上下文是否和问题相关上下文不相关但答案流畅也是问题这三个指标可以组成一个固定的评估模板。也有的团队用RAGAS这类开源评估框架来批量计算。不过如果用自动评估框架建议先在小样本上人工核对分数是否合理。自动评估模型本身也有误差不要完全交给机器。4.3 构建自己的评估集评估指标不是随便定的它需要一组“已知正确”的问题和上下文来跑。我把评估集建设的思路总结为三步从真实用户问题里挑50到100条覆盖常见问题、边角问题和反例问题。对每个问题人工标注出知识库中对应的正确文档片段。用这组数据分别跑检索和生成记录指标分数。评估集不必一开始做得很大但一定要覆盖业务真实场景。否则指标好看上线照样翻车。这里额外提醒一点评估集要持续积累。每出现一个线上失败的Case就把它补进评估集。时间长了评估集本身会变成团队最宝贵的资产。它能防止同一个问题反复发生也能让模型迭代有据可依。4.4 评估分数低时怎么定位是哪个环节出了问题评估分数不理想时不要笼统地说“效果不好”。要分环节定位。先看检索。把用户问题丢进检索层拉出前5个片段人工判断这些片段是否和问题真正相关。如果不相关问题在检索之前的链路解析、分块、向量化、索引、元数据过滤逐个排查。再看生成。如果检索到的片段是相关的但最终答案不对问题就在生成侧Prompt构造是否清晰、上下文是否被截断、模型是否遵循指令、是否引入了无关信息。一个可复用的小技巧是先不看最终答案只看检索出来的片段。如果片段质量本身很高再排查生成环节。这一步能快速把问题范围缩小一半。注意评估分数的意义是“发现问题”不是“证明上线”。如果评估集只包含简单问题分数再高也不代表生产环境没问题。5. LLM精度细节FP16、FP32、BF16工程化绕不开的底层配置5.1 三种精度格式的核心差异RAG项目做到工程化会碰到一个绕不开的底层话题LLM的精度格式。这跟算法本身无关但它直接影响显存占用、推理速度和结果稳定性。FP32、FP16、BF16是现在最常碰到的三种格式。格式全称指数位尾数位特点FP32单精度浮点数8位23位精度高占用大FP16半精度浮点数5位10位占用减半但表示范围窄BF16脑浮点数8位7位和FP32指数范围一致但尾数更少简单理解FP16的优点是省显存、算得快缺点是数值范围小容易出现上溢或下溢。BF16的指数范围和FP32一样所以数值范围更稳但尾数精度低。深度学习场景对尾数精度不那么敏感所以BF16在训练和推理中都很常用。很多模型在训练时用的是BF16或FP16混合精度。到了推理阶段为了省显存也会切到半精度。这里的风险在于如果训练时使用的精度和推理时不一致某些数值敏感的任务可能会表现出微妙但不可忽视的结果差异。5.2 不同阶段的精度选择不同阶段应该有不同策略。一个保守的实践方案是评估阶段先用FP32或原始权重推理得到“答案基线”。开发阶段切到BF16看结果和基线是否有明显差异。生产阶段再根据显存和延迟需求决定是否启用FP16或量化。这个顺序的出发点是先保证“结果正确”再优化“资源占用”。如果一上来就为了省显存切到FP16遇到不稳定的输出很难判断是模型能力问题还是精度问题排查成本会明显增加。还有一个细节是如果项目使用了量化工具需要在日志里记录量化前后同一批问题的输出对比。很多团队在模型量化的第一版会出现明显的效果回退但没有留下对比数据导致后面很难判断是量化还是Prompt改动引起的。5.3 精度不一致带来的问题精度不一致最常见的问题是数值敏感型任务结果抖动。比如一些对数字计算、逻辑推理、格式输出很敏感的任务在FP32下正常到了FP16下可能偶尔出现小数点偏差或格式错乱。另一个问题是日志和复现。如果团队A用FP32推理团队B用BF16推理两边对同一个问题的结果可能不一样。这不是模型版本不一致而是精度配置不一致。这种问题很难查尤其是当大家都觉得“半精度应该差不多”的时候。我的建议是把精度格式写进模型配置里和模型版本一起记录。复现问题或做评估时先确认精度格式一致。这样看似多余但在跨团队协作时能省下大量排查时间。5.4 精度和显存之外的工程细节精度配置经常和显存占用、部署方案一起讨论但工程化还要关注另外几个点推理服务并发和超时。同一个模型在批量并发时显存占用会上升如果不做限制可能出现OOM。输入长度动态变化。不同问题输入长度差异很大固定分配显存会导致浪费但动态分配又需要估算峰值。结果缓存。对高频相似问题做缓存能明显降低模型调用压力。日志结构化。记录每次请求的输入长度、精度格式、模型版本、检索到的文档ID便于回溯。这些点看起来零碎却是RAG系统能否稳定运行的关键。很多项目在初期只关注“模型能不能答对”但上线后真正考验的是“系统在负载下还能不能稳定地答对”。6. 从传统RAG到Agentic RAG再回到稳定可控6.1 传统RAG与Agentic RAG的差别传统RAG是单向流程用户问题→检索→生成→返回。Agentic RAG则会引入一个Agent来动态规划流程。比如Agent先判断用户问法是否需要去查外部工具再决定是直接生成还是先走检索或者先拆解问题再分多次检索。这个变化意味着什么传统RAG适合“用户问题直接检索知识库”的多数场景Agentic RAG适合“问题边界模糊、信息分散、需要多步决策”的场景。Part 2把Agentic RAG作为一个进阶方向来讲也是这个逻辑先掌握稳定的传统RAG再引入Agent来增强。如果基础RAG的质量都不稳定引入Agent只会放大问题。6.2 何时适合引入Agent我的判断是以下信号出现时可以考虑引入Agent用户问题经常需要分两步以上才能回答。同一个问题需要检索多个不同来源才能拼出完整答案。用户问题经常依赖上下文才能确定意图直接检索容易偏。需要调用外部工具来补充信息而不只是从向量库取内容。但如果知识库结构简单、问题单一传统RAG就够了。引入Agent会带来额外的延迟、成本和不确定性维护上也更复杂。需要说清楚的一点是Agent不是“更聪明的RAG”而是一种流程控制机制。它让系统在面对复杂问题时有能力拆分步骤、选择工具、验证结果。但这同时也意味着系统的行为不再是完全确定性的调试和回归的难度会变大。6.3 工程化落地时的风险控制引入Agent之后最需要注意的是“控制边界”。常见方法给Agent限定可调用的工具范围不开放无限制规划。设置最大迭代次数避免死循环。对关键步骤做日志埋点方便回溯。保留“降级路径”Agent计划失败时直接回到传统RAG。一句话Agent可以补充灵活性但不能让系统失去可解释性。真正重要的不是功能多花哨而是出问题的时候能不能快速定位是哪一层出了问题。如果你用的是比较重的平台或框架还要注意Agent相关配置是不是容易失控。比如工具调用权限、外部API的鉴权、Prompt注入防护等。这些话题展开会很长但核心原则是一致的引入能力的同时要同步引入约束。6.4 RAG、微调与Agent怎么组合很多人会问RAG和模型微调到底怎么选。我的理解是它们解决的是两类不同问题。RAG解决的是“知识更新和外部资料引用”的问题。它适合业务知识频繁变化、需要引用具体来源的场景。微调解决的是“模型行为模式不对”的问题。它适合模型格式不稳定、语气不对、工具调用规范不符合预期的场景。Agent则解决的是“复杂任务需要动态规划”的问题。它坐在RAG和微调之上负责调度。所以技术选型不是二选一。常见的组合方式是用RAG管理知识库用微调固定输出格式用Agent处理多步决策。但这套组合对团队和运维的要求都很高建议一次只做一项改造每项上线前都跑一遍评估集。回到开头那个RAG知识库项目。我最后没有用什么复杂架构就是把解析做扎实了把评估集建起来了把精度格式记录清楚了再用最简单的检索流程上线。这个经验放到今天依然成立RAG的工程化不是拼模型强弱而是把数据、索引、评估和可观测性这些“琐碎但关键”的部分做成一套稳定流程。如果你的RAG项目卡住了别急着换大模型。先把文档解析、分块和评估重新看一遍。看起来慢实际是最快的一条路。 RAG工程化实战：从文档解析到评估指标的完整链路
去年在做一个RAG知识库项目时我连续踩了一个星期的坑。最终定位到的核心问题不在大模型也不在向量数据库而在PDF解析——表格里的内容总被切碎检索出来的上下文和问题完全对不上。把解析层重写之后效果立刻好转。这件事给我的体感很直接RAG的难点从来不是“怎么把大模型接进去”而是整个数据链路能不能扛住真实场景的复杂度。最近系统梳理Udemy那门《AI LLM Engineering Mastery: GenAI, RAG Complete Guide》Part 2的学习笔记时这个感受又被反复印证。Part 2的重点不是基础概念而是从文档解析到评估指标、再到Agent化的完整工程链路。很多教程喜欢把RAG讲成一个“三步走”方案加载文档、向量化、交给大模型。但真实项目里这三步每一步都能裂变成一堆细节。这篇文章不打算复述课程目录而是结合项目实战经验把RAG链路按“解析→分块→索引→评估→精度→Agent化”的顺序拆一遍。适合那些已经跑通过demo、正准备把RAG放进真实业务的读者。1. RAG入门之后真正的分水岭在工程化1.1 为什么demo能跑生产却问题不断很多人第一次接触RAG用的都是现成例子一个PDF放进去按固定长度切块embedding之后存到向量库再用LangChain或LlamaIndex把检索结果拼进Prompt最后让模型生成答案。这一套在演示环境里通常很丝滑因为样例文档干净、问题经过筛选、没有并发压力、也不会有人问知识库边界之外的事情。一旦换成真实业务文档问题立刻涌现。常见的有PDF里的表格跨页切块后语义断裂。扫描件没有OCR层检索质量急剧下降。Word文档带批注、文本框、页眉页脚解析出来全是噪音。不同来源的文档元数据不统一过滤时无从下手。用户问法和知识库原文的表述差异太大直接向量检索召不回内容。这些问题的共性是它们都不在模型层而在数据工程层。RAG系统的上限首先由数据管道的质量决定其次才是模型能力。Part 2花了大量篇幅讲“文档加载解析详细全流程”原因就在这里——它不是最显眼的部分但它是决定成败的部分。这里先给一个核心判断任何RAG项目都应该把大部分精力花在“让检索之前的一切变得可靠”上而不是反复调Prompt和换模型。理由很直接——检索喂进去的内容本身就是错乱的再强的生成能力也只是建立在错误上下文之上。1.2 RAG完整链路从文档到生成既然要谈工程化就要先把链路拆开。一个完整的RAG系统通常包含下面几个环节环节主要任务常见工具/方法文档加载读取不同格式的文件PDF、Word、Markdown、HTML解析器内容清理去页眉页脚、去噪音、保留表格结构文本清洗、OCR、版面分析分块把长文本切成适合向量化的片段固定长度、递归分割、语义分块向量化将文本块转成向量Embedding模型索引建向量索引、元数据索引向量数据库开源或云端检索根据问题召回相关片段向量检索、混合检索、重排序生成把检索结果组装成Prompt交给LLMPrompt模板、模型推理评估验证检索和生成的质量评估集、自动化指标这个链路里每一个环节都有“能做”和“能做好”的差距。比如文档加载能读到文字和能保留版面结构是两回事分块能切出片段和能切出语义完整的片段是两回事检索能返回相似内容与能返回当前问题真正需要的上下文也是两回事。Part 2的重点就在这些“两回事”上。它不是教你怎么调通一个RAG而是教你怎么把RAG调到可以交付给业务方使用。这个认知转变是从“会用工具”走向“能做工程”的分水岭。1.3 该先掌握框架还是先理解数据链路现在市面上RAG相关框架很多有LangChain、LlamaIndex这类开发框架也有Dify这类低代码平台还有Spring AI这种把大模型能力整合进Java生态的尝试。工具选型很容易让人陷入纠结但对初学者来说框架本身不是关键。我的建议是先手写一个最小链路不用任何重量级框架。用最朴素的代码完成从文档解析到向量化再到检索生成的过程。这个过程中你会被迫理解每一步在干什么解析器返回了什么结构分块之后文本变成了什么形态embedding之后的向量如何比较相似度检索到的片段又如何拼进Prompt。理解完这些底层机制再上手LangChain或Dify你会像看地图一样清晰框架只不过是把这些环节封装成了配置项和调用链。框架会更新、会变化但数据链路的底层问题一直都在。如果你已经完全理解链路直接用Dify这类平台做业务原型也完全合理。它的价值在于把重复劳动简化尤其适合快速验证。但要注意平台化工具降低了上手门槛并不意味着工程问题会自动消失。数据质量、评估闭环、权限管理这些事平台不会替你做。2. 文档加载与解析是RAG最容易被低估的环节2.1 PDF、Word、扫描件三类格式各有各的坑RAG项目中文档解析是第一个隐藏瓶颈。很多教程的代码只有三五行把PDF文件传给某个解析器得到文本完事。但真实场景里文本的版式、层级、表格信息一旦丢失后面的检索和生成都跟着失真。先说最常见的PDF。PDF本身不是一种“文档”格式而是一种“版面描述”格式。它记录的是一行行文字该放在哪里而不是“标题是什么”“表格有几行几列”。所以直接抽取文本时经常碰到标题层级丢失标题和正文混在一起。表格被按行读取单元格之间的关系被拆散。多栏排版的文档文字顺序错乱。页眉页脚和正文混入同一文本块。这会导致什么后果举个例子一个产品规格表里有“型号A支持10W快充”和“型号B支持50W快充”切块后可能变成两个互不关联的片段。用户问“哪款支持50W快充”模型检索到的内容里缺少“型号B”和“50W”的关联上下文答案自然不准。Word文档的问题也不小。它本身有结构但很多解析器没有把段落、表格、批注、文本框区分开。扫描件则是另一类问题——没有OCR层图片里的文字完全无法被检索到。现实业务中大量历史合同和票据恰恰是扫描件。2.2 解析流程的通用拆解从工程经验看一个稳定的解析流程通常包含四步格式识别按扩展名或文件头判断文档类型。内容提取调用对应解析器拿到粗文本。结构还原尽量还原标题、段落、表格、列表等结构。清洗过滤去掉页眉页脚、重复空行、乱码字符、无关批注。这里给一个通用示例结构表示文本解析脚本的主干。具体解析库需要结合你的环境选择代码只是骨架。def extract_document(file_path): file_type detect_file_type(file_path) # pdf / docx / md / html if file_type pdf: content extract_pdf_with_layout(file_path) # 尽量保留表格和层级 elif file_type docx: content extract_docx_with_structure(file_path) else: content extract_markdown_or_html(file_path) cleaned_content remove_noise(content) return cleaned_content注意这只是一个示例结构不是可以直接复制使用的代码。落地前要结合自己的文档库样本确认解析器对表格、多栏和字体大小的处理效果。不同解析库在版面还原能力上差异很大遇到复杂文档时宁可多花时间选型也不要盲目相信默认输出。2.3 小样本验证法文档解析这块我见过最多的错误是“没有验证直接批量跑”。结果几千份文档喂进去事后才知道一半都解析错了清洗成本和返工成本非常高。更稳妥的做法是五步从真实文档库里随机挑30份覆盖PDF、Word、扫描件等不同来源。把这30份全部解析一遍人工检查输出质量。统计失败率定位最常见的解析问题。针对问题调整解析器配置或增加预处理步骤。30份确认稳定之后再扩大到几百份做灰度验证。判断标准也很简单一份文档解析完标题层级是否保留、表格结构是否完整、正文顺序是否正确、噪音是否除净。这些表面上看起来和响应速度无关但决定了后续检索质量的基线。注意不要用样例文档验证解析流程一定要用真实业务文档。真实文档里的版式混乱程度通常远超样例数据。2.4 解析常见的排查顺序如果解析结果不理想不要急着换工具。先按下面的顺序排查看原始文件本身是否正常编码、缺损、加密、扫描清晰度。看解析器输出是完全是空还是文本错乱还是结构丢失。看是否涉及特殊版面表格、多栏、文本框、公式、图片。看清洗步骤是否过度有些清洗规则会把表格分隔符或者关键标点一起删掉。看文件规模和并发超过解析器单文件限制时结果可能被截断。这个排查顺序的核心思想是从“文件不可用”到“解析器不行”再到“清洗规则误伤”逐层缩小范围。如果不加区分很容易把解析问题误判成embedding或模型问题。3. 分块、向量化与索引决定召回质量的三块拼图3.1 分块策略怎么定文档解析完下一步是分块。分块直接影响检索质量因为它决定了向量化之后每个片段是否“语义完整”。常见的分块方式大致有几种分块方式基本思路适用场景固定长度分块按字符数或token数切分快速验证、通用场景递归字符分割先按段落再按句子逐级切分大部分文本型文档语义分块利用embedding或模型判断语义边界内容复杂、主题切换频繁的文档结构分块按标题、表格、章节等结构切分手册、合同、法规等强结构文档固定长度分块是很多教程默认推荐的因为它简单。但它的缺点是经常把一句话、一个表格、一组对照关系切成两半。递归字符分割会好一些因为它会根据段落和句子来切。实践中更建议分层处理有明确结构的文档优先按结构分块。没有结构的长文本用递归分割再设置合理的块大小和重叠。块大小要根据embedding模型的上下文长度来确定。对同一文档可以保留多种块策略检索时按元数据选择。这部分没有标准答案因为分块是否合理最终要用检索效果来验证。重要的是先建立“分块效果可以观察”的意识而不是套一个固定参数就完事。3.2 向量化模型选型和使用分块之后是向量化也就是用embedding模型把文本转成向量。这一步有四个关键点模型上下文长度。如果embedding模型支持的最大输入长度是512个token那你的块就不要无脑设成1000个token。文本规范化。同一批文档的大小写、标点、换行格式最好统一避免无意义的向量漂移。批量向量化。大规模场景不要一条条调接口要批量提交能明显降低耗时和成本。向量化结果的缓存。同一份文档如果只改了后续版本可以复用未变化部分的向量减少重复计算。很多项目的第一步和第二步都会出问题。比如分块大小和模型上下文不匹配文本被截断导致语义信息丢失比如同一份文档在不同版本里格式不一致向量检索时出现不可解释的偏差。embedding模型选型时还要注意语言的匹配度。如果你的知识库以中文为主就要优先选择中文效果好的模型并针对自己的业务术语做小规模检索测试。不要只看公开榜单分数要拿自己的问题去测。3.3 元数据过滤与索引设计RAG项目做到后面单纯靠向量相似度往往不够。一个常见的改善手段是“元数据过滤”。比如只从某一类文档里检索。只检索最近一段时间内的内容。只检索某个部门或某个产品线的知识。根据文档类型过滤掉FAQ或公告。这些都需要在向量化时保留元数据并在检索时把元数据条件作为过滤器。常见的做法是把元数据和向量放在同一行记录里例如{ id: doc_001_chunk_003, text: 型号B支持50W快充……, embedding: [...], metadata: { source: product_spec_2025.pdf, doc_type: spec, category: charger, updated_at: 2025-01-15 } }有了这样的结构检索时就可以先按metadata过滤再算向量相似度也可以在向量相似度基础上加一层重排序。很多RAG项目召回质量差不是embedding模型不够强而是没有利用好元数据这个“先验条件”。3.4 为什么调了embedding模型效果还是不稳定这是RAG项目中非常普遍的现象换了更强的embedding模型检索结果却没有明显变好。原因通常不在embedding模型本身而在前面的步骤。最常见的情况是分块方式没有跟着变。比如之前是固定512字换了embedding模型后模型能处理的上下文长度变了块大小却没有同步调整结果长尾句被截断语义信息照旧丢失。另一种情况是文档解析质量不稳定。同样一份文档解析器不同得到的文本结构不同向量化后的空间分布也就不同。这种情况下embedding模型的差异被解析噪声掩盖了。所以遇到检索效果不好优先排查的是“输入到embedding模型的那段文本是不是干净的、语义完整的”而不是立刻怀疑模型选型。这条经验在多个项目里都验证过。4. RAG评估指标不能靠“看着不错”4.1 检索层指标RAG效果好不好不能只看“模型回答得顺不顺”。因为即使检索到的内容完全无关大模型也能编出一段看起来很流畅的答案。所以要建立一套系统化的评估指标。检索层关注的是“召回的片段是否真的对”。常用指标有RecallK前K个结果里包含多少个相关文档。PrecisionK前K个结果里真正相关的比例。MRR第一个正确结果排在第几位。NDCG考虑排序位置的相关性折损。实践里我建议先盯RecallK。因为RAG生成答案的前提是相关上下文被召回。如果相关片段根本没进前几名后面的生成质量基本无从谈起。4.2 生成层指标生成层的指标目前常用的有指标关注点通俗解释Faithfulness / Groundedness答案是否忠于检索到的上下文有没有在知识库之外瞎编Answer Relevance答案是否对应用户的问题答非所问会拉低分数Context Relevance检索到的上下文是否和问题相关上下文不相关但答案流畅也是问题这三个指标可以组成一个固定的评估模板。也有的团队用RAGAS这类开源评估框架来批量计算。不过如果用自动评估框架建议先在小样本上人工核对分数是否合理。自动评估模型本身也有误差不要完全交给机器。4.3 构建自己的评估集评估指标不是随便定的它需要一组“已知正确”的问题和上下文来跑。我把评估集建设的思路总结为三步从真实用户问题里挑50到100条覆盖常见问题、边角问题和反例问题。对每个问题人工标注出知识库中对应的正确文档片段。用这组数据分别跑检索和生成记录指标分数。评估集不必一开始做得很大但一定要覆盖业务真实场景。否则指标好看上线照样翻车。这里额外提醒一点评估集要持续积累。每出现一个线上失败的Case就把它补进评估集。时间长了评估集本身会变成团队最宝贵的资产。它能防止同一个问题反复发生也能让模型迭代有据可依。4.4 评估分数低时怎么定位是哪个环节出了问题评估分数不理想时不要笼统地说“效果不好”。要分环节定位。先看检索。把用户问题丢进检索层拉出前5个片段人工判断这些片段是否和问题真正相关。如果不相关问题在检索之前的链路解析、分块、向量化、索引、元数据过滤逐个排查。再看生成。如果检索到的片段是相关的但最终答案不对问题就在生成侧Prompt构造是否清晰、上下文是否被截断、模型是否遵循指令、是否引入了无关信息。一个可复用的小技巧是先不看最终答案只看检索出来的片段。如果片段质量本身很高再排查生成环节。这一步能快速把问题范围缩小一半。注意评估分数的意义是“发现问题”不是“证明上线”。如果评估集只包含简单问题分数再高也不代表生产环境没问题。5. LLM精度细节FP16、FP32、BF16工程化绕不开的底层配置5.1 三种精度格式的核心差异RAG项目做到工程化会碰到一个绕不开的底层话题LLM的精度格式。这跟算法本身无关但它直接影响显存占用、推理速度和结果稳定性。FP32、FP16、BF16是现在最常碰到的三种格式。格式全称指数位尾数位特点FP32单精度浮点数8位23位精度高占用大FP16半精度浮点数5位10位占用减半但表示范围窄BF16脑浮点数8位7位和FP32指数范围一致但尾数更少简单理解FP16的优点是省显存、算得快缺点是数值范围小容易出现上溢或下溢。BF16的指数范围和FP32一样所以数值范围更稳但尾数精度低。深度学习场景对尾数精度不那么敏感所以BF16在训练和推理中都很常用。很多模型在训练时用的是BF16或FP16混合精度。到了推理阶段为了省显存也会切到半精度。这里的风险在于如果训练时使用的精度和推理时不一致某些数值敏感的任务可能会表现出微妙但不可忽视的结果差异。5.2 不同阶段的精度选择不同阶段应该有不同策略。一个保守的实践方案是评估阶段先用FP32或原始权重推理得到“答案基线”。开发阶段切到BF16看结果和基线是否有明显差异。生产阶段再根据显存和延迟需求决定是否启用FP16或量化。这个顺序的出发点是先保证“结果正确”再优化“资源占用”。如果一上来就为了省显存切到FP16遇到不稳定的输出很难判断是模型能力问题还是精度问题排查成本会明显增加。还有一个细节是如果项目使用了量化工具需要在日志里记录量化前后同一批问题的输出对比。很多团队在模型量化的第一版会出现明显的效果回退但没有留下对比数据导致后面很难判断是量化还是Prompt改动引起的。5.3 精度不一致带来的问题精度不一致最常见的问题是数值敏感型任务结果抖动。比如一些对数字计算、逻辑推理、格式输出很敏感的任务在FP32下正常到了FP16下可能偶尔出现小数点偏差或格式错乱。另一个问题是日志和复现。如果团队A用FP32推理团队B用BF16推理两边对同一个问题的结果可能不一样。这不是模型版本不一致而是精度配置不一致。这种问题很难查尤其是当大家都觉得“半精度应该差不多”的时候。我的建议是把精度格式写进模型配置里和模型版本一起记录。复现问题或做评估时先确认精度格式一致。这样看似多余但在跨团队协作时能省下大量排查时间。5.4 精度和显存之外的工程细节精度配置经常和显存占用、部署方案一起讨论但工程化还要关注另外几个点推理服务并发和超时。同一个模型在批量并发时显存占用会上升如果不做限制可能出现OOM。输入长度动态变化。不同问题输入长度差异很大固定分配显存会导致浪费但动态分配又需要估算峰值。结果缓存。对高频相似问题做缓存能明显降低模型调用压力。日志结构化。记录每次请求的输入长度、精度格式、模型版本、检索到的文档ID便于回溯。这些点看起来零碎却是RAG系统能否稳定运行的关键。很多项目在初期只关注“模型能不能答对”但上线后真正考验的是“系统在负载下还能不能稳定地答对”。6. 从传统RAG到Agentic RAG再回到稳定可控6.1 传统RAG与Agentic RAG的差别传统RAG是单向流程用户问题→检索→生成→返回。Agentic RAG则会引入一个Agent来动态规划流程。比如Agent先判断用户问法是否需要去查外部工具再决定是直接生成还是先走检索或者先拆解问题再分多次检索。这个变化意味着什么传统RAG适合“用户问题直接检索知识库”的多数场景Agentic RAG适合“问题边界模糊、信息分散、需要多步决策”的场景。Part 2把Agentic RAG作为一个进阶方向来讲也是这个逻辑先掌握稳定的传统RAG再引入Agent来增强。如果基础RAG的质量都不稳定引入Agent只会放大问题。6.2 何时适合引入Agent我的判断是以下信号出现时可以考虑引入Agent用户问题经常需要分两步以上才能回答。同一个问题需要检索多个不同来源才能拼出完整答案。用户问题经常依赖上下文才能确定意图直接检索容易偏。需要调用外部工具来补充信息而不只是从向量库取内容。但如果知识库结构简单、问题单一传统RAG就够了。引入Agent会带来额外的延迟、成本和不确定性维护上也更复杂。需要说清楚的一点是Agent不是“更聪明的RAG”而是一种流程控制机制。它让系统在面对复杂问题时有能力拆分步骤、选择工具、验证结果。但这同时也意味着系统的行为不再是完全确定性的调试和回归的难度会变大。6.3 工程化落地时的风险控制引入Agent之后最需要注意的是“控制边界”。常见方法给Agent限定可调用的工具范围不开放无限制规划。设置最大迭代次数避免死循环。对关键步骤做日志埋点方便回溯。保留“降级路径”Agent计划失败时直接回到传统RAG。一句话Agent可以补充灵活性但不能让系统失去可解释性。真正重要的不是功能多花哨而是出问题的时候能不能快速定位是哪一层出了问题。如果你用的是比较重的平台或框架还要注意Agent相关配置是不是容易失控。比如工具调用权限、外部API的鉴权、Prompt注入防护等。这些话题展开会很长但核心原则是一致的引入能力的同时要同步引入约束。6.4 RAG、微调与Agent怎么组合很多人会问RAG和模型微调到底怎么选。我的理解是它们解决的是两类不同问题。RAG解决的是“知识更新和外部资料引用”的问题。它适合业务知识频繁变化、需要引用具体来源的场景。微调解决的是“模型行为模式不对”的问题。它适合模型格式不稳定、语气不对、工具调用规范不符合预期的场景。Agent则解决的是“复杂任务需要动态规划”的问题。它坐在RAG和微调之上负责调度。所以技术选型不是二选一。常见的组合方式是用RAG管理知识库用微调固定输出格式用Agent处理多步决策。但这套组合对团队和运维的要求都很高建议一次只做一项改造每项上线前都跑一遍评估集。回到开头那个RAG知识库项目。我最后没有用什么复杂架构就是把解析做扎实了把评估集建起来了把精度格式记录清楚了再用最简单的检索流程上线。这个经验放到今天依然成立RAG的工程化不是拼模型强弱而是把数据、索引、评估和可观测性这些“琐碎但关键”的部分做成一套稳定流程。如果你的RAG项目卡住了别急着换大模型。先把文档解析、分块和评估重新看一遍。看起来慢实际是最快的一条路。