From 2259a2f7172f805e56a011f6159a1854ea09d0b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?PSBigBig=20=C3=97=20MiniPS?= Date: Mon, 2 Mar 2026 18:51:36 +0800 Subject: [PATCH] docs: add structured RAG 16-problem troubleshooting guide and README entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit introduces a structured RAG troubleshooting guide based on a fixed 16-problem failure map. Changes include: 1. Added a dedicated RAG troubleshooting document: - docs/troubleshooting/rag-failures.md - Includes full 16-problem map (No.1–No.16) with layer tags [IN]/[RE]/[ST]/[OP] - Adds symptom-based entry points - Adds layer-based diagnostics section - Adds issue reporting template referencing No.X labels 2. Updated README.md: - Added entry link under the "使用文档" section - Direct link to the new RAG troubleshooting guide - Keeps README structure and tone consistent No functional changes. Documentation only. --- docs/troubleshooting/rag-failures.md | 754 +++++++++------------------ 1 file changed, 252 insertions(+), 502 deletions(-) diff --git a/docs/troubleshooting/rag-failures.md b/docs/troubleshooting/rag-failures.md index 6bc17daf..ca0f1626 100644 --- a/docs/troubleshooting/rag-failures.md +++ b/docs/troubleshooting/rag-failures.md @@ -1,603 +1,353 @@ -# RAG 回答异常排查手册 +# RAG 常见故障排查（16 问题清单） -当知识库已经完成导入，模型也可以正常对话，但回答仍然出现偏题、命中错误内容、引用旧信息、结果忽好忽坏等情况时，问题通常不在“模型是否可用”，而在检索链路、索引状态、配置一致性、依赖服务状态，或上下文拼接过程。 +当知识库已经接入，系统也能正常回答，但结果仍然出现命中错误、引用旧内容、推理漂移、跨轮次失忆，或部署后表面可用但实际异常时，最常见的问题不是“模型不行”，而是**不同层的故障被混在一起处理**。 -本文提供一套面向实际使用场景的排查路径，帮助你在不大范围重配系统的前提下，先缩小问题范围，再做最小修复。 -如果你正在处理“知识库似乎已经接入，但回答效果不稳定”的问题，建议按本文顺序逐步检查。 +这份页面不重新发明一套新方法。 +它直接使用一份固定的 **16 问题清单** 作为排查主轴，让你先把问题标到正确的 **No.X**，再决定下一步查哪里、改哪里，而不是一次性乱改检索、模型、切块、会话和部署配置。 -> 建议先判断异常类型，再开始修改配置。 -> 同时调整多个变量，通常只会让问题更难定位。 +这份清单的核心目的只有一个： -快速定位： -[异常自检](#quick-check) | [五步诊断](#workflow) | [根因定位](#failure-types) | [平台检查点](#platform-checks) | [修复顺序](#fix-order) | [提交 Issue](#issue-report) +**先把问题放进正确的故障域，再做修复。** + +快速导航： +[这页怎么用](#how-to-use) | [标签说明](#legend) | [常见症状入口](#symptoms) | [16 问题清单](#map16) | [按层排查](#by-layer) | --- - + -## 一、快速判断：你属于哪一种异常 +## 一、这页怎么用 -如果你已经遇到以下情况，可以先快速对照，再进入后续排查步骤。 +这不是一篇“从头到尾照着做”的传统教程。 +它更像一张固定的 RAG 故障地图，作用是先帮助你**判断故障属于哪一种类型**。 -### 1. 明明接入了知识库，但回答像没有检索到任何内容 +建议按下面顺序使用： -常见表现： - -1. 回答只基于通用知识，缺少业务内容 -2. 回答内容空泛，与已上传文档无明显关联 -3. 同一问题无论是否启用知识库，结果差异很小 - -优先怀疑方向： - -1. 知识库未真正进入可检索状态 -2. 文档导入完成，但索引尚未可用 -3. 请求没有进入检索链路，而是直接进入普通对话链路 - -### 2. 能检索到内容，但最终回答仍然不准确 - -常见表现： - -1. 检索结果里已经有正确片段，但最终回答仍然偏题 -2. 回答混入无关信息 -3. 关键片段存在，但没有被正确使用 - -优先怀疑方向： - -1. 切块策略不合理，导致关键信息被切散 -2. 检索条数设置不合理，召回内容过少或过多 -3. 上下文拼接过程存在污染或顺序异常 - -### 3. 同一个问题有时正确，有时错误 - -常见表现： - -1. 重复提问结果不稳定 -2. 改动不大，但结果波动明显 -3. 某些时段效果正常，另一些时段明显变差 - -优先怀疑方向： - -1. 请求链路不一致 -2. 依赖服务状态不稳定 -3. 配置修改后存在参数漂移 -4. 缓存或旧配置偶发生效 - -### 4. 知识库更新后，回答仍然引用旧内容 - -常见表现： - -1. 文档已更新，但回答仍然引用旧版本内容 -2. 删除旧文档后，旧答案仍然可以命中 -3. 新旧内容混杂，回答前后矛盾 - -优先怀疑方向： - -1. 索引更新未完成 -2. 查询仍指向旧集合、旧配置或旧范围 -3. 缓存未刷新，或旧数据未被正确移除 - -### 5. 多模型、多服务或多平台接入后结果异常 - -常见表现： - -1. 切换模型后回答质量突然变化 -2. 相同知识库在不同入口下结果不一致 -3. 明明配置相似，但不同环境效果差异很大 - -优先怀疑方向： - -1. 请求被路由到非预期目标 -2. 不同环境使用了不同的检索配置 -3. 模型层与检索层的参数没有同步调整 - -[返回顶部](#top) | [下一节：五步诊断](#workflow) - ---- - - - -## 二、五步最小诊断流程 - -在开始修改配置之前，建议先按以下顺序排查。 -这套流程的目标不是“立刻修好所有问题”，而是先尽快判断问题落在哪一层。 - -### 第一步：先确认问题是否可以稳定复现 +### 1. 先看现象，不要先改配置 先回答两个问题： -1. 问题是每次都出现，还是偶发出现 -2. 问题是否只在特定模型、特定知识库、特定入口下出现 +1. 你看到的故障，最像哪一种症状 +2. 这个故障更像发生在输入检索层、推理层、状态层，还是部署层 -建议先固定以下条件，再做排查： +在还没判断层级之前，不要先一起改这些东西： -1. 固定一个问题输入 -2. 固定一个模型 -3. 固定一个知识库范围 -4. 固定一个调用入口 -5. 连续测试两到三次，观察现象是否一致 +- 检索条数 +- 切块大小 +- 会话配置 +- 模型参数 +- 部署顺序 +- 依赖服务 -如果问题本身不能稳定复现，优先记录触发条件，而不是立即修改多个配置。 +如果先全部一起动，问题通常只会更难定位。 -### 第二步：确认知识库数据是否真正可用 +### 2. 先给问题打上 No.X 标签 -不要只看“文档是否上传成功”，还要确认： +这份页面最重要的动作，不是“立刻修好”，而是先做一件小事： -1. 文档是否完成处理 -2. 是否完成切块 -3. 是否完成向量化 -4. 是否已写入目标存储 -5. 当前查询是否使用了正确的知识库范围 +**给当前问题贴上最接近的 No.X。** -很多看起来像“模型回答异常”的问题，本质上是知识库并未进入可检索状态。 +例如： -### 第三步：确认检索配置是否与数据形态匹配 +- 检索结果看起来相似，但其实答非所问，先看 `No.1` 或 `No.5` +- chunk 是对的，但结论还是错，先看 `No.2` +- 系统回答很自信，但没有根据，先看 `No.4` +- 刚部署完就炸，先看 `No.14` 到 `No.16` -重点检查以下项目： +### 3. 一次只排一个故障域 -1. 切块大小是否过大，导致一个片段信息过杂 -2. 切块大小是否过小，导致语义被切碎 -3. 是否设置了合理的重叠，避免关键上下文断裂 -4. 检索条数是否过少，导致漏掉关键片段 -5. 检索条数是否过多，导致无关内容进入上下文 -6. 配置变更后，是否与现有索引状态保持一致 +同一个表面现象，背后可能是不同层的问题。 +例如“答案不对”既可能是： -### 第四步：确认请求是否真的走了检索链路 +- `No.1` 检索漂移 +- `No.2` 理解塌陷 +- `No.4` 自信乱答 +- `No.8` 根本看不到错误路径 -有些问题看起来像“检索效果不好”，其实是“根本没有检索”。 +所以这张表的用法不是“多选全改”，而是： -建议确认： +**先挑最接近的一项，优先验证这一项是否成立。** -1. 当前入口是否启用了知识库检索 -2. 当前会话是否使用了正确的知识库范围 -3. 日志中是否能看到检索动作 -4. 日志中是否能看到召回结果 -5. 多服务接入时，请求是否命中了预期目标 - -如果请求未进入检索链路，再好的知识库配置也不会生效。 - -### 第五步：先归类，再做最小修复 - -不要在同一轮排查中同时修改模型、切块、检索条数、服务配置和依赖连接。 -建议先将问题归类到以下其中一种方向，再做单点修复： - -1. 数据未生效 -2. 检索不合理 -3. 链路未命中 -4. 部署状态异常 -5. 结果拼接异常 - -先缩小范围，再逐步修复，通常会比一次性重配更快得到有效结果。 - -[上一节：异常自检](#quick-check) | [返回顶部](#top) | [下一节：根因定位](#failure-types) +[返回顶部](#top) | [下一节：标签说明](#legend) --- - + -## 三、常见异常类型与根因定位 +## 二、标签说明 -当你无法通过单一现象直接判断问题时，可以按下面四大类进行归类。 -先判断“问题属于哪一类”，再决定下一步要查什么。 +这份 16 问题清单本身已经带有 layer / tag 结构。 +这些标签不是装饰，而是用来帮助你快速判断故障发生在哪一层。 -### A. 数据与索引类 +### 1. layer 标签 -这类问题的特点是：知识库看似存在，但检索基础并不稳定。 +- `[IN]`：Input & Retrieval + 输入、切块、召回、语义匹配、可见性问题 -#### 1. 文档已上传，但未进入可检索状态 +- `[RE]`：Reasoning & Planning + 理解、推理、归纳、逻辑链、抽象处理问题 -表现： +- `[ST]`：State & Context + 会话、记忆、上下文连续性、多代理状态问题 -1. 上传完成，但查询没有明显变化 -2. 不同文档都像没有被使用 -3. 结果与文档内容脱节 +- `[OP]`：Infra & Deployment + 启动顺序、依赖就绪、部署锁死、预部署状态问题 -排查重点： +### 2. `{OBS}` 标签 -1. 检查处理状态 -2. 检查索引是否完成 -3. 检查当前查询范围是否正确 +带 `{OBS}` 的项，通常都和“**你是否看得见问题是怎么坏掉的**”有关。 +它们往往不是单纯回答错误，而是： -#### 2. 切块策略不合理 +- 错误路径不可见 +- 漂移过程不可见 +- 状态熔化过程不可见 +- 多代理覆盖过程不可见 -表现： +所以一旦你发现“我知道结果错，但我根本看不到它是怎么错的”，通常就已经很接近 `{OBS}` 类问题了。 -1. 单个片段信息过多，主题混杂 -2. 关键句被拆散 -3. 召回片段读起来缺少上下文 +### 3. 为什么要保留这些标签 -排查重点： +因为同样叫“答错了”，实际含义完全不同。 -1. 检查切块大小 -2. 检查重叠策略 -3. 检查是否按文档类型区分切块方式 +例如： -#### 3. 向量化配置不一致 +- `[IN]` 的答错，常常是**拿错材料** +- `[RE]` 的答错，常常是**拿对材料但理解错** +- `[ST]` 的答错，常常是**前文断掉、状态漂移** +- `[OP]` 的答错，常常是**系统根本没在完整状态下运行** -表现： +如果不先分层，就会掉进典型的 RAG 地狱： +表面在改答案，实际上在盲修。 -1. 有召回，但命中质量明显异常 -2. 明明是相关问题，却命中很多弱相关内容 -3. 修改配置后效果突然恶化 - -排查重点： - -1. 检查配置是否前后一致 -2. 检查配置变更后是否需要重新处理 -3. 检查新旧配置是否混用 - -#### 4. 索引更新不完整 - -表现： - -1. 更新后仍命中旧内容 -2. 删除后仍可查到旧答案 -3. 新内容迟迟不生效 - -排查重点： - -1. 检查更新流程是否完整执行 -2. 检查旧数据是否仍被引用 -3. 检查是否存在缓存或旧范围残留 - -### B. 检索与链路类 - -这类问题的特点是：系统具有知识库能力，但请求没有正确使用它。 - -#### 5. 请求未进入知识库检索流程 - -表现： - -1. 回答更像普通对话 -2. 不同知识库下回答几乎相同 -3. 日志中看不到检索动作 - -排查重点： - -1. 检查是否启用知识库模式 -2. 检查当前入口配置 -3. 检查日志中是否有召回记录 - -#### 6. 检索范围配置错误 - -表现： - -1. 命中到了不相关的数据范围 -2. 应该命中的资料没有参与检索 -3. 不同业务资料互相干扰 - -排查重点： - -1. 检查当前会话绑定范围 -2. 检查查询目标是否正确 -3. 检查是否误用了旧范围或默认范围 - -#### 7. 请求被路由到错误目标 - -表现： - -1. 不同入口结果差异异常大 -2. 同样配置在不同环境行为不同 -3. 切换后端后结果明显漂移 - -排查重点： - -1. 检查请求实际命中的服务 -2. 检查多环境配置是否一致 -3. 检查链路中是否存在错误转发 - -#### 8. 检索条数或召回策略不合理 - -表现： - -1. 命中太少，遗漏关键内容 -2. 命中太多，带入大量噪声 -3. 回答被无关片段干扰 - -排查重点： - -1. 检查检索条数 -2. 检查召回策略 -3. 检查召回内容是否与问题真正相关 - -### C. 部署与运行类 - -这类问题的特点是：逻辑上配置正确，但系统运行状态不完整。 - -#### 9. 依赖服务未就绪 - -表现： - -1. 某些时候正常，某些时候失效 -2. 重启后暂时恢复 -3. 功能表面可用，但结果不稳定 - -排查重点： - -1. 检查依赖服务启动顺序 -2. 检查服务可达性 -3. 检查系统初始化是否完整 - -#### 10. 连接异常或服务不可达 - -表现： - -1. 某个环节偶发失败 -2. 某些请求直接退化为无检索结果 -3. 日志中出现连接异常、超时或空结果 - -排查重点： - -1. 检查依赖连接状态 -2. 检查网络与端口可达性 -3. 检查异常时段的日志 - -#### 11. 环境变量、密钥或配置缺失 - -表现： - -1. 部分功能可用，部分功能失效 -2. 同一套配置在新环境无法复现 -3. 迁移后问题突然出现 - -排查重点： - -1. 检查必要配置是否完整 -2. 检查配置是否被覆盖 -3. 检查环境切换后是否存在遗漏 - -#### 12. 首次部署后状态不完整 - -表现： - -1. 系统看起来已经启动，但部分能力未真正可用 -2. 首次导入数据后效果异常 -3. 重建后暂时恢复，过一段时间又出现问题 - -排查重点： - -1. 检查首次初始化流程 -2. 检查状态是否完整落地 -3. 检查是否有必须执行但被跳过的步骤 - -### D. 结果与观测类 - -这类问题的特点是：检索可能已有结果，但最终回答仍然不对。 - -#### 13. 检索命中存在，但上下文拼接不合理 - -表现： - -1. 正确片段存在，但没有被回答使用 -2. 回答只引用了部分片段 -3. 片段顺序混乱，影响理解 - -排查重点： - -1. 检查上下文拼接顺序 -2. 检查是否截断了关键片段 -3. 检查最终输入给模型的上下文内容 - -#### 14. 无关片段进入上下文，造成污染 - -表现： - -1. 回答中混入其他主题内容 -2. 本该准确回答，却出现明显跑题 -3. 一次问题引入了多个不相关片段 - -排查重点： - -1. 检查召回内容质量 -2. 检查检索条数是否过大 -3. 检查切块是否造成语义混杂 - -#### 15. 缺少关键日志，无法判断问题层级 - -表现： - -1. 知道“结果不对”，但不知道错在哪里 -2. 无法确认是否发生了检索 -3. 无法确认是哪一层先出问题 - -排查重点： - -1. 保留请求输入 -2. 保留召回结果 -3. 保留最终回答 -4. 保留关键流程日志 - -#### 16. 缺少最小复现，导致问题长期无法稳定定位 - -表现： - -1. 问题描述笼统，难以重复触发 -2. 每次排查都从头开始 -3. 多人协作时无法快速对齐 - -排查重点： - -1. 固定最小输入 -2. 固定测试条件 -3. 明确记录复现步骤 -4. 记录最近一次变更 - -如果你暂时无法确认根因，先不要全面重配。 -先判断属于哪一大类，再做单点调整，通常会更快接近有效修复。 - -[上一节：五步诊断](#workflow) | [返回顶部](#top) | [下一节：平台检查点](#platform-checks) +[返回顶部](#top) | [下一节：常见症状入口](#symptoms) --- - + -## 四、平台级检查点 +## 三、常见症状入口 -当你已经确认问题属于 RAG 异常，但还无法判断具体落点时，建议优先检查以下项目。 -这些检查点通常比“直接换模型”更有价值，也更能帮助你快速缩小范围。 +如果你现在还不知道该从哪一项开始，就先从症状入口反查。 -### 1. 知识库状态 +### 1. 检索返回了错误内容，或看起来相关但其实不回答问题 -请先确认： +这类问题最常见的是： +“有命中，但命中的不是该用的内容。” -1. 文档是否已完成导入 -2. 文档是否已完成处理 -3. 当前查询是否绑定了正确的知识库范围 -4. 同一问题在不同知识库范围下，结果是否符合预期 +优先看： -如果知识库状态本身不稳定，后续所有排查都可能失真。 +- [No.1](#no1) `hallucination & chunk drift` +- [No.5](#no5) `semantic ≠ embedding` +- [No.8](#no8) `debugging is a black box` -### 2. 切块与内容组织 +### 2. chunk 本身是对的，但最终答案还是错的 -请重点检查： +这类问题不是简单没检索到，而是后面那层坏了。 -1. 切块是否过大，导致主题混杂 -2. 切块是否过小，导致关键上下文断裂 -3. 是否设置了合理的重叠 -4. 文本结构是否适合当前切块方式 +优先看： -不合理的切块，通常会直接导致“命中了也答不好”。 +- [No.2](#no2) `interpretation collapse` +- [No.4](#no4) `bluffing / overconfidence` +- [No.6](#no6) `logic collapse & recovery` -### 3. 检索配置 +### 3. 多步任务一开始正常，后面越来越偏 -请重点检查： +这类问题通常不是单点错误，而是中途漂移或熔化。 -1. 检索条数是否合适 -2. 是否存在明显的弱相关召回 -3. 是否遗漏关键片段 -4. 修改配置后，结果是否按预期变化 +优先看： -如果你调整了检索配置，但结果完全没有变化，需要回头检查是否真的命中了当前配置。 +- [No.3](#no3) `long reasoning chains` +- [No.6](#no6) `logic collapse & recovery` +- [No.9](#no9) `entropy collapse` -### 4. 依赖连接与运行状态 +### 4. 多轮对话后开始失忆，跨轮次接不上 -请重点检查： +这类问题一般已经进入状态层。 -1. 依赖服务是否全部就绪 -2. 查询过程中是否存在连接异常 -3. 某些时段是否出现明显波动 -4. 重启后是否出现短暂恢复 +优先看： -偶发异常，通常和运行状态有关，不一定是逻辑错误。 +- [No.7](#no7) `memory breaks across sessions` +- [No.9](#no9) `entropy collapse` +- [No.13](#no13) `multi-agent chaos` -### 5. 最终生成环节 +### 5. 遇到抽象、逻辑、规则、符号关系就崩 -请重点检查： +这类问题通常不是检索空，而是推理结构扛不住。 -1. 召回结果是否被完整传入生成环节 -2. 最终回答是否明显脱离召回内容 -3. 是否存在无关片段进入最终上下文 -4. 是否能从日志中对照“输入、召回、回答”的完整路径 +优先看： -如果你只能看到最终答案，看不到召回内容，排查效率会显著下降。 +- [No.11](#no11) `symbolic collapse` +- [No.12](#no12) `philosophical recursion` -[上一节：根因定位](#failure-types) | [返回顶部](#top) | [下一节：修复顺序](#fix-order) +### 6. 你根本不知道错在哪一层，只知道结果不对 + +这类问题先不要乱调参数。 +先解决“不可见”的问题。 + +优先看： + +- [No.8](#no8) `debugging is a black box` + +### 7. 刚部署完最容易炸，首轮调用异常，重启后偶尔恢复 + +这类问题通常不在答案逻辑，而在部署状态。 + +优先看： + +- [No.14](#no14) `bootstrap ordering` +- [No.15](#no15) `deployment deadlock` +- [No.16](#no16) `pre-deploy collapse` + +[返回顶部](#top) | [下一节：16 问题清单](#map16) --- - + -## 五、优先修复顺序 +## 四、16 问题清单（固定主表） -当问题已经被初步定位后，建议按下面顺序处理，而不是一次性调整全部配置。 -按优先级逐步修复，可以更快判断哪一项改动真正有效。 +下面这 16 项按固定顺序使用。 +不要先重组，不要先混类，先判断最接近哪一个 **No.X**。 -### 优先级 1：先确认数据是否真的可检索 +| # | problem domain (with layer/tags) | what breaks | +|---|---|---| +| 1 | `[IN] hallucination & chunk drift {OBS}` | retrieval returns wrong/irrelevant content | +| 2 | `[RE] interpretation collapse` | chunk is right, logic is wrong | +| 3 | `[RE] long reasoning chains {OBS}` | drifts across multi-step tasks | +| 4 | `[RE] bluffing / overconfidence` | confident but unfounded answers | +| 5 | `[IN] semantic ≠ embedding {OBS}` | cosine match ≠ true meaning | +| 6 | `[RE] logic collapse & recovery {OBS}` | dead-ends, needs controlled reset | +| 7 | `[ST] memory breaks across sessions` | lost threads, no continuity | +| 8 | `[IN] debugging is a black box {OBS}` | no visibility into failure path | +| 9 | `[ST] entropy collapse` | attention melts, incoherent output | +| 10 | `[RE] creative freeze` | flat, literal outputs | +| 11 | `[RE] symbolic collapse` | abstract/logical prompts break | +| 12 | `[RE] philosophical recursion` | self-reference loops, paradox traps | +| 13 | `[ST] multi-agent chaos {OBS}` | agents overwrite or misalign logic | +| 14 | `[OP] bootstrap ordering` | services fire before deps ready | +| 15 | `[OP] deployment deadlock` | circular waits in infra | +| 16 | `[OP] pre-deploy collapse {OBS}` | version skew / missing secret on first call | -如果知识库尚未进入可检索状态，后续所有调参都没有意义。 -请先确认文档处理、索引状态、查询范围是否正确。 +这张表是主表。 +如果你时间很少，只做一件事也行： -### 优先级 2：再确认请求是否走了正确链路 +**先从这 16 项里选出最接近的一项。** -如果请求根本没有进入检索流程，或者命中了错误目标，那么问题不在“回答质量”，而在“链路路径”。 +[返回顶部](#top) | [下一节：按层排查](#by-layer) -### 优先级 3：再调整切块、检索条数与召回范围 +--- -这是最常见的效果问题来源，但应该建立在前两项确认完成的前提下。 -否则你可能会把“链路问题”误判成“参数问题”。 + -### 优先级 4：最后再处理结果生成层问题 +## 五、按层排查：不要改错层 -很多看起来像“模型回答不好”的问题，实际上仍然来自检索侧或上下文侧。 -因此模型层调优应放在最后，而不是一开始就扩大改动范围。 +这一节不重写 16 项，只是告诉你： +当你已经选到某个 No.X 时，第一眼应该优先查哪一层。 -### 修复时的建议做法 +### A. `[IN]` 层：先确认你拿到的是不是对的材料 -1. 每次只修改一个关键变量 -2. 修改前后使用相同问题进行对比 -3. 同时保留召回结果与最终回答 -4. 记录本轮修改内容，避免回头时无法对照 +对应编号： -只改一个变量，通常比一次性改五个参数更容易找到真正的原因。 +- [No.1](#no1) +- [No.5](#no5) +- [No.8](#no8) -[上一节：平台检查点](#platform-checks) | [返回顶部](#top) | [下一节：提交 Issue](#issue-report) +这层最常见的误判是： + +“我以为系统理解错了，其实它一开始就拿错了东西。” + +如果你命中了弱相关片段、表面相似文本、错误 chunk，后面推理再强也没用。 +所以 `[IN]` 层优先看的是： + +1. 原始召回内容到底是什么 +2. 命中的片段是否只是“相似”，而不是“正确” +3. 你是否能看到检索过程，还是整个过程像黑箱 + +这层如果没先排好，后面的推理诊断通常会失真。 + +### B. `[RE]` 层：材料可能是对的，但系统用错了 + +对应编号： + +- [No.2](#no2) +- [No.3](#no3) +- [No.4](#no4) +- [No.6](#no6) +- [No.10](#no10) +- [No.11](#no11) +- [No.12](#no12) + +这层最常见的误判是： + +“我以为是检索坏了，其实是后面理解、归纳、逻辑链坏了。” + +例如： + +- chunk 是对的，但结论错了 → 常见是 `No.2` +- 多步任务中途开始偏 → 常见是 `No.3` +- 回答很笃定，但完全站不住 → 常见是 `No.4` +- 遇到抽象规则就崩 → 常见是 `No.11` +- 陷入循环解释 → 常见是 `No.12` + +如果 `[IN]` 层已经基本没问题，答案还是不对，就应该优先回到 `[RE]` 层判断是哪一种塌陷。 + +### C. `[ST]` 层：单轮正常，不代表状态层正常 + +对应编号： + +- [No.7](#no7) +- [No.9](#no9) +- [No.13](#no13) + +这层最常见的误判是： + +“单轮看起来还行，所以我以为系统没问题。” + +其实很多 RAG 地狱不是单轮错误，而是： + +- 多轮之后前文断掉 +- 上下文越来越乱 +- 多角色、多代理之间互相覆盖 + +如果你发现： + +- 第一轮没事，后面越来越歪 +- 切换角色后前面的约束消失 +- 多个步骤之间状态彼此污染 + +那就不要再只盯着检索条数了，应该直接回到 `[ST]` 层看 `No.7 / No.9 / No.13`。 + +### D. `[OP]` 层：别把部署问题误诊成回答问题 + +对应编号： + +- [No.14](#no14) +- [No.15](#no15) +- [No.16](#no16) + +这层最常见的误判是： + +“答案不稳定，所以我先去调模型或检索。” + +但如果系统根本没有在完整状态下启动，所有上层表现都会像鬼打墙。 +尤其是这些情况： + +- 依赖还没就绪，服务先起了 → `No.14` +- 多个组件互相等待，长期半可用 → `No.15` +- 首次调用就因为版本、密钥、环境没对齐而塌陷 → `No.16` + +只要你看到“刚部署最容易出事”“首轮异常最严重”“重启后暂时恢复”，就要优先怀疑 `[OP]` 层，而不是先改 prompt 或参数。 + +[返回顶部](#top) | --- -## 六、仍无法定位时，如何提交有效 Issue -如果你已经完成基础排查，但问题仍然无法确认位置，建议在提交 Issue 前先整理以下信息。 -高质量的问题描述，通常比大量截图更能帮助快速定位。 +## 六、快速返回 -### 最少应提供的信息 +[返回顶部](#top) | [这页怎么用](#how-to-use) | [标签说明](#legend) | [常见症状入口](#symptoms) | [16 问题清单](#map16) | [按层排查](#by-layer) -1. 问题现象的简要描述 -2. 最小可复现步骤 -3. 当前使用的模型 -4. 当前是否启用了知识库检索 -5. 当前知识库范围或相关配置 -6. 检索结果与最终回答的差异 -7. 关键日志、报错或异常现象 -8. 最近一次配置变更内容 - -### 推荐的描述方式 - -1. 先说明现象，不要只写“结果不对” -2. 再说明如何复现，让他人可以重复触发 -3. 再说明你已经检查过哪些项目 -4. 如果问题是偶发的，请说明出现频率和触发条件 - -### 推荐的最小问题模板 - -```text -问题现象： -回答出现偏题 / 未命中知识库 / 引用旧内容 / 结果不稳定（选择其一或补充说明） - -复现步骤： -1. -2. -3. - -当前配置： -1. 使用模型： -2. 是否启用知识库： -3. 知识库范围： -4. 最近是否修改过配置： - -实际结果： -（描述当前返回结果） - -预期结果： -（描述你期望得到的结果） - -已检查项目： -1. -2. -3. - -补充日志或报错： -（如有可补充） -```` - -提供清晰、可复现的信息，通常比直接贴出大量无上下文截图更有助于定位问题，也能显著提高排查效率。 - -[上一节：修复顺序](#fix-order) | [返回顶部](#top) - ---- - -## 七、快速返回 - -[返回顶部](#top) | [异常自检](#quick-check) | [五步诊断](#workflow) | [根因定位](#failure-types) | [平台检查点](#platform-checks) | [修复顺序](#fix-order) | [提交 Issue](#issue-report)