从“答错了”到“错在哪”：RAG 检索诊断接口设计

这篇笔记由 2026 年 7 月考试 RAG Agent 平台的阶段记录整理成文，重点记录诊断思路，不把一次样例结果包装成普遍指标。

考试题库是一个很适合暴露 RAG 缺陷的场景。问题常常依赖一段材料、图表或公式；如果材料缺失，模型仍可能凭常识给出流畅答案。用户看到的只是“答错了”，研发人员却需要判断错误发生在存储、解析、召回、重排还是生成阶段。

我为此设计诊断接口时，目标不是再返回一个答案，而是返回一份可以追踪的检索报告。

1. 诊断输入要保留业务语义#

普通搜索接口通常只接收 query。考试场景还需要题干、材料、选项、科目和题型。材料不能默认从题干里推断，而应明确读取业务字段；当材料字段为空时，诊断结果要直接标记，而不是悄悄跳过。

这一点非常重要：接口健康、数据库有题目、知识库有文档，三者都不等于这道题所依赖的材料已经被正确存储。

2. 返回每个阶段，而不是只返回最终 top-k#

诊断响应可以分为以下层次：

1
request
2
  ├─ normalized_query
3
  ├─ material_status
4
  └─ key_phrases
5
retrieval
6
  ├─ bm25_candidates
7
  ├─ vector_candidates
8
  ├─ rrf_candidates
9
  └─ reranked_candidates
10
coverage
11
  ├─ matched_phrases
12
  └─ missing_phrases
13
context
14
  └─ final_chunks

候选条目至少保留文档标识、片段标识、原文摘要、分数、排名和召回来源。这样，开发者能够看到目标片段是否被 BM25 命中、是否只出现在向量结果中、RRF 后排名如何，以及是否在重排阶段被挤出上下文。

3. 关键短语覆盖比单一分数更直观#

相似度分数难以直接解释“为什么这道题缺证据”。我会从题干和材料中提取有区分度的实体、术语和限定条件，再检查最终候选是否覆盖它们。

missing_phrases 不是新的相关性算法，而是一个面向排障的解释层。例如题目涉及“特定年份”“实验条件”和“图中曲线 B”，最终上下文只覆盖了主题词，却没有覆盖这些限定条件，那么即使相似度很高，回答仍可能错误。

这个字段还能指导下一步动作：

专有名词缺失：检查 BM25 分词与索引；
同义表达缺失：检查向量模型与查询改写；
材料限定条件缺失：检查业务字段和切分；
候选有覆盖但最终上下文缺失：检查重排、阈值和上下文预算。

4. 诊断接口不直接替生产参数背书#

一个样例召回成功，不代表当前阈值适用于所有科目。诊断接口的职责是暴露过程，而不是自动把 top-k、权重或阈值写回生产配置。参数调整应该基于覆盖不同题型的评测集，并比较召回、答案正确性、延迟和成本。

同样，RRF 的常数、BM25 与向量召回数量、重排 top-n 都只是起点。它们需要通过真实数据验证，不应被写成脱离数据集的“最佳实践数字”。

5. 错误路径也要可用#

诊断接口遇到材料缺失、知识库未索引、向量服务不可用或重排超时时，不应只返回 500。更有用的响应是保留已经完成的阶段，并通过状态字段说明停止原因。例如 BM25 已得到结果、向量服务失败，报告仍可返回关键词候选，同时标记混合检索未完成。

这让诊断工具本身不会成为新的黑盒，也方便前端把“系统错误”和“证据不足”用不同方式呈现。

6. 最终收获#

RAG 系统真正难维护的部分，不是写出一次能回答问题的 Demo，而是在它答错时能快速定位原因。一个好的诊断接口应该沿数据流保留证据、区分存储缺失与检索失败、展示关键短语覆盖，并把参数调优留给评测而不是直觉。

音乐