External Cannbot Model Model Infer Precision Debug

推理精度问题诊断技能

当前主要覆盖 KVCache / FA 相关精度问题，其他推理精度问题后续补充。 不覆盖运行时错误（crash、hang、OOM、算子约束违反等见 model-infer-runtime-debug）。

按"症状分类 → 快速验证 → 分模块定位 → 逐层对比 → 陷阱修复"的分层策略排查精度问题。完整校验工具见 references/fa_debug_utils.md。

重要原则

• 对比驱动：所有精度判定必须基于与基线（eager 模式 / 优化前）的数值对比，不可凭直觉
• 逐步缩小范围：先定位阶段（Prefill/Decode）→ 再定位模块（KVCache 写入/FA 计算/后处理）→ 最后定位参数
• 最小改动验证：每次只修改一个变量，验证后再进入下一个
• 保留现场：调试过程中的中间 tensor 和日志必须保留，用于后续分析
• 实际执行测试：所有调试步骤由 Agent 实际执行，不将测试工作委托给用户

排查工作流

接到精度调试任务后，按以下步骤执行：

第一步：收集信息 — 获取精度症状、优化阶段、执行/量化模式、基线输出

第二步：快速诊断 — 根据症状分类表判断方向 → 执行快速验证清单（含 FA 入参检查）→ 发现问题直接修复

第三步：分模块定位 — 二分法确定 Prefill/Decode → 针对性插桩验证 → PA 场景执行专项排查

第四步：精细定位（按需） — 使用逐层对比框架，dump 基线 → compare 优化后 → 定位首次偏差层

第五步：修复与验证 — 参照常见陷阱表修复 → 重新运行完整精度验证

第六步：输出调试报告 — 问题概要、根因分析、修复措施、修复验证、遗留风险

第二步：快速诊断

2.1 症状分类

2.2 快速验证清单

• 1. dtype 一致性：KVCache tensor 与模型计算 dtype 一致（BF16 / FP16）
• 2. device 一致性：所有 tensor 均在 NPU 上，无意外的 CPU tensor
• 3. block_table dtype：必须为 torch.int32
• 4. sparse_mode 正确：Prefill=3（因果），Decode=0（dense）；sparse_mode=2 不推荐
• 5. Prefill 和 Decode 的 FA 调用参数需分别配置（sparse_mode、atten_mask、actual_seq_lengths 等）
• 6. scale 参数：1.0 / sqrt(head_dim)，确认 head_dim 值正确
• 7. num_heads / num_kv_heads：与模型配置一致，多卡时已按 rank 切分
• 8. kv_len 初始值：Prefill 后 kv_len 等于输入序列长度，非 0
• 9. input_layout 与 tensor shape 匹配
• 10. actual_seq_lengths 构造方式与 layout 匹配（TND 用 cumsum，BSH 用原值）
• 11. atten_mask 与 sparse_mode 匹配（详见附录 F.1）；Decode 单 token 查询通常不需要 mask
• 12. FA v1 vs v2 参数名：未混用（详见附录 F.2）
• 13. Decode 阶段未使用 sparse_mode=3
• 14. PA 场景下 mask 最后一维 >= block_table 第二维 × block_size
• 15. MLA rope 参数：query_rope/key_rope 同时传或同时不传；rope D=64，query D 仅支持 512/128
• 16. inner_precise 行无效：Prefill + 自定义 mask 有全遮蔽行时需设为 2/3
• 17. kv_len 层内只读：kv_len 在 attention/cache 内部未被修改（禁止层内递增，否则各层写入位置错位导致精度彻底损坏）

第三步：分模块定位

3.1 排查策略：二分法定位

