Ascend/ascendc-operator-precision-debug

AscendC 算子精度调试

按「由浅入深」五阶段定位根因：先看数据分布，再查代码易错点，然后实验隔离，最后插桩定位。

Phase 1: 误差分析 → Phase 2: 代码审查 → Phase 3: 实验隔离 → Phase 4: 插桩定位 → Phase 5: 修复验证

---

Phase 1：误差分析

原则：先看数据，再看代码。 先搞清楚「错在哪、错多少、错成什么样」。

收集失败用例的 shape、dtype、MaxAbsErr/MeanAbsErr/CosineSim，然后基于 scripts/debug_precision_template.py 创建 csrc/ops/<op_name>/test/debug_<op_name>_precision.py（替换占位符后运行），自动分析：

1. 误差统计：MaxAbsErr、MeanAbsErr、MaxRelErr
2. 首个错误元素：多维坐标 + 线性下标 + NPU 值 vs 参考值
3. 错误分布：错误元素数量/占比、错误间隔是否呈周期性
4. 特殊值：输出是否全零、含 NaN/Inf
5. 自动对照：固定输入 vs 随机输入、缩小 shape 二分

误差特征 → 初步判断

| 现象 | 最可能原因 | 下一步 | |------|-----------|--------| | FP16 失败，FP32 通过 | 未升精度到 FP32 计算 | Phase 2 查 Cast | | 输出全零 | CopyOut 未执行 / GM 偏移错 | Phase 2 查 CopyOut | | 输出含 NaN/Inf | 除零 / log 负数 / 溢出 | Phase 2 查 Compute | | 全部偏差，CosineSim≈1 | 系统性精度损失 | Phase 2 查升精度 | | 周期性/条纹状错误 | tile 边界 / 搬运偏移 | Phase 3 实验 | | 仅尾部元素错 | 尾 tile 长度 / 对齐 | Phase 2 查尾 tile | | 多次运行结果不同 | 异步同步不足 | Phase 3 实验 B | | 小 shape 过、大 shape 挂 | 多核/tiling 边界 | Phase 3 实验 A | | 固定输入过、随机挂 | 地址/stride/偏移错 | Phase 3 实验 C |

---

Phase 2：代码审查

MANDATORY：读取 op_host/<op_name>.cpp、op_kernel/<op_name>.cpp、design.md（若存在），按以下清单由浅入深排查。

第一层：基本正确性（最高频）

• [ ] FP16/BF16 未升精度：Compute 中半精度是否先 Cast 到 FP32 计算再 Cast 回？这是最高频精度 bug。
• [ ] 计算公式错误：API 调用序列与设计文档/PyTorch 逐步对照——运算顺序、标量符号、是否缺步骤。
• [ ] GM 偏移单位混淆：xGm[progress * tileLength] 是元素偏移，不要多乘 sizeof(T)。
• [ ] tileLength vs curTileLength：偏移用 tileLength，计算/搬运用 curTileLength（尾 tile 可能更小）。

第二层：搬运与对齐

• [ ] DataCopyPad copyLen：DataCopyExtParams 的 copyLen 是字节数 = curTileLength * sizeof(T)。
• [ ] 尾 tile 对齐：尾 tile 不满足 32B 对齐时，alignedTailLen 计算及使用是否正确。
• [ ] 多输入偏移不一致：多输入 tensor shape 不同时（如 RoPE 的 x vs cos/sin），各自的偏移计算是否正确。

第三层：Tiling 与多核

• [ ] Host/Kernel tiling 不一致：同一符号（如 tileLength）在 host 和 kernel 中含义是否一致。
• [ ] 核间边界重叠/遗漏：formerNum × formerLength + tailNum × tailLength 是否恰好覆盖全部数据。
• [ ] bufferCoefficient 错误：与设计文档 UB 分配表核对，错误的系数会导致 tileLength 偏差。

第四层：API 陷阱

• [ ] ReduceSum/Max 修改源数据：归约可能改写源 tensor，后续若复用需先 Adds(backup, src, 0.0f, len) 备份。
• [ ] AllocTensor/FreeTensor 未配对：与 EnQue/DeQue 需严格配对，否则缓冲区泄漏。
• [ ] 向量长度参数：AscendC 向量 API 长度是元素个数，非字节数。

第五层：边界情况

• [ ] 除零 / 定义域越界：Div、Reciprocal 防零；Ln 要求正数；Sqrt 要求非负。
• [ ] tiling 整数溢出：乘法是否可能溢出 int32？建议 int64_t。

检查点：输出审查报告——疑似问题列表（按可能性排序）。若已锁定根因，跳到 Phase 5；否则进入 Phase 3。

---

Phase 3：实验隔离

Phase 2 无法直接锁定根因时，通过控制变量实验缩小范围。每次只改一个变量。

实验 A：block_dim → 1（多核隔离）

在 op_host 临时硬编码 blockDim = 1，重编译测试。可配合缩小 shape。

| 结果 | 结论 | |------|------| | 单核过、多核挂 | 核间问题：GM 区间重叠 / tiling 映射 / 核间同步 | | 单核也挂 | 非多核问题 → 实验 B |

实验 B：PipeBarrier<PIPE_ALL>（同步隔离）

将 kernel Process 中所有同步临时替换为 AscendC::PipeBarrier<PIPE_ALL>()（CopyIn / Compute / CopyOut 之间各加一个）。

| 结果 | 结论 | |------|------| | 全屏障后过 | 核内同步不足 → 逐步恢复细粒度同步定位 | | 仍失败 | 非同步问题 → 实验 C |

PIPE_ALL 仅用于实验隔离，绝不可作为最终方案。

实验 C：固定/规律输入（地址隔离）

分别用全 1、等差序列（torch.arange）、随机输入测试。

| 结果 | 结论 | |------|------| | 全 1 过、等差/随机挂 | 地址/偏移/stride 错误（常数输入掩盖了偏移问题） | | 全都挂 | 计算逻辑或全局 tiling 错误 | | 全都过 | 特定数值范围触发精度问题 → 查边界值/极值 |

实验 D：缩小 shape（边界隔离）

shape=(32,) → (tileLength,) → (tileLength*2,) → 原始 shape，定位恰好开始失败的分界点，反推 tile/核边界。

首错下标 + tiling 反推

首错线性下标 → 第几个 tile → 哪个核 → 该核 GM 起始偏移 → 搬运预期字节数

周期 = tileLength → 搬运/偏移问题；周期 = 向量宽度 → 计算流程问题；与核边界对齐 → 多核/offset 问题。

---

Phase 4：插桩定位

问题范围已收敛到某阶段/某 tile 后，用 AscendC::printf 和 AscendC::DumpTensor 精确定位。

核心规则

1. 仅 0 核打印：每个核计算逻辑一致时，加 if (AscendC::GetBlockIdx() == 0) 减少输出量。
2. 同步后再读：在 DeQue / PipeBarrier 之后才能读 LocalTensor，否则读到未完成搬运的脏数据。
3. FP16 先转 float：AscendC::printf("v=%.6f\n", static_cast<float>(tensor.GetValue(idx)));，直接打 half 会乱码。
4. 用 desc 区分阶段：DumpTensor 的 desc 参数（0=CopyIn 后, 1=Compute 中间, 2=CopyOut 前）。
5. 小量起步：DumpTensor 的 dumpSize 从小值开始，过大会导致缓冲满或截断。

printf vs DumpTensor 选择

| 场景 | 工具 | |------|------| | 标量、分支判断、单个下标 | AscendC::printf | | 连续一段 tensor 快速扫 | AscendC::DumpTensor(tensor, desc, dumpSize) | | 全量逐元素对比 | 不在 kernel 内做 — Host 读 GM + Python 脚本 |

插桩策略

在 Compute 函数内 DeQue 之后，逐步骤插桩，与 Python 侧用相同输入手算的中间结果逐步对比。第一个出现偏差的步骤即为根因所在。

// 示意：0 核、第 0 个 tile
if (AscendC::GetBlockIdx() == 0 && progress == 0) {
    AscendC::printf("[step1] tmp[0]=%.6f\n", static_cast<float>(tmp.GetValue(0)));
}

---

Phase 5：修复验证

常见修复模式

| 根因 | 修复 | |------|------| | FP16 未升精度 | 添加 Cast(fp16→fp32) + 计算 + Cast(fp32→fp16) | | GM 偏移错 | 修正偏移公式（元素 vs 字节） | | 尾 tile 长度错 | 计算/搬运用 curTileLength，偏移用 tileLength | | tiling 参数错 | 修正 host 端 tiling 计算 | | 同步缺失 | 添加正确的 EnQue/DeQue 或 PipeBarrier | | ReduceSum 覆盖源 | 先 Adds 备份再 ReduceSum | | 搬运长度错 | 修正 DataCopyExtParams 的 copyLen |

修复后

1. 移除所有调试插桩（printf/DumpTensor），或用 #ifdef DEBUG_PRECISION 包裹
2. 重新编译安装
3. 运行原失败用例 + 完整精度测试
4. 仍失败 → 回到 Phase 1（最多 3 轮），3 轮后仍失败则报告用户

输出要求（MANDATORY）

调试完成后 MUST 在对话中展示：问题摘要、根因分析、修复内容、验证结果、≥2 条关键经验。NEVER 仅回复「已修复」。

---

典型案例（按需加载）

定位到疑似根因后，加载对应案例了解完整排查过程：

| 误差现象 | 案例文件 | 何时加载 | |----------|---------|---------| | FP16 挂 FP32 过，全部偏差 | examples/fp16-no-upcast.md | 怀疑升精度缺失 | | 首错在 tile 边界，周期 = tileLength | examples/gm-offset-error.md | 怀疑 GM 偏移错误 | | 仅尾部少量元素错 | examples/tail-tile-misalign.md | 怀疑尾 tile 处理 | | block_dim=1 过，多核挂 | examples/multicore-tiling-overlap.md | 怀疑核间 tiling | | 多次运行结果不同 | examples/async-sync-missing.md | 怀疑同步缺失 |

不要一次性加载所有案例。 仅在误差特征匹配时加载对应案例。

---

反模式（NEVER）

• NEVER 不分析误差分布就直接改代码
• NEVER 在 kernel 中 printf 循环打全量 tensor — 用 DumpTensor 或 Host 侧对比
• NEVER 多核同时大量打印 — 加 GetBlockIdx() == 0 仅 0 核打印
• NEVER 在未同步位置读 LocalTensor — 必须在 DeQue/PipeBarrier 之后
• NEVER 用 PIPE_ALL 作为最终修复 — 仅用于实验隔离
• NEVER 修复后不移除调试代码
• NEVER 仅修复已知失败用例而不跑完整精度测试
• NEVER 超过 3 轮仍失败时继续尝试 — 应报告用户