排障手册:从现象到根因
RAG 的故障几乎都表现为同一句话:“答案不对。”
1、先追一块正确证据
固定问题、租户、知识库和 run_id,沿链路追正确块。下面数量都是示例,关键不是“越来越少”,而是 正确资料在哪里消失:
定位后一次只改一个变量,再跑相关回归集。若证据没进 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 搜不到新文档
按顺序查:
- 文档是否启用且具备检索条件(不能只看是否
completed); - 块是否写入业务库;
- 向量是否写入索引;
- 索引版本是否已切换;
- 查询是否走了旧别名;
- 权限过滤是否把它排除了;
- 缓存是否返回了旧结果。
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、高频根因清单
按排查方向分组:
- 解析/
OCR质量差; - 切分切断语义;
- 只有向量召回,缺关键词;
top-k太小;- 分数直接相加;
- 重排缺失或不匹配;
- 证据没进
Prompt(预算截断); - 提示词没有拒答出口;
- 引用编号错位;
- 权限过滤位置错误;
- 旧索引/旧缓存;
- 服务失败被当成“无资料”。
11、排障记录模板
问题:
复现步骤:
run_id:
租户/知识库:
期望:
实际:
漏斗:召回 __ 条 → 融合 __ 条 → 重排 __ 条 → 最终 __ 条
正确块:是否在索引 / 排名 / 是否进 Prompt
根因:
最小修复:
回归验证:
遗留风险:12、一句话总结
排障不是“猜哪里坏了”,而是沿着数据流逐段取证,确认正确证据在哪一步消失,再做最小修复。
下一步:13 项目与资料,看可以对照阅读的开源实现与论文。
评论
正在加载评论…