16 KiB
RAG 回答异常排查手册
当知识库已经完成导入，模型也可以正常对话，但回答仍然出现偏题、命中错误内容、引用旧信息、结果忽好忽坏等情况时，问题通常不在“模型是否可用”，而在检索链路、索引状态、配置一致性、依赖服务状态，或上下文拼接过程。
本文提供一套面向实际使用场景的排查路径，帮助你在不大范围重配系统的前提下，先缩小问题范围，再做最小修复。
如果你正在处理“知识库似乎已经接入，但回答效果不稳定”的问题，建议按本文顺序逐步检查。
建议先判断异常类型，再开始修改配置。
同时调整多个变量，通常只会让问题更难定位。
快速定位：
异常自检 | 五步诊断 | 根因定位 | 平台检查点 | 修复顺序 | 提交 Issue
一、快速判断：你属于哪一种异常
如果你已经遇到以下情况，可以先快速对照，再进入后续排查步骤。
1. 明明接入了知识库，但回答像没有检索到任何内容
常见表现：
- 回答只基于通用知识，缺少业务内容
- 回答内容空泛，与已上传文档无明显关联
- 同一问题无论是否启用知识库，结果差异很小
优先怀疑方向：
- 知识库未真正进入可检索状态
- 文档导入完成，但索引尚未可用
- 请求没有进入检索链路，而是直接进入普通对话链路
2. 能检索到内容，但最终回答仍然不准确
常见表现：
- 检索结果里已经有正确片段，但最终回答仍然偏题
- 回答混入无关信息
- 关键片段存在，但没有被正确使用
优先怀疑方向：
- 切块策略不合理，导致关键信息被切散
- 检索条数设置不合理，召回内容过少或过多
- 上下文拼接过程存在污染或顺序异常
3. 同一个问题有时正确，有时错误
常见表现：
- 重复提问结果不稳定
- 改动不大，但结果波动明显
- 某些时段效果正常，另一些时段明显变差
优先怀疑方向：
- 请求链路不一致
- 依赖服务状态不稳定
- 配置修改后存在参数漂移
- 缓存或旧配置偶发生效
4. 知识库更新后，回答仍然引用旧内容
常见表现：
- 文档已更新，但回答仍然引用旧版本内容
- 删除旧文档后，旧答案仍然可以命中
- 新旧内容混杂，回答前后矛盾
优先怀疑方向：
- 索引更新未完成
- 查询仍指向旧集合、旧配置或旧范围
- 缓存未刷新，或旧数据未被正确移除
5. 多模型、多服务或多平台接入后结果异常
常见表现：
- 切换模型后回答质量突然变化
- 相同知识库在不同入口下结果不一致
- 明明配置相似，但不同环境效果差异很大
优先怀疑方向：
- 请求被路由到非预期目标
- 不同环境使用了不同的检索配置
- 模型层与检索层的参数没有同步调整
二、五步最小诊断流程
在开始修改配置之前，建议先按以下顺序排查。
这套流程的目标不是“立刻修好所有问题”，而是先尽快判断问题落在哪一层。
第一步：先确认问题是否可以稳定复现
先回答两个问题：
- 问题是每次都出现，还是偶发出现
- 问题是否只在特定模型、特定知识库、特定入口下出现
建议先固定以下条件，再做排查：
- 固定一个问题输入
- 固定一个模型
- 固定一个知识库范围
- 固定一个调用入口
- 连续测试两到三次，观察现象是否一致
如果问题本身不能稳定复现，优先记录触发条件，而不是立即修改多个配置。
第二步：确认知识库数据是否真正可用
不要只看“文档是否上传成功”，还要确认：
- 文档是否完成处理
- 是否完成切块
- 是否完成向量化
- 是否已写入目标存储
- 当前查询是否使用了正确的知识库范围
很多看起来像“模型回答异常”的问题，本质上是知识库并未进入可检索状态。
第三步：确认检索配置是否与数据形态匹配
重点检查以下项目：
- 切块大小是否过大，导致一个片段信息过杂
- 切块大小是否过小，导致语义被切碎
- 是否设置了合理的重叠，避免关键上下文断裂
- 检索条数是否过少，导致漏掉关键片段
- 检索条数是否过多，导致无关内容进入上下文
- 配置变更后，是否与现有索引状态保持一致
第四步：确认请求是否真的走了检索链路
有些问题看起来像“检索效果不好”，其实是“根本没有检索”。
建议确认：
- 当前入口是否启用了知识库检索
- 当前会话是否使用了正确的知识库范围
- 日志中是否能看到检索动作
- 日志中是否能看到召回结果
- 多服务接入时，请求是否命中了预期目标
如果请求未进入检索链路，再好的知识库配置也不会生效。
第五步：先归类，再做最小修复
不要在同一轮排查中同时修改模型、切块、检索条数、服务配置和依赖连接。
建议先将问题归类到以下其中一种方向，再做单点修复：
- 数据未生效
- 检索不合理
- 链路未命中
- 部署状态异常
- 结果拼接异常
先缩小范围，再逐步修复，通常会比一次性重配更快得到有效结果。
三、常见异常类型与根因定位
当你无法通过单一现象直接判断问题时，可以按下面四大类进行归类。
先判断“问题属于哪一类”，再决定下一步要查什么。
A. 数据与索引类
这类问题的特点是：知识库看似存在，但检索基础并不稳定。
1. 文档已上传，但未进入可检索状态
表现：
- 上传完成，但查询没有明显变化
- 不同文档都像没有被使用
- 结果与文档内容脱节
排查重点：
- 检查处理状态
- 检查索引是否完成
- 检查当前查询范围是否正确
2. 切块策略不合理
表现：
- 单个片段信息过多，主题混杂
- 关键句被拆散
- 召回片段读起来缺少上下文
排查重点：
- 检查切块大小
- 检查重叠策略
- 检查是否按文档类型区分切块方式
3. 向量化配置不一致
表现：
- 有召回，但命中质量明显异常
- 明明是相关问题，却命中很多弱相关内容
- 修改配置后效果突然恶化
排查重点：
- 检查配置是否前后一致
- 检查配置变更后是否需要重新处理
- 检查新旧配置是否混用
4. 索引更新不完整
表现：
- 更新后仍命中旧内容
- 删除后仍可查到旧答案
- 新内容迟迟不生效
排查重点：
- 检查更新流程是否完整执行
- 检查旧数据是否仍被引用
- 检查是否存在缓存或旧范围残留
B. 检索与链路类
这类问题的特点是：系统具有知识库能力，但请求没有正确使用它。
5. 请求未进入知识库检索流程
表现：
- 回答更像普通对话
- 不同知识库下回答几乎相同
- 日志中看不到检索动作
排查重点：
- 检查是否启用知识库模式
- 检查当前入口配置
- 检查日志中是否有召回记录
6. 检索范围配置错误
表现：
- 命中到了不相关的数据范围
- 应该命中的资料没有参与检索
- 不同业务资料互相干扰
排查重点：
- 检查当前会话绑定范围
- 检查查询目标是否正确
- 检查是否误用了旧范围或默认范围
7. 请求被路由到错误目标
表现：
- 不同入口结果差异异常大
- 同样配置在不同环境行为不同
- 切换后端后结果明显漂移
排查重点：
- 检查请求实际命中的服务
- 检查多环境配置是否一致
- 检查链路中是否存在错误转发
8. 检索条数或召回策略不合理
表现：
- 命中太少，遗漏关键内容
- 命中太多，带入大量噪声
- 回答被无关片段干扰
排查重点：
- 检查检索条数
- 检查召回策略
- 检查召回内容是否与问题真正相关
C. 部署与运行类
这类问题的特点是：逻辑上配置正确，但系统运行状态不完整。
9. 依赖服务未就绪
表现：
- 某些时候正常，某些时候失效
- 重启后暂时恢复
- 功能表面可用，但结果不稳定
排查重点：
- 检查依赖服务启动顺序
- 检查服务可达性
- 检查系统初始化是否完整
10. 连接异常或服务不可达
表现：
- 某个环节偶发失败
- 某些请求直接退化为无检索结果
- 日志中出现连接异常、超时或空结果
排查重点：
- 检查依赖连接状态
- 检查网络与端口可达性
- 检查异常时段的日志
11. 环境变量、密钥或配置缺失
表现：
- 部分功能可用，部分功能失效
- 同一套配置在新环境无法复现
- 迁移后问题突然出现
排查重点：
- 检查必要配置是否完整
- 检查配置是否被覆盖
- 检查环境切换后是否存在遗漏
12. 首次部署后状态不完整
表现：
- 系统看起来已经启动，但部分能力未真正可用
- 首次导入数据后效果异常
- 重建后暂时恢复，过一段时间又出现问题
排查重点：
- 检查首次初始化流程
- 检查状态是否完整落地
- 检查是否有必须执行但被跳过的步骤
D. 结果与观测类
这类问题的特点是：检索可能已有结果，但最终回答仍然不对。
13. 检索命中存在，但上下文拼接不合理
表现：
- 正确片段存在，但没有被回答使用
- 回答只引用了部分片段
- 片段顺序混乱，影响理解
排查重点：
- 检查上下文拼接顺序
- 检查是否截断了关键片段
- 检查最终输入给模型的上下文内容
14. 无关片段进入上下文，造成污染
表现：
- 回答中混入其他主题内容
- 本该准确回答，却出现明显跑题
- 一次问题引入了多个不相关片段
排查重点：
- 检查召回内容质量
- 检查检索条数是否过大
- 检查切块是否造成语义混杂
15. 缺少关键日志，无法判断问题层级
表现：
- 知道“结果不对”，但不知道错在哪里
- 无法确认是否发生了检索
- 无法确认是哪一层先出问题
排查重点：
- 保留请求输入
- 保留召回结果
- 保留最终回答
- 保留关键流程日志
16. 缺少最小复现，导致问题长期无法稳定定位
表现：
- 问题描述笼统，难以重复触发
- 每次排查都从头开始
- 多人协作时无法快速对齐
排查重点：
- 固定最小输入
- 固定测试条件
- 明确记录复现步骤
- 记录最近一次变更
如果你暂时无法确认根因，先不要全面重配。
先判断属于哪一大类，再做单点调整，通常会更快接近有效修复。
四、平台级检查点
当你已经确认问题属于 RAG 异常，但还无法判断具体落点时，建议优先检查以下项目。
这些检查点通常比“直接换模型”更有价值，也更能帮助你快速缩小范围。
1. 知识库状态
请先确认：
- 文档是否已完成导入
- 文档是否已完成处理
- 当前查询是否绑定了正确的知识库范围
- 同一问题在不同知识库范围下，结果是否符合预期
如果知识库状态本身不稳定，后续所有排查都可能失真。
2. 切块与内容组织
请重点检查：
- 切块是否过大，导致主题混杂
- 切块是否过小，导致关键上下文断裂
- 是否设置了合理的重叠
- 文本结构是否适合当前切块方式
不合理的切块，通常会直接导致“命中了也答不好”。
3. 检索配置
请重点检查：
- 检索条数是否合适
- 是否存在明显的弱相关召回
- 是否遗漏关键片段
- 修改配置后，结果是否按预期变化
如果你调整了检索配置，但结果完全没有变化，需要回头检查是否真的命中了当前配置。
4. 依赖连接与运行状态
请重点检查：
- 依赖服务是否全部就绪
- 查询过程中是否存在连接异常
- 某些时段是否出现明显波动
- 重启后是否出现短暂恢复
偶发异常，通常和运行状态有关，不一定是逻辑错误。
5. 最终生成环节
请重点检查：
- 召回结果是否被完整传入生成环节
- 最终回答是否明显脱离召回内容
- 是否存在无关片段进入最终上下文
- 是否能从日志中对照“输入、召回、回答”的完整路径
如果你只能看到最终答案，看不到召回内容，排查效率会显著下降。
五、优先修复顺序
当问题已经被初步定位后，建议按下面顺序处理，而不是一次性调整全部配置。
按优先级逐步修复，可以更快判断哪一项改动真正有效。
优先级 1：先确认数据是否真的可检索
如果知识库尚未进入可检索状态，后续所有调参都没有意义。
请先确认文档处理、索引状态、查询范围是否正确。
优先级 2：再确认请求是否走了正确链路
如果请求根本没有进入检索流程，或者命中了错误目标，那么问题不在“回答质量”，而在“链路路径”。
优先级 3：再调整切块、检索条数与召回范围
这是最常见的效果问题来源，但应该建立在前两项确认完成的前提下。
否则你可能会把“链路问题”误判成“参数问题”。
优先级 4：最后再处理结果生成层问题
很多看起来像“模型回答不好”的问题，实际上仍然来自检索侧或上下文侧。
因此模型层调优应放在最后，而不是一开始就扩大改动范围。
修复时的建议做法
- 每次只修改一个关键变量
- 修改前后使用相同问题进行对比
- 同时保留召回结果与最终回答
- 记录本轮修改内容，避免回头时无法对照
只改一个变量，通常比一次性改五个参数更容易找到真正的原因。
上一节：平台检查点 | 返回顶部 | 下一节：提交 Issue
六、仍无法定位时，如何提交有效 Issue
如果你已经完成基础排查，但问题仍然无法确认位置，建议在提交 Issue 前先整理以下信息。
高质量的问题描述，通常比大量截图更能帮助快速定位。
最少应提供的信息
- 问题现象的简要描述
- 最小可复现步骤
- 当前使用的模型
- 当前是否启用了知识库检索
- 当前知识库范围或相关配置
- 检索结果与最终回答的差异
- 关键日志、报错或异常现象
- 最近一次配置变更内容
推荐的描述方式
- 先说明现象，不要只写“结果不对”
- 再说明如何复现，让他人可以重复触发
- 再说明你已经检查过哪些项目
- 如果问题是偶发的，请说明出现频率和触发条件
推荐的最小问题模板
问题现象：
回答出现偏题 / 未命中知识库 / 引用旧内容 / 结果不稳定（选择其一或补充说明）
复现步骤：
1.
2.
3.
当前配置：
1. 使用模型：
2. 是否启用知识库：
3. 知识库范围：
4. 最近是否修改过配置：
实际结果：
（描述当前返回结果）
预期结果：
（描述你期望得到的结果）
已检查项目：
1.
2.
3.
补充日志或报错：
（如有可补充）
提供清晰、可复现的信息，通常比直接贴出大量无上下文截图更有助于定位问题，也能显著提高排查效率。