Skip to content

排障手册:从现象到根因 ​

RAG 的故障几乎都表现为同一句话:“答案不对。”

1、先追一块正确证据 ​

固定问题、租户、知识库和 run_id,沿链路追正确块。下面数量都是示例,关键不是“越来越少”,而是 正确资料在哪里消失:

追踪正确块 C17,找到它消失的那一步
追踪正确块 C17,找到它消失的那一步C17 在索引里存在,召回排12,重排排2,却因上下文预算未进最终证据。应检查上下文组装,不是先换嵌入模型。索引:正确块 C17 存在召回 30 条:C17 排第 12重排留 8 条:C17 排第 2× 最终证据 3 条:C17 消失日志原因:上下文预算不足,被跳过先检查上下文组装,不要先换嵌入模型
示例 run_id=r017。数量减少本身不是故障;关键是正确证据在哪一步被丢掉。

定位后一次只改一个变量,再跑相关回归集。若证据没进 Prompt,先修上游,不要先改提示词。

2、上传与解析 ​

2.1 上传成功但文档不出现 ​

检查说明
接口返回是否 success=true,还是只看了 HTTP 200
文档 ID是否真的创建了记录
租户/知识库是否传错范围
去重是否被内容哈希判为重复
权限当前用户是否有列表可见权限
异步任务是否排队但未开始

HTTP 200 不代表业务成功。很多系统在响应体里用 success/code 表示结果,前端只看状态码会误判。

2.2 一直停留在“处理中” ​

可能原因证据处理
worker 未启动队列有积压、无消费日志启动/扩容 worker
任务异常退出最后心跳时间、错误日志重试、修 bug
外部服务超时解析/嵌入调用超时调超时、重试、降级
状态计数不一致子任务完成数 < 总数对账、修复状态
锁未释放同一文档重复卡住清理锁、加超时
文件过大页数/大小超限拆分、限制

“处理中”是一个状态,不是一个原因。要看子任务完成情况和最后错误。

2.3 解析内容缺失或错乱 ​

现象可能原因验证
扫描件全是空白没做 OCR看中间产物是否有文字
表格变成一列解析器不支持表格结构对比原页与解析结果
段落顺序乱多栏/页眉页脚干扰看版面分析结果
公式乱码公式未识别抽查公式区域
中文乱码编码错误检查文件编码
页码对不上解析器页码从 0 开始核对偏移

解析错误会在后面所有环节放大。先看中间产物,再看检索。

2.4 切分不合理 ​

  • 块太大:检索命中但噪声多,答案发散;
  • 块太小:语义不完整,模型缺上下文;
  • 切断表格/代码:关键行丢失;
  • 重叠过多:重复结果占满 top-k;
  • 标题与正文分离:块失去章节语义。

验证方法:随机抽 20 个块,问“只看这个块,能回答什么问题”。答不上来就是切分有问题。

3、索引与入库 ​

3.1 搜不到新文档 ​

按顺序查:

  1. 文档是否启用且具备检索条件(不能只看是否 completed);
  2. 块是否写入业务库;
  3. 向量是否写入索引;
  4. 索引版本是否已切换;
  5. 查询是否走了旧别名;
  6. 权限过滤是否把它排除了;
  7. 缓存是否返回了旧结果。

3.2 搜到旧内容 ​

原因处理
旧块未删除墓碑 + 清理任务
多版本共存版本过滤
索引未切换检查别名
缓存未失效缓存键加版本
文档更新但未重嵌入检查变更检测

“更新文档”不等于“更新索引”。要确认块被替换、旧块被删除、缓存被清理。

3.3 结果重复 ​

  • 同一文档多版本;
  • 父子块重叠;
  • 邻接扩展重复;
  • 多路召回同一块未去重;
  • 表格行文本高度相似。

去重要基于 chunk_id + 位置 + 内容哈希,不能只按文本相似度(可能误删不同的表格行)。

3.4 向量维度/模型不匹配 ​

症状:写入报错、检索报错、或结果完全无关。

检查:

  • 索引维度与模型输出维度;
  • 是否混用了不同模型的向量;
  • 归一化方式是否一致;
  • 度量方式(cosine/dot/l2)是否与索引配置一致;
  • 是否在切换模型后复用了旧索引。

换嵌入模型必须重建索引,不能只换查询侧。

4、检索 ​

4.1 完全搜不到 ​

检查说明
查询是否为空/被改写坏看改写结果
过滤器是否过严租户、标签、时间、状态
阈值是否过高重排阈值、相似度阈值
索引是否为空统计块数
分词是否失败中文分词、特殊符号
嵌入服务是否失败错误日志、降级标记

4.2 搜到了但排得靠后 ​

  • 只取 top-3,正确块在第 20;
  • 重排器与语料不匹配;
  • 融合权重偏向错误通道;
  • 缺少关键词召回;
  • 块本身语义不完整。

处理:扩大候选 → 加重排 → 看重排前后排名 → 用评估集验证。

4.3 关键词结果霸榜 ​

原因:分数直接相加、BM25 范围无界、权重过高。

处理:改用 RRF、归一化、限制单路数量、调权重。

4.4 语义漂移 ​

现象:问题问 A,召回一堆“看起来相关但答非所问”的块。

原因:

  • 嵌入模型对领域不敏感;
  • 块太长,主题混杂;
  • 查询改写引入了错误意图;
  • HyDE 假设答案跑偏。

处理:换/微调嵌入模型、缩小块、关掉改写对比、把 HyDE 改为并行一路。