模型输出与基线不一致
    │
    ├─ 1. 仅运行 Prefill，对比输出
    │   ├─ Prefill 输出一致 → 问题在 Decode 阶段（跳到 3.3）
    │   └─ Prefill 输出不一致 → 问题在 Prefill 阶段（跳到 3.2）
    │
    ├─ 2. Decode 第 1 步 vs 第 N 步
    │   ├─ 第 1 步就不一致 → FA 入参或 KVCache 初始状态问题
    │   └─ 第 N 步开始不一致 → kv_len 累计更新或缓存溢出问题
    │
    └─ 3. 逐层对比（跳到第四步）

3.2 Prefill 阶段精度排查

KVCache 写入验证：在 scatter_update_ 调用前后插桩，检查：

1. 写入前缓存是否为零（首次 Prefill）
2. 写入后缓存内容与 key_states 是否一致（阈值 1e-6）
3. scatter_update_ 的 axis 参数与 layout 是否匹配（BSH → axis=1, TND → axis=0）

FA 入参验证：打印并校验 Q/K/V shape、actual_seq_qlen/kvlen、sparse_mode、是否含 NaN/Inf

3.3 Decode 阶段精度排查

KVCache 写入验证：

1. 验证 slot_mapping 计算（连续缓存：expected_slot = kv_len.view(-1,1) + kv_len_offset；PA：通过 block_table 索引）
2. 验证写入位置未越界
3. 验证 kv_len 逐步递增正确

FA 入参验证：

1. sparse_mode 应为 0，actual_seq_qlen 每个值应为 1（MTP 除外）
2. block_table dtype 必须为 int32
3. KV cache 已写入区域无 NaN/Inf

3.4 分页注意力（PA）专项排查

1. block_table 静态校验：numel == batch_size × (max_seq_len // block_size)
2. block_table 值域校验：应为 [0, total_blocks) 的排列，无重复
3. slot_mapping 与 block_table 交叉验证

第四步：逐层精细对比

4.1 逐层对比框架

在 Transformer Block 的 8 个关键位置插入 checkpoint，与基线对比：

对比指标（均转为 float32 计算）：max_abs_diff / max_rel_diff / cosine_similarity

判定阈值：BF16 模式 max_rel < 1e-3，量化模式 max_rel < 1e-2

使用流程：dump 基线 → compare 优化后 → 定位首次出现偏差的层和位置

第五步：常见精度陷阱与修复

5.1 KVCache 写入相关

5.2 FA 算子相关

5.3 量化相关

5.4 Prefill/Decode 一致性

附录 F：FA 入参配置参考

表格供快速验证清单引用，完整校验代码见 references/fa_debug_utils.md，可在 FA 调用前插入 debug_fa_all_params() 一键检查。

F.1 atten_mask 与 sparse_mode 联合校验

F.2 FA v1 vs v2 关键参数名映射

F.3 input_layout 与 tensor shape 匹配

PA 模式下 KV 按 block_table 索引，shape 与非 PA 不同。

F.4 actual_seq_lengths 构造

Decode 时 actual_seq_qlen 每个值通常为 1（MTP 场景除外）。

F.5 inner_precise 行无效

F.6 MLA rope 约束

• query_rope 和 key_rope 必须同时传或同时不传
• rope D 必须为 64，query D 仅支持 512 或 128
• D=512 时仅支持 sparse_mode 为 0、3、4

精度调试报告模板

## 精度调试报告

### 问题概要
- 症状：{描述}
- 定位阶段：{Prefill / Decode / 两者}
- 定位模块：{KVCache 写入 / FA 计算 / 量化参数 / ...}

### 根因分析
- 原因：{具体原因}
- 影响范围：{受影响的层/模块}

### 修复措施
| 修改文件 | 修改内容 | 修改原因 |
|---------|---------|---------|
| {file} | {change} | {reason} |

### 修复验证
- 精度对比：{通过/未通过，max_rel_diff, cosine_similarity}
- 输出一致性：{token 序列对比结果}

### 遗留风险
- {如有，列出可能的后续风险}

其他已知精度问题

以下问题来自本仓已适配模型的调试经验，不属于 KVCache/FA 范畴但会导致精度异常。