跳转至

RAG 排障

本页按“症状 -> 先看什么 -> 常见根因 -> 下一步动作”组织，目标是让维护者能快速判断问题是在 source 治理、摄取、向量健康、检索阶段，还是在纠错 / 回退 / rerank 这些后续阶段。

先用这套顺序判断

  1. 问题是“完全召回不到”还是“召回到了但不够准”
  2. 先分清是单个 source 问题，还是 Agent 挂载 / 会话可见性问题
  3. 再分清是 ingest 没完成、向量不健康，还是 retrieval 阶段排序有问题
  4. 只有在证据支持时再 rebuild，不要一上来就重建

症状 1: 文档上传成功，但对话查不到内容

先看什么

  1. document status
  2. document vector_status
  3. ingestion job status 和 status_message
  4. Agent 是否挂载了该 source

常见根因

  • 文档只上传到了 MinIO，但没有完成 live ingestion
  • ingest 失败，document 进入 failed
  • document 已 indexed，但 vector_status 不是健康状态
  • source 没挂到当前 Agent
  • source 已挂载，但本次会话不是这个 Agent 在执行

下一步动作

  • 如果 ingest 没完成，先看 ingestion job 失败信息
  • 如果 vector_status 异常，先跑 manual inspection 的 vector_health
  • 如果挂载关系不对，去 Agent Detail 修正 mounts

症状 2: Retrieval Test 能命中，但在线对话命不中

先看什么

  1. Retrieval Test 的 query 与线上 query 是否一致
  2. 线上会话实际使用的是哪个 Agent
  3. active sources 是否与测试时一致

常见根因

  • 测试 source 和线上 Agent 的可见 source 集合不同
  • 会话切换到了另一个 Agent / version
  • 对话时 query 被 multi-query、managed correction 或 rerank 阶段改写了最终排序

下一步动作

  1. 对线上同一次 turn 跑 RAG debug
  2. 对比 Retrieval Test 与 turn 级 active sources
  3. 看 rerank drift 和 final retrieved chunks 是否发生明显变化

症状 3: 已经召回 chunk，但回答仍然偏离

先看什么

  1. final retrieved chunks 的内容是否真的包含答案
  2. turn 里最终注入的上下文是否被截断或排序靠后
  3. managed correction source 是否覆盖了原始 source

常见根因

  • chunk 被召回了，但不是最相关的几个
  • query 命中了错误的 correction source
  • chunking 过碎或过粗，导致关键信息被拆散或稀释
  • rerank 后前几名被重新排序

下一步动作

  • 先看 rag_debug 的 final_retrieved_chunks
  • 再看 rerank_drift_top3
  • 如果怀疑 chunking，跑 chunking_preview

症状 4: 只有关键词能搜到，完整问题搜不到

先看什么

  1. RAG debug 中 keyword fallback 是否被触发
  2. vector recall 的 raw candidates 是否为空或分数太低

常见根因

  • embedding 对当前 query 表达不够稳定
  • query 太短、太口语化或包含中英混合短词
  • keyword fallback 在补位，但向量召回本身不足

下一步动作

  • 先确认 keyword fallback 是不是唯一命中来源
  • 如果是，优先考虑优化 source 内容组织或 chunking，而不是依赖 fallback 兜底
  • 必要时观察 multi-query 是否开启

症状 5: source 明明存在，但本次会话没有使用

先看什么

  1. source 是否 active
  2. source 是否挂载到当前 Agent
  3. source kind 是否是服务器维护的 managed source

常见根因

  • source 没挂载到当前 Agent
  • source 被停用
  • source 属于其他 Agent 的 managed correction source，不能手动跨 Agent 挂载

下一步动作

  • 去 Agent Detail 看 mounted sources
  • 对于 managed correction source，不要手动 mount/unmount，改走 correction publish 链路

症状 6: 文档显示 indexed，但检索健康不稳定

先看什么

  1. expected_point_count
  2. actual_point_count
  3. vector_verified_at
  4. vector_status

常见根因

  • 历史向量写入成功，但后续 collection 状态漂移
  • Qdrant 在某次核验时不可用，导致 verification_failed
  • 文档重建前后的 point count 已经不一致

下一步动作

  1. 跑 manual inspection 的 vector_health
  2. 如果 parse snapshot 存在，按建议走 snapshot rebuild
  3. 如果没有 snapshot，只能从原始文件重新 ingestion

症状 7: correction publish 后效果不稳定

先看什么

  1. correction 对应 ingestion job 是否完成
  2. managed correction document 是否创建成功
  3. correction source 是否被正确识别为 managed_correction

常见根因

  • correction publish 创建了文档，但 ingestion 未完成
  • correction source 已创建，但本次 turn 并没有实际走到该 source
  • 旧 correction 文档和新 revision 同时存在，造成行为混杂

下一步动作

  • 看 correction publish 对应 job 状态
  • 对发布后的 query 跑一次 RAG debug
  • 确认 final retrieved chunks 里是否真的出现 correction source 的 chunk

当前最有用的排障工具

工具 适合解决什么问题
Retrieval Test 某个 source 对某个 query 是否具备命中能力
RAG Debug 为什么召回 / 没召回，以及 final chunks 是怎么来的
Manual Inspection vector_health 向量点是否真的存在
Manual Inspection chunking_preview 改 chunking 后会长什么样
Snapshot Rebuild parse snapshot 还在时重建索引
Correction Publish 把线上纠错变成正式知识来源

高频根因总表

根因 典型症状
ingest 未完成 上传成功但完全查不到
Agent 未挂载 source Retrieval Test 能测通，线上对话不使用
vector_status 不健康 文档显示 indexed 但检索不稳定
chunking 不合适 能召回但信息不完整或相关性低
keyword fallback 在硬撑 只有短关键词能命中
correction source 生效异常 修正后仍被旧知识覆盖
rerank 改变最终排序 原始召回合理，但答案引用了别的 chunk

不要这样做

  • 不要看到召回差就立刻全量重建
  • 不要手动维护 managed correction source
  • 不要只看 status=indexed 就认定知识库健康
  • 不要只用单个演示 query 做结论，优先用真实问题集复验

相关页面