RAG 管道故障模式：生产环境调试现场指南

RAG 管道会静默地失败。与崩溃的服务或抛出的异常不同，损坏的 RAG 管道仍然会返回答案。只不过是错误的答案、不完整的答案，或者被不应该到达 LLM 的信息所污染的答案。系统看起来运行正常，实际上却在输出无用的结果。

本指南编录了我们在生产 RAG 系统中反复看到的故障模式。每个条目遵循相同的结构：您观察到什么、为什么会发生以及如何修复。请收藏本页。当凌晨 2 点您的检索管道返回无意义的结果而您无法弄清原因时，您会需要它。

故障模式 1：检索未命中（相关文档存在但未被检索）

症状： LLM 说"我没有关于这个的信息"或虚构一个答案，即使正确的文档在您的向量存储中。用户报告系统"不知道"您明知已经索引的内容。

根本原因： 查询 embedding 和文档块 embedding 在向量空间中不够接近，尽管它们在语义上是相关的。这发生在以下情况：

• 查询使用的术语与源文档不同（用户询问"解雇员工"，文档使用"非自愿终止"）
• embedding 模型未在您的领域词汇上训练
• 块太大，用不相关的上下文稀释了 embedding
• 块太小，丢失了与查询匹配所需的语义含义

修复方法：

• 添加混合搜索层（BM25 关键词搜索与向量相似度并行）以捕获术语不匹配
• 在上线前用真实用户查询测试检索——不仅仅是您自己编写的查询
• 尝试不同的块大小：256-512 个 token 对大多数文档类型来说是一个合理的起点
• 如果您的内容使用专业词汇，考虑使用领域适配的 embedding 模型
• 添加查询扩展或重写，在 embedding 之前重新表述用户查询

故障模式 2：检索到错误的上下文（不相关的文档获得高分）

症状： LLM 给出自信但不正确的答案，引用了错误文档、错误章节或完全不同主题的信息。检索到的块看起来合理但与实际问题无关。

根本原因： 向量相似度不等于相关性。两个段落可以在语义上相似（相同领域、相同词汇），但一个对另一个并不相关。常见触发因素：

• 模板文本（页眉、页脚、免责声明）获得高相似度分数，因为它们到处出现
• 来自不同时间段或版本的文档未被区分
• 缺少元数据过滤器，因此搜索考虑整个语料库而不是相关子集

修复方法：

• 添加元数据过滤（日期、文档类型、部门、版本），使检索在相似度排序之前缩小搜索空间
• 在摄取过程中去除模板文本——在分块之前移除页眉、页脚和重复的免责声明
• 在初始检索之后实施重排序步骤，使用 cross-encoder 模型比原始余弦相似度更准确地评分查询-文档相关性
• 添加相关性阈值——如果块的相似度分数低于经过测试的最低值，则不要将其传递给 LLM

故障模式 3：过时的上下文（文档已过期）

症状： LLM 基于旧信息给出答案——上季度的定价、被替代的政策、已弃用的 API 端点。用户失去信任，因为他们知道信息已更改但系统仍给出旧答案。

根本原因： 向量存储包含已被更新或替换的文档的 embedding，而索引管道不检测或处理更新。这是生产中最常见的 RAG 故障，因为大多数团队构建了初始索引管道，但从未构建更新管道。

修复方法：

• 在元数据中实施带时间戳的文档版本控制，以便可以按新近度过滤
• 构建增量重新索引管道，检测更改的文档并仅重新 embed 更新的块
• 为每个块添加"上次索引"时间戳，并在上下文中将其呈现给 LLM，以便它可以提醒可能过时的信息
• 安排定期的完整重新索引作为安全网，即使您有增量更新
• 请参阅我们关于 embedding 漂移和过时向量 的深入分析以了解检测策略

故障模式 4：块边界损坏（答案跨块分裂）

症状： LLM 给出感觉不完整的部分答案，或者因为相关内容被分裂在块边界而组合了两个不相关部分的信息。用户描述答案"接近但缺少关键细节"。

根本原因： 固定大小分块在任意字符或 token 计数处分割文档，忽略语义边界。一个关键段落被一分为二。前半部分落在一个块中，后半部分在另一个块中。检索找到一半但找不到另一半。

修复方法：

• 使用尊重段落、节和标题边界的语义分块
• 添加块重叠（块大小的 10-20%），使边界内容出现在相邻的块中
• 对于结构化文档（法律合同、技术规范），按节层级而不是按大小分块
• 在每个块中包含父节标题，以便 LLM 即使对于节中间的块也有结构上下文
• 请参阅我们关于糟糕的块如何毒害 RAG 答案的文章以获取详细分析

故障模式 5：上下文窗口溢出（检索到太多上下文）

症状： LLM 忽略一些检索到的文档，给出仅引用第一个或最后一个块的答案（首因/近因偏差），或产生过于笼统的响应，不涉及上下文中的具体细节。

根本原因： 检索步骤返回太多块，超出了 LLM 的有效上下文利用能力。即使是拥有超过 128K 上下文窗口的模型，在上下文嘈杂或过多时也会表现出性能下降。当模型被埋在十页松散相关的文本中时，它无法区分信号和噪音。

修复方法：

