30 秒拿走一份判断清单，下面是完整论证版。

它是什么，治什么病

一句话：索引小块管查得准，返回父文档管上下文全。

检索命中一个小 chunk 后，不直接把它喂给模型，而是顺着元数据找回它所属的大单元（父段落/整页/整文档），用大单元做生成上下文。

它治的病只有一个：分块把意义切断了——结论依赖前文铺垫，小块单独拿出来语义不成立。

副作用同样明确：prompt 塞进大量无关内容、模型注意力被稀释（回答变吵）、token 成本变高、时延变长。

它是治「切断意义」的药，不是补脑药。 没这个病就别吃。

3 种场景不值得做

1. 段落自包含：问答对、条款、产品参数这类文体，按分隔符切开后每块意义完整。小块已经够用，展开父页只是往 prompt 里灌水。
2. 语料不大且检索稳：混合检索+重排做完，top3/top5 一直命中得很稳，根本不需要回父页凑上下文——你的问题在「查得准」，不在「上下文全」。
3. 抽取型答案：只要从文档里抽一个字段/一条规定。返回整页反而给模型发挥空间，它开始在你不该有自由度的地方自行总结。

2 种场景值得做

1. 长文档、结论依赖上下文才成立：法律意见书、实验报告，「综上所述」的「上述」就是病。
2. 怎么切都装不下一个答案：切小块检索不准、切大块上下文还是不够——说明你缺的不是查得准，是上下文完整。这时父页面召回才是正解。

我的数据形状：为什么落在「不做」区

语料是部门制度类文档，txt/word/pdf/xlsx 上传解析成纯文本后走我的递归切分器（chunker.ts）：

export const DEFAULT_TARGET_CHARS = 800   // 目标字符数 ≈ 上限值
// 短文档：直接一片（核心保护，避免过切）
if (cleaned.length <= targetChars) {
  return [{ content: cleaned, chunk_order: 1, page_no: pageNo }]
}
// 超长才逐层下降粒度：标题 → 空行段落 → 句号断句 → 固定兜底

制度文档的特点：条款天然自包含，一条「婚假申请流程」就是一个完整语义单元，800 字符目标 + 贪心合并（每片尽量落在 [400, 800] 区间）切出来的就是本来就自包含的小块。全库 172 个 chunk，混合检索（BM25+向量 RRF 融合）+ 精排取前 5 之后，命中一直挺稳——正好命中上面「不值得做」的前两种。

还有一个隐性成本：父页面召回需要 chunk→parent 的元数据链路（parent_id/页文档正文回查）。我的 chunk 有 page_no 和全文档连续 chunk_order，页级回查技术上做得动，但文档级展开等于把「检索」降级成「整本塞」——为我这 172 个块的语料引入这层结构和运行期回查，收益负期望。

所以父页面召回对我是锦上添花，不是药。功能不是看别人做了就抄，是看自己的数据形状。

3 秒自查法（建议抄走）

随机抽库里 5 个段落，只问一句：

「只留这一段，答案还成立吗？」

• 多数成立 → 不用做父页面，钱花在检索精排上更值
• 多数不成立 → 再动手，而且先试便宜的「取相邻片段」（命中 chunk 前后各带 1 条），还解决不了才上父文档级展开

速查表

我的清单里后续真要排的是 eval 验证集和生成侧引用校验——先有尺子再谈优化，这是下一个话题。

本篇最早于 2026 年 10 月 20 日发布于小红书，此为博客完整版。

为什么先分类再改写

病症不同，药不同。不分类一刀切地「请改写用户问题」，模型容易改错方向：把该放行的独立问题改花，把对比句「归纳」掉一个实体。我的做法是把六规则和六类型全部写进 system prompt，模型每步输出 JSON {type, rewritten}——先判型，再按规则改。

真实 prompt 关键段（query-rewrite.service.ts，节选）：

先判断 query 类型（从以下选一个）：
- context_dependent: 上下文依赖型（需看历史才能理解指代）
- comparative:       对比型（A 和 B 哪个好）
- vague_reference:   模糊指代型（那个东西怎么用）
- multi_intent:      多意图型（同时问多个事）
- rhetorical:        反问型（难道不是...吗）
- standalone:        独立型（不依赖历史，表达清晰）

只输出 JSON，不要解释，不要 markdown：
{"type": "类型", "rewritten": "改写后的完整query"}

模型 deepseek-chat，temperature: 0.1（改写要确定性），response_format: json_object。

六组配对：症状 → 药

婚假实测（同一组数据贯穿两篇）：

输入：「申请要怎么做?有没有步骤」+ 2 条婚假相关历史
输出：{"type": "context_dependent",
       "rewritten": "婚假申请的具体步骤和流程是什么"}
耗时 709ms / 565 token
BM25 命中：0 条 → 11 条（索引 docs=38, vocab=1936）

一条横六型的护栏：不编造实体

prompt 第 6 条规则单独拎出来说，因为它是事故源头：

6. 不要添加历史中不存在的信息，不要编造实体

rewritten 里只能出现 history 和原问里出现过的实体——用户没提婚假，就不能「猜」他要问婚假。编造实体 = 检索奔向错误文档，比不改更糟。

对比型还有一个专门的坑：模型爱把「A 和 B 的区别」「归纳」成只讲 A。所以规则里写死双实体必须保留，这条救过一次召回。

