检索质检递归轮次证据明细补充方案

项目地址：https://github.com/WiSiW/AI-RAG

摘要

当前检索质检模块已完整展示多粒度路由和多跳识别结果，无需重做。唯一缺口是递归轮次只显示 chunk_ids，页面未展开实际证据。此次仅扩展 MultiHopStep 的快照数据和轨迹面板，使每轮都能看到来源、章节、粒度、分数及召回路由。

后端数据与接口

  • 新增 TraceChunkSnapshot 类型，包含：
    chunk_id、document_id、source、section、granularity_level、granule_type、rrf_score、vector_score、bm25_score、matched_representations、content_snippet。
  • MultiHopStep 新增：
    • chunks：该轮实际召回的 chunk 快照列表。
    • route_counts：该轮按 BM25、L1、原块、摘要、问题、L3 去重后的路由命中数量。
    • granularity_counts：该轮 L1/L2/L3 的 chunk 数量。
  • 保留现有 chunk_ids 字段，兼容已有 UI、历史轨迹和 API 客户端。
  • 后端构造每轮轨迹时，从 round_outcome.chunks 生成快照：
    • 单轮最多保留 multihop_round_top_k 个块。
    • content_snippet 截取正文或上下文前 240 字。
    • 路由统计按 chunk_id 去重，不按表示行直接累加。
  • 对“无证据”“规划模型失败”“达到最大轮数”等停止分支也写入已有证据快照，确保停止原因有可核验依据。
  • SSE retrieval_step 的 payload 自动包含新增字段；SearchResponse 和消息 usage.retrieval_trace 同步持久化。

检索质检页面

  • 每轮轨迹卡片改为可展开明细，保留现有子问题、关键实体、新增数量、置信度和继续标记。
  • 展开后显示：
    • 路由命中标签：BM25、L1、原块、摘要、问题、L3。
    • 粒度统计：L1/L2/L3 数量。
    • Chunk 证据列表：来源、章节、粒度、动作类型、RRF/向量/BM25 分数、命中表示和内容摘要。
  • 未命中任何路由或旧历史轨迹只有 chunk_ids 时，展示兼容占位，不报错。
  • Chat 页面复用同一个 RetrievalTracePanel，因此多跳对话也能查看每轮证据。
  • 多粒度路由汇总和顶部多跳分类结果保持现状，不重复新增组件。

测试与验收

  • 构造两轮多跳检索，验证每轮 chunks 只包含该轮结果，累计结果与轮次结果不混淆。
  • 验证 route_counts 按 chunk_id 去重，granularity_counts 与快照数量一致。
  • 验证规划失败、无新增证据和最大轮数分支仍保存已有轮次快照。
  • 验证 Search API、SSE retrieval_step 和消息 usage 返回新增字段。
  • 前端验证轮次折叠、路由/粒度统计、chunk 证据列表和缺少快照的兼容展示，并通过生产构建。
  • 保持现有单跳检索、多粒度召回、Rerank、上下文窗口和不确定提示行为不变。

假设与默认值

  • 轮次快照表示该轮原始召回证据，不表示最终 Rerank 后的结果。
  • 每轮最多展示当前配置的候选数，默认 8 个；超出部分以数量提示。
  • 历史消息如果没有轮次快照，只显示原有子问题和数量统计。
  • 本次只修改轨迹数据结构与展示，不调整分类阈值、递归停止条件或检索权重。

最后更新： 2026年11月03日 15:01