From 523628ade6cdf13c44315ed574ec1d2ce614b7ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?PSBigBig=20=C3=97=20MiniPS?= Date: Mon, 2 Mar 2026 19:01:59 +0800 Subject: [PATCH] docs: add structured RAG 16-problem troubleshooting guide and README entry --- docs/troubleshooting/rag-failures.md | 93 ++++++++++++++-------------- 1 file changed, 46 insertions(+), 47 deletions(-) diff --git a/docs/troubleshooting/rag-failures.md b/docs/troubleshooting/rag-failures.md index ca0f1626..fdcadefe 100644 --- a/docs/troubleshooting/rag-failures.md +++ b/docs/troubleshooting/rag-failures.md @@ -52,7 +52,7 @@ 例如： - 检索结果看起来相似，但其实答非所问，先看 `No.1` 或 `No.5` -- chunk 是对的，但结论还是错，先看 `No.2` +- 切块是对的，但结论还是错，先看 `No.2` - 系统回答很自信，但没有根据，先看 `No.4` - 刚部署完就炸，先看 `No.14` 到 `No.16` @@ -78,21 +78,21 @@ ## 二、标签说明 -这份 16 问题清单本身已经带有 layer / tag 结构。 +这份 16 问题清单本身已经带有层级 / 标签结构。 这些标签不是装饰，而是用来帮助你快速判断故障发生在哪一层。 -### 1. layer 标签 +### 1. 层级标签 -- `[IN]`：Input & Retrieval +- `[IN]`：输入与检索 输入、切块、召回、语义匹配、可见性问题 -- `[RE]`：Reasoning & Planning +- `[RE]`：推理与规划 理解、推理、归纳、逻辑链、抽象处理问题 -- `[ST]`：State & Context +- `[ST]`：状态与上下文 会话、记忆、上下文连续性、多代理状态问题 -- `[OP]`：Infra & Deployment +- `[OP]`：基础设施与部署 启动顺序、依赖就绪、部署锁死、预部署状态问题 ### 2. `{OBS}` 标签 @@ -138,19 +138,19 @@ 优先看： -- [No.1](#no1) `hallucination & chunk drift` -- [No.5](#no5) `semantic ≠ embedding` -- [No.8](#no8) `debugging is a black box` +- [No.1](#no1) `幻觉与切块漂移` +- [No.5](#no5) `语义 ≠ 向量嵌入` +- [No.8](#no8) `调试是一个黑箱` -### 2. chunk 本身是对的，但最终答案还是错的 +### 2. 切块本身是对的，但最终答案还是错的 这类问题不是简单没检索到，而是后面那层坏了。 优先看： -- [No.2](#no2) `interpretation collapse` -- [No.4](#no4) `bluffing / overconfidence` -- [No.6](#no6) `logic collapse & recovery` +- [No.2](#no2) `解释塌陷` +- [No.4](#no4) `虚张声势 / 过度自信` +- [No.6](#no6) `逻辑塌陷与恢复` ### 3. 多步任务一开始正常，后面越来越偏 @@ -158,9 +158,9 @@ 优先看： -- [No.3](#no3) `long reasoning chains` -- [No.6](#no6) `logic collapse & recovery` -- [No.9](#no9) `entropy collapse` +- [No.3](#no3) `长推理链` +- [No.6](#no6) `逻辑塌陷与恢复` +- [No.9](#no9) `熵塌陷` ### 4. 多轮对话后开始失忆，跨轮次接不上 @@ -168,9 +168,9 @@ 优先看： -- [No.7](#no7) `memory breaks across sessions` -- [No.9](#no9) `entropy collapse` -- [No.13](#no13) `multi-agent chaos` +- [No.7](#no7) `跨会话记忆断裂` +- [No.9](#no9) `熵塌陷` +- [No.13](#no13) `多代理混乱` ### 5. 遇到抽象、逻辑、规则、符号关系就崩 @@ -178,8 +178,8 @@ 优先看： -- [No.11](#no11) `symbolic collapse` -- [No.12](#no12) `philosophical recursion` +- [No.11](#no11) `符号塌陷` +- [No.12](#no12) `哲学递归` ### 6. 你根本不知道错在哪一层，只知道结果不对 @@ -188,7 +188,7 @@ 优先看： -- [No.8](#no8) `debugging is a black box` +- [No.8](#no8) `调试是一个黑箱` ### 7. 刚部署完最容易炸，首轮调用异常，重启后偶尔恢复 @@ -196,9 +196,9 @@ 优先看： -- [No.14](#no14) `bootstrap ordering` -- [No.15](#no15) `deployment deadlock` -- [No.16](#no16) `pre-deploy collapse` +- [No.14](#no14) `引导启动顺序` +- [No.15](#no15) `部署死锁` +- [No.16](#no16) `预部署塌陷` [返回顶部](#top) | [下一节：16 问题清单](#map16) @@ -211,24 +211,24 @@ 下面这 16 项按固定顺序使用。 不要先重组，不要先混类，先判断最接近哪一个 **No.X**。 -| # | 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 | +| 1 | `[IN] 幻觉与切块漂移 {OBS}` | 检索返回错误/无关内容 | +| 2 | `[RE] 解释塌陷` | 切块是对的，逻辑是错的 | +| 3 | `[RE] 长推理链 {OBS}` | 在多步任务中逐步漂移 | +| 4 | `[RE] 虚张声势 / 过度自信` | 自信但没有根据的回答 | +| 5 | `[IN] 语义 ≠ 向量嵌入 {OBS}` | 余弦匹配 ≠ 真实语义 | +| 6 | `[RE] 逻辑塌陷与恢复 {OBS}` | 走入死胡同，需要受控重置 | +| 7 | `[ST] 跨会话记忆断裂` | 线索丢失，没有连续性 | +| 8 | `[IN] 调试是一个黑箱 {OBS}` | 看不到故障路径 | +| 9 | `[ST] 熵塌陷` | 注意力熔化，输出失去连贯性 | +| 10 | `[RE] 创造力冻结` | 平直、字面化输出 | +| 11 | `[RE] 符号塌陷` | 抽象/逻辑性提示词失效 | +| 12 | `[RE] 哲学递归` | 自我引用循环、悖论陷阱 | +| 13 | `[ST] 多代理混乱 {OBS}` | 代理互相覆盖或使逻辑错位 | +| 14 | `[OP] 引导启动顺序` | 依赖未就绪时服务先启动 | +| 15 | `[OP] 部署死锁` | 基础设施中的循环等待 | +| 16 | `[OP] 预部署塌陷 {OBS}` | 首次调用时版本错配 / 缺少密钥 | 这张表是主表。 如果你时间很少，只做一件事也行： @@ -258,7 +258,7 @@ “我以为系统理解错了，其实它一开始就拿错了东西。” -如果你命中了弱相关片段、表面相似文本、错误 chunk，后面推理再强也没用。 +如果你命中了弱相关片段、表面相似文本、错误切块，后面推理再强也没用。 所以 `[IN]` 层优先看的是： 1. 原始召回内容到底是什么 @@ -285,7 +285,7 @@ 例如： -- chunk 是对的，但结论错了 → 常见是 `No.2` +- 切块是对的，但结论错了 → 常见是 `No.2` - 多步任务中途开始偏 → 常见是 `No.3` - 回答很笃定，但完全站不住 → 常见是 `No.4` - 遇到抽象规则就崩 → 常见是 `No.11` @@ -338,7 +338,7 @@ - 多个组件互相等待，长期半可用 → `No.15` - 首次调用就因为版本、密钥、环境没对齐而塌陷 → `No.16` -只要你看到“刚部署最容易出事”“首轮异常最严重”“重启后暂时恢复”，就要优先怀疑 `[OP]` 层，而不是先改 prompt 或参数。 +只要你看到“刚部署最容易出事”“首轮异常最严重”“重启后暂时恢复”，就要优先怀疑 `[OP]` 层，而不是先改提示词或参数。 [返回顶部](#top) | @@ -350,4 +350,3 @@ ## 六、快速返回 [返回顶部](#top) | [这页怎么用](#how-to-use) | [标签说明](#legend) | [常见症状入口](#symptoms) | [16 问题清单](#map16) | [按层排查](#by-layer) -