RAG 效果差的排查路径
RAG 效果差时，团队最常见的反应是换 Embedding、加 Reranker 或升级生成模型。偶尔会变好，但往往说不清是哪项改动生效，也无法防止问题再次出现。原因很简单：RAG 是一条多阶段流水线，“最终答案不对”只是表象，故障可能早在文档解析时就发生了。
更稳的做法是保留中间产物，用一组可复现问题从前往后排查。先找出第一个偏离预期的阶段，只改一个变量，再用同一批样本验证。下面是一条适合小团队直接照着执行的路径。
一、先固定失败样本和期望证据
不要从“用户觉得不好用”直接进入调参。先收集 20 至 50 个真实失败问题，为每个问题写下期望答案要点、必须引用的文档和允许接受的表达差异。若正确答案本身有争议，应先让业务负责人确认，而不是让模型替团队定义真相。
最小诊断记录应包含 query、租户与权限、检索过滤条件、候选片段及分数、最终送入模型的上下文、模型输出和策略版本。记录时对个人信息与敏感字段做脱敏，避免调试日志变成新的数据风险。
可以为每条样本标记首个失败阶段：
| 现象 | 优先检查 | 不要先做 |
|---|---|---|
| 正确文档从未入库 | 解析与索引 | 调 Prompt |
| 正确片段未进候选集 | 召回与过滤 | 换生成模型 |
| 正确片段有但排名低 | 排序与重排 | 扩大最终上下文 |
| 上下文正确但回答错 | Prompt 与生成 | 重做切片 |
| 偶发引用旧内容 | 版本与缓存 | 增加 temperature |
二、确认数据是否真的进入了索引
第一步不是搜索，而是核对“可被搜索的知识”是否完整。抽取失败、扫描 PDF 没做 OCR、表格被打散、标题层级丢失，都会让后续算法在错误输入上努力。随机抽样不够，应该针对失败样本反查源文档到索引的完整链路。
检查源文件标识、内容哈希、解析文本、切片数量、索引版本和更新时间。对于答案所在段落，直接在解析后的纯文本中搜索关键句；搜不到就停在数据层修复。若文档刚更新但仍召回旧片段，再核对删除传播和缓存失效，具体机制可参考 RAG 文档版本与索引一致性。
一个很实用的守门规则是：入库任务只有在“新片段写入、旧片段清理、计数核对”全部完成后才能切换为可查询版本。不要把“任务进程退出为零”当成内容完整。
三、单独测召回，不让生成结果干扰判断
召回阶段只回答一个问题：正确证据有没有进入候选集合。暂时关闭 Reranker 和生成模型，对每条测试 query 输出 Top K 片段。人工标注正确证据是否出现，再计算 hit rate，而不是凭几个好看的示例判断。
query -> 权限/metadata 过滤 -> 向量或关键词召回 -> Top K 候选
^ ^
先核对范围 再核对相关性若正确片段完全没有出现，按顺序检查过滤条件、切片边界、关键词与专有名词、Embedding 输入是否一致。中文缩写、产品型号和精确条款编号常适合混合检索；长问题可以先做查询改写，但必须保留原始 query 便于复现。
过滤器尤其要先审计。错误的 tenant_id、版本或状态条件会把正确文档挡在召回之前，再强的向量模型也无能为力。多租户和预过滤设计可参考 RAG Metadata Filter 设计。
四、再判断排序是否把正确证据压下去了
如果正确片段在 Top 20，却没进入最终 Top 5，问题才位于排序层。此时比较向量分数、关键词排名、融合分数和 Reranker 分数，观察正确片段在哪一步掉队。不要同时改融合权重、Top K 和重排模型，否则无法归因。
先建立一个简单基线：固定候选数量，分别跑纯向量、纯关键词和混合召回；选出召回稳定的方案后再加重排。Reranker 只能重排已召回候选，不能找回根本没出现的证据。是否值得增加这一层，可参照 RAG Reranker 选型与评测。
还要检查“看似相关但不可回答”的片段。例如目录、免责声明和重复页眉可能关键词很多，却没有答案。为它们加文档类型或章节字段，通常比反复调相似度阈值更直接。
五、检查上下文组装有没有破坏证据
候选片段正确，不代表模型看到的上下文正确。去重逻辑可能误删关键段落，token 预算可能从尾部截断，多个文档拼接后也可能丢失来源标识。应把最终 Prompt 原样保存，并确认期望证据实际存在且没有被截断。
上下文不是越长越好。重复和互相矛盾的片段会增加模型选择难度。建议按来源聚合相邻片段、保留标题与时间信息、删除完全重复内容，并为每段分配稳定引用 ID。若新旧政策冲突，应在检索层按有效版本过滤，而不是指望模型猜哪份更新。
对长文切片问题，不要只比较固定字符长度。用失败样本验证答案是否跨切片边界、标题是否随正文继承，以及表格行是否保留列名。专项评测方法可见 RAG Chunking 策略怎么评测。
六、最后才调 Prompt 与生成模型
当正确、简洁、无冲突的证据已经进入上下文，才轮到生成层。先用确定性较高的设置和清晰约束建立基线：只根据上下文回答；证据不足时明确拒答；关键结论附来源 ID；不要把常识补成文档事实。
把生成错误再分为三类：忽略证据、错误综合、无证据补全。前两类可通过调整上下文顺序、明确任务格式或增加小样例处理；第三类要强化拒答和引用校验。升级模型应作为可度量的实验：使用同一测试集比较正确性、引用一致性、延迟和成本，而不是只观察主观文风。
上线前把修复过的失败样本加入回归集。此后每次修改切片、Embedding、过滤、排序或 Prompt，都跑分阶段评测。完整指标设计可参考 RAG 评估框架：把检索和生成分开测。