mcgatom/codex-cannbot/model-infer-precision-debug

推理精度问题诊断技能

当前主要覆盖 KVCache / FA 相关精度问题，其他推理精度问题后续补充。

不覆盖运行时错误（crash、hang、OOM、算子约束违反等见 model-infer-runtime-debug）。

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

部署模式适配：诊断流程对框架部署 / 独立部署两模式均适用，差异仅在参数获取路径——框架部署从 forward_metadata.{block_table, slot_mapping, actual_seq_lengths_*, is_prefill} 取，独立部署从 Runner 自管的 ParallelContext / forward_metadata 实例取。block_table / slot_mapping 在框架部署下是 Dict[attn_type → Tensor]，attention 内按 self.attn_type 取出对应 tensor；独立部署 Runner 自管的形态是单 Tensor。

packed sequence 协议（框架部署 modeling 强制要求）：input_ids / position_ids 是 [TotalTokens] 一维；hidden_states 全程保持 [TotalTokens, hidden_size] 二维（不要 reshape 成 [B, S, H]）；阶段分支统一用 forward_metadata.is_prefill。详见 model-infer-kvcache skill §3.1。

sparse_mode 写法（按路径分类）：标准 LLM TND PA 路径 Prefill + Decode 统一 sparse_mode=3 + causal mask；滑窗层 Prefill + Decode 统一 sparse_mode=4 + band mask；MLA absorb 路径 Prefill sparse_mode=3 / Decode sparse_mode=0+mask=None。详见 model-infer-kvcache skill §2.7。

重要原则

• 对比驱动：所有精度判定必须基于与基线（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 按路径正确：标准 LLM TND PA Prefill+Decode 统一 3；滑窗层统一 4；MLA absorb Prefill 3 / Decode 0（详见 model-infer-kvcache §2.7）
• [ ] 5. Prefill 和 Decode 的 FA 调用参数按路径配置（atten_mask、actual_seq_lengths 等；阶段分支取自 forward_metadata.is_prefill）
• [ ] 6. scale 参数：1.0 / sqrt(head_dim)，确认 head_dim 值正确
• [ ] 7. num_heads / num_kv_heads：与模型配置一致，多卡时已按 rank 切分（num_kv_heads_per_rank = max(num_kv_heads // attn_tp_size, 1)）
• [ ] 8. kv_len 初始值：Prefill 后 kv_len 等于输入序列长度，非 0
• [ ] 9. input_layout 与 tensor shape 匹配（标准 LLM TND PA 默认 TND；MLA absorb 用 TND_NTD）
• [ ] 10. actual_seq_lengths 构造方式与 layout 匹配（TND 用 cumsum，BSH 用原值；框架部署对应 forward_metadata.actual_seq_lengths_cu_q / actual_seq_lengths_kv）
• [ ] 11. atten_mask 与 sparse_mode 匹配（详见附录 F.1）；MLA absorb Decode 用 None
• [ ] 12. FA v1 vs v2 参数名：未混用（详见附录 F.2）
• [ ] 13. PA 场景下 mask 最后一维 >= block_table 第二维 × block_size
• [ ] 14. MLA rope 参数：query_rope/key_rope 同时传或同时不传；rope D=64，query D 仅支持 512/128
• [ ] 15. inner_precise 行无效：Prefill + 自定义 mask 有全遮蔽行时需设为 2/3
• [ ] 16. kv_len 层内只读：kv_len 在 attention/cache 内部未被修改（禁止层内递增，否则各层写入位置错位导致精度彻底损坏）
• [ ] 17. hidden_states 全程保持 [TotalTokens, hidden_size] 二维形态，未被 reshape 成 [B, S, H]（变长 batch 不能简单 reshape）

第三步：分模块定位

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 写入验证：在写入算子（PA 模式 npu_scatter_nd_update_ / MLA 融合写入 npu_kv_rmsnorm_rope_cache / BSH legacy 骨架 scatter_update_）调用前后插桩，检查：

1. 写入前缓存是否为零（首次 Prefill）
2. 写入后缓存内容与 key_states 是否一致（阈值 1e-6）
3. PA 路径：cache / states 都需 view 为 [total, num_kv_heads, head_dim]；slot_mapping 取 forward_metadata.slot_mapping[self.attn_type].view(-1, 1)
4. BSH legacy 路径：scatter_update_ 的 axis 与 layout 匹配（BSH → axis=1）

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 模式：框架部署由 prepare_slot_mapping() 生成，独立部署 Runner 自管按 block_table 索引构造）
2. 验证写入位置未越界
3. 验证 kv_len 逐步递增正确

FA 入参验证（按路径分类）：

1. 标准 LLM TND PA：sparse_mode=3 + causal mask（与 Prefill 一致）
2. 滑窗层：sparse_mode=4 + band mask + pre_tokens=sliding_window
3. MLA absorb Decode：sparse_mode=0 + mask=None
4. actual_seq_qlen 每个值通常为 1（MTP 场景为 next_n+1）
5. block_table dtype 必须为 int32
6. 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 匹配

★ 标注的 TND / TND_NTD 是框架部署默认推荐 layout（详见 model-infer-kvcache §2.7）。PA 模式下 KV 按 block_table 索引，物理存储 shape [total_blocks, block_size, num_kv_heads, head_dim]，FA 调用时 view 为 [bn, bs, num_head*dim]。

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 范畴但会导致精度异常。