• 将 top-k 检索减少到 3-5 个块而不是 10-20 个
• 添加重排序步骤，仅将排名最高的结果传递给 LLM
• 实施上下文压缩——在传递给模型之前，对检索到的块进行摘要或提取关键句子
• 使用您的特定文档类型，在不同上下文长度下测试模型的实际性能
• 考虑您是否需要所有块还是只需要最相关的那一个

故障模式 6：通过上下文泄露 PII

症状： LLM 的响应包含不应该向当前用户展示的文档中的个人姓名、电子邮件地址、电话号码或其他个人身份信息。合规团队提交事件报告。

根本原因： 包含 PII 的文档在未经编辑的情况下被索引，检索管道没有访问控制层。LLM 忠实地包含上下文中的任何内容，包括它不应该看到的敏感数据。

修复方法：

• 在文档解析和分块/embedding 之间添加 PII 编辑作为管道阶段
• 实施文档级和块级访问控制，使检索尊重用户权限
• 审计您的向量存储以查找 PII 暴露——在存储的块文本中搜索模式（电子邮件、电话号码、SSN）
• 请参阅我们关于 RAG 上下文窗口中的 PII 泄露 的指南以获取全面的预防框架

故障模式 7：尽管上下文正确仍产生幻觉

症状： 检索到了正确的文档并存在于上下文中，但 LLM 仍然生成不正确的信息。它可能综合了不在任何检索块中的事实，或误解上下文并得出错误的结论。

根本原因： LLM 将其参数知识（预训练数据）与提供的上下文混合，其参数知识占了上风。这在具有强先验的更大、更强模型中更为常见。当上下文与模型的训练数据相矛盾时也会发生——模型"信任自己"胜过信任上下文。

修复方法：

• 在系统提示中添加明确指令："仅根据提供的上下文回答。如果上下文不包含答案，请说明。"
• 使用更小的、经过微调的模型，这些模型被训练为忠实于上下文而不是依赖参数知识
• 实施引用要求——强制模型引用其参考的特定块
• 添加验证步骤，检查答案是否基于检索到的上下文
• 如果这是一个持续存在的问题，考虑针对上下文忠实度进行微调

故障模式 8：Embedding 模型不匹配

症状： 尽管分块良好且文档充足，所有查询的检索质量始终很差。相关文档的得分低于预期。切换到不同的 embedding 模型后结果发生了显著变化。

根本原因： embedding 模型是根据基准测试分数而不是领域适配性选择的。通用 embedding 模型在专业内容（医学、法律、金融）上可能表现不佳，因为它们未在该词汇上训练。此外，对索引和查询使用不同的 embedding 模型会产生无意义的相似度分数。

修复方法：

• 始终对索引和查询使用相同的 embedding 模型——这是不可协商的
• 在做出选择之前，用您的实际文档和实际查询测试多个 embedding 模型
• 对专业内容考虑使用特定领域或微调的 embedding 模型
• 运行检索评估：对于 50-100 个已知的查询-文档对，衡量正确文档是否出现在 top-k 结果中

诊断检查表

当您的 RAG 管道产生糟糕的结果时，按顺序完成此检查表：

1. 文档是否在存储中？ 检查源文档是否确实已被索引。摄取失败比您想象的更常见。
2. 块是否可检索？ 用源文档中的确切文本直接查询向量存储。如果精确匹配都失败了，您的 embedding 管道已损坏。
3. 对于真实查询是否检索到了正确的块？ 用实际用户查询测试，而不是您编写的合成查询。
4. 块的内容是否正确？ 阅读块的原始文本。它是完整的吗？它是否损坏？它是否包含回答问题所需的信息？
5. 上下文是否到达了 LLM？ 记录发送给模型的完整提示，包括所有检索到的上下文。确认没有内容被截断或丢弃。
6. LLM 是否在使用上下文？ 如果上下文正确但答案错误，问题出在生成步骤，而不是检索。

构建可观测的 RAG 管道

这些故障模式中的大多数共享一个共同的促成因素：缺乏可观测性。当您的 RAG 管道是一系列不可见的函数调用——文档解析、分块、embedding、检索、上下文组装、生成——诊断故障需要追溯几个月前在截止日期压力下编写的代码。

Ertas Data Suite 采用了不同的方法。RAG 管道的每个阶段都是画布上可见的节点——用于索引的 File Import、Parser、PII Redactor、RAG Chunker、Embedding、Vector Store Writer；用于检索的 API Endpoint、Query Embedder、Vector Search、Context Assembler、API Response。每个节点记录其输入和输出。当检索质量下降时，您可以检查每个阶段的确切输出，而无需向深埋的 Python 函数添加打印语句。

管道不是隐藏在 LangChain 抽象或 LlamaIndex 回调中。它是可见的、可审计的和可调试的——这正是当生产 RAG 在凌晨 2 点崩溃时您所需要的。

令人不安的真相

RAG 管道不是"设置后就忘记"的基础设施。它们是活的系统，随着文档变化、用户查询演变和 embedding 模型漂移而退化。每个在生产中部署 RAG 的团队最终都会遇到本目录中的大多数故障模式。快速恢复的团队和花数周调试的团队之间的区别在于可观测性：您能看到管道每个阶段在做什么，还是在猜测？

构建您的 RAG 管道，使您能够看到其内部。未来的您会感谢现在的自己。