前言：

做项目二的过程中，踩了不少坑。

一开始以为是检索问题，后来发现是解析问题；
修完解析，又发现是 scope 规则问题；
修完 scope，又暴露 gate 边界问题。

反复之后，把整个 RAG 系统拆成六层调试模型。

思路更加清晰。

为什么需要分层调试？

很多时候调 RAG 的方式是：

• 改 prompt

• 调 top_k

• 换 embedding

但是：

你不知道问题在哪一层。

如果解析层就错了，你调 embedding 没意义。

所以须先分层。

RAG 六层调试模型

1、解析层（PDF → Text）

问题类型：

• 文本未被正确抽取

• 连字符丢失

• 字符被合并

• 特殊符号变形

典型现象：

• debug 显示 token 命中 0

• 明明 PDF 里有内容

调试方法：

• 在 build_chunks 后打印关键 token 命中统计

• 先验证“内容是否进入系统”

结论：

解析层错，后面全是假象。

2、chunk 层（文本切分）

问题类型：

• 关键句被拆开

• 句子被切断

• 上下文断裂

现象：

• 命中 chunk 但答案语义不完整

调试方法：

• 打印 chunk 内容

• 调整 chunk_size / overlap

• 检查 token 是否被切碎

3、检索层（Retrieval）

问题类型：

• 泛词误命中

• 版本混杂

• top1 不稳定

典型现象：

• 命中内容相关但不精准

• 不同运行结果排序不同

调试方法：

• 输出 top_k + score

• 对比命中顺序

• 分析关键词权重

原则：

检索负责“找候选”，不负责控制边界。

4、Scope 层（文档边界控制）

问题类型：

• 跨文档污染

• 指定文档却答错版本

典型现象：

• chunk_id 混合 A 和 B

• Scope leak 统计 > 0

解决方式：

• dominant_doc 过滤

• forced_doc 规则（显式约束优先）

• scope 回归断言

这是多文档 RAG 的核心层。

---

5、Gate 层（问题类型控制）

问题类型：

• 方法型问题无证据却回答

• 对比类问题强行回答

• 推荐类主观判断

解决方式：

• is_howto_question + has_howto_evidence

• compare gate

• 推荐类拒答

原则：

边界必须明确，拒答比误答安全。

---

6、生成层（模型表达）

问题类型：

• 组织表达不清

• 引用不完整

• 模型补充了未提供内容

控制方式：

• 明确 system prompt 约束

• 限定引用来源

• 禁止模型自由扩展

生成层是最后一层，不是第一层。

六层关系

解析
  ↓
chunk
  ↓
检索
  ↓
scope
  ↓
gate
  ↓
生成

问题须从上往下排查。

不要跳层。

为什么这个模型重要？

因为它带来三个改变：

1. 调试有顺序

2. 每层可观测

3. 问题可归因

这比“调 prompt”重要得多。

项目现阶段状态

v0.5：

• 解析层稳定（测试 PDF）

• 多文档 scope 稳定

• Gate 边界清晰

• 回归 100%

• Scope 污染 0

下一阶段将进入：

检索层升级（embedding / 向量化）