4.5 多跳问题只召回一半 ​

  • 查询没有拆分;
  • 两段证据在不同文档,单次检索只覆盖一个;
  • 融合后只保留了一条。

处理:拆分 + 多轮检索 + 合并证据;或引入图/多步方案。

5、生成 ​

5.1 答案编造 ​

检查说明
证据是否真的包含答案逐条核对
提示词是否允许“根据常识补充”明确禁止
是否有拒答路径没有就会硬答
温度是否过高调低
是否放入了冲突证据模型自行“调和”

编造往往不是模型“不听话”,而是证据不足 + 没有拒答出口。

5.2 答案正确但没引用 ​

  • 提示词没有强制引用;
  • 证据没有编号;
  • 模型引用了不存在的编号被过滤;
  • 后处理把引用删了;
  • 流式输出把引用标记截断。

5.3 引用错误 ​

  • 编号与本轮证据不一致;
  • 多轮复用了旧编号;
  • 引用了父块开头而不是命中子块;
  • 引用文本不支持结论;
  • 编号在流式拼接时错位。

处理:每轮重新编号、只注册本轮证据、生成后校验、引用指向实际命中块。

5.4 答案过长/过短 ​

  • max_tokens 设置;
  • 证据数量;
  • 提示词的长度要求;
  • 是否把整篇文档塞入;
  • 是否被截断(看 finish_reason)。

5.5 拒答过多/过少 ​

现象可能原因
拒答过多阈值过高、召回差、提示词过严
拒答过少没有拒答规则、阈值过低、模型硬答
该拒答却给了数字冲突证据、提示词未约束
不该拒答却说不知道证据在但排名低、被截断

拒答率要和召回指标一起看。

6、引用与展示 ​

6.1 引用点不开 ​

  • 引用 ID 不存在;
  • 权限校验失败;
  • 签名 URL 过期;
  • 文档已删除;
  • 前端映射错误;
  • 流式 complete 早于落库。

6.2 引用定位不准 ​

  • 页码偏移;
  • 字符偏移基于清洗后文本,原文坐标不同;
  • 编辑后内容变化但坐标未更新;
  • 引用了父块范围。

定位要基于稳定的块 ID + 原文偏移,并在文档更新时重建。

6.3 刷新后消息消失 ​

典型原因:流式完成信号早于持久化。修复顺序:先落库,再发 complete;失败时发 error。

7、性能 ​

7.1 首字慢 ​

按阶段看:

  • 鉴权/范围解析;
  • 查询改写;
  • 嵌入;
  • 检索;
  • 重排;
  • 模型首 token。

常见原因:串行调用、重排候选过多、嵌入服务冷启动、向量库慢查询、Prompt 过长。

7.2 整体慢 ​

  • 证据太多,输入 token 大;
  • 历史太长;
  • 重排模型太大;
  • 多路召回串行;
  • 数据库 N+1 查询;
  • 流式被缓冲(代理/网关)。

7.3 超时与重试放大 ​

  • 重试没有上限;
  • 超时设置不合理;
  • 故障时所有请求同时重试;
  • 没有熔断。

要加退避、抖动、全局预算和熔断。

8、权限与多租户 ​

8.1 越权 ​

检查说明
过滤位置是否检索后才过滤
过滤字段租户/ACL 是否写入索引
共享规则归属租户与访问租户
缓存缓存键是否含租户/权限
引用点击时是否重新鉴权
日志是否泄露其他租户内容

越权是最高优先级问题,发现后先止血(关闭共享/清缓存),再修根因。

8.2 该看到的看不到 ​

  • ACL 未同步;
  • 标签范围取交集过严;
  • 共享未生效;
  • 索引中的租户字段错误;
  • 缓存了旧的空结果。

9、评估与指标异常 ​

9.1 离线指标涨,线上没感觉 ​

  • 测试集与真实分布不一致;
  • 指标被简单样本拉高;
  • 线上延迟/格式问题;
  • 用户真正关心的是引用可信度,不是 Recall@10。

9.2 指标突然下降 ​

按变更排查:

  • 模型版本;
  • Prompt;
  • 切分参数;
  • 索引版本;
  • 嵌入模型;
  • 数据集本身被修改;
  • judge 模型升级。

保存配置快照是排障的前提。

9.3 judge 分数不可信 ​

  • 未校准;
  • 位置/长度偏差;
  • judge 模型漂移;
  • 评分标准模糊;
  • 抽样偏差。

用人工标注的小集合定期复校。

10、高频根因清单 ​

按排查方向分组:

  1. 解析/OCR 质量差;
  2. 切分切断语义;
  3. 只有向量召回,缺关键词;
  4. top-k 太小;
  5. 分数直接相加;
  6. 重排缺失或不匹配;
  7. 证据没进 Prompt(预算截断);
  8. 提示词没有拒答出口;
  9. 引用编号错位;
  10. 权限过滤位置错误;
  11. 旧索引/旧缓存;
  12. 服务失败被当成“无资料”。

11、排障记录模板 ​

text
问题:
复现步骤:
run_id:
租户/知识库:
期望:
实际:
漏斗:召回 __ 条 → 融合 __ 条 → 重排 __ 条 → 最终 __ 条
正确块:是否在索引 / 排名 / 是否进 Prompt
根因:
最小修复:
回归验证:
遗留风险:

12、一句话总结 ​

排障不是“猜哪里坏了”,而是沿着数据流逐段取证,确认正确证据在哪一步消失,再做最小修复。

下一步:13 项目与资料,看可以对照阅读的开源实现与论文。

评论

正在加载评论…