宁可保守：失败全回 null

改写失败、超时、JSON 不合法、改写结果和原话一样——一律 return null，上层降级用原 query，链路永不因改写挂掉。判型成 standalone 或直接跳过（无历史 / 启发式不含指代信号）都走同一个出口。

保守方向的选择题：改坏了捞错文档 vs 不改多捞几条垃圾——后者至少模型还能自己消化，前者直接把错误资料塞进上下文。所以宁可少改。

速查表（贴墙版）

上下文依赖 → 指代消解 + 省略补全
对比       → 具体化 + 保留双实体
模糊       → 模糊词具体化
多意图     → 拆分逐条检
反问       → 转陈述再查
独立       → 放行不改
公共护栏：不编造实体 + 异常回原话

改改写本质是「先承认用户的问法会带来什么麻烦，再决定怎么改」。无差别套一句「请优化这个问题」的 prompt，最容易跑偏。

本篇最早于 2026 年 10 月 15 日发布于小红书，此为含完整代码与数据的博客版。

我把自己 Nuxt3 知识库（my-nuxt-app）的调试工具链整个做成了一套排查方法，这篇按层过一遍。

总原则：控制变量 + 只看检索不生成

两条铁律贯穿所有排查：

1. 召回策略是唯一变量。我把检索做成 hybrid / bm25 / vector 三档模式开关，同一问题各跑一遍，后面的精排、生成完全一致——谁拖后腿一眼看见。
2. 检索和生成分开验。有 retrieveOnly 开关：只看召回了哪些片段、名次如何，不跑生成。答案不对，先确认是「没捞到」还是「捞到了模型没用好」，这两件事的修法完全不同。

分层排查

层 1：入库（文档→分块→向量）

七步建库链路：知识整理 → 清理格式化 → 内容切分 → 向量化 → 挂元数据 → 载入向量库 → 集成。效果差的病根很多在这：切太碎丢上下文，切太粗检索不准。

我项目的真实分块参数：递归切分器 chunker.ts，目标 800 字符（标题→空行段落→句号→硬切四层降级，短文档直接一片不硬切）；BM25 侧启动全量预热——最新实测：172 个 chunk / 3015 个词项，建索引 2688ms（TiDB 拉取+分词+倒排全算上）。

排查动作：随机抽几个 chunk 看语义是否自包含；问一个已知有答案的问题，确认目标 chunk 的文本入库时没被解析器吃掉（表格/PDF 是重灾区）。

层 2：检索（两路单测）

关键词路和向量路各留了单路调试接口：/api/rag/keyword-search、/api/rag/vector-search——单路粗召、不精排，专治「不知道哪路烂」。

典型病症对照：

• 专有名词/条款号/型号搜不到 → 关键词路问题：查分词（我的 BM25 用中文分词器切 query 和文档，分词烂则倒排全烂）、查索引预热是否成功（控制台看 docs/vocab 数）
• 换个说法就搜不到 → 只有 BM25 在干活，向量路没接上或阈值过严
• 召回一堆语义相近但没用的 → 向量路正常但缺精排，去层 4

层 3：融合（RRF 名次日志）

两路各召 top20，RRF 融合（score=Σ1/(60+rank)）。FusedResult 里我专门存了每个 id 的 ranks: [向量路名次, BM25路名次]（未命中记 null），服务端控制台按模式打印——融合后排名怪，直接看是「一路强推」还是「两路共认」。

坑：别把余弦分和 BM25 分直接加权，量纲不同（0~1 vs 无上限），必须转名次。

层 4：精排

粗召本质是盲选——入库时分块单独算的向量，从没和你的问题同框比过。精排用 cross-encoder（bge-reranker-v2-m3）把「问题+候选」成对打分，融合 top20 → 精排 top5。

排查信号：召回明明有正确答案却排在 15 名开外进不了上下文 → 看 rerank 分数；rerank 服务挂了会自动降级按 RRF 分排，日志里有标记，别把降级的锅算到检索头上。

层 5：生成

检索没问题、答案还是烂，才轮到生成层：prompt 里资料怎么拼、有没有约束「只用资料作答、引用标来源页码」、模型是不是被无关片段带偏（top5 塞太多噪声也是病，回头减 FINAL_TOP_K）。

常见三病因（课件口径 + 我的实战对应）

1. 文档处理和切割颗粒度问题 → 层 1
2. 召回不准，想命中的片段排序太靠后 → 层 2/3/4
3. 检索到了但整合生成没用对 → 层 5

对应五个提准手段（我项目落了的标 ✓）：切分技巧 ✓（递归四层+短文档保护）、取相邻片段（父页面类方案，评估后我没做）、多召回+rerank ✓（20→5）、混合检索 ✓（BM25+向量）、Query 重写 ✓（改写只进检索）。

面试话术一句话

「我调试 RAG 的路径是分层二分：先用 retrieveOnly 把检索和生成切开，再用三模式开关把两路召回切开，每层都有接口和名次日志。定位到层之后，改参数—回归—再定位，不靠玄学。」

这就是面试官要听的：不是你知道多少技巧，而是你有能把问题范围每次减半的方法。

本篇最早于 2026 年 10 月 10 日发布于小红书，此为博客完整版。