External Cannbot Ops Ascendc Precision Debug

Ascend C 算子精度调试

核心理念

精度调试 = 理解 + 分析 + 定位 + 修复

1. 理解数据类型限制：FP16 约 3-4 位有效数字，FP32 约 6-7 位。
2. 识别数值稳定性问题：大数吃小数、灾难性抵消。
3. 掌握科学调试方法：从最小复现到根因分析。

使用时机

适用：精度验证失败（rtol/atol 不达标）、输出全为0或随机值、FP16差于FP32、特定数值范围误差大、流水线同步问题、DataCopy对齐问题。

调试前置要求 ⭐⭐⭐

进入调试前必须完成以下三步

1. 固定最小可复现用例

选择原则：优先简单 → 优先32字节对齐 → 优先FP32 → 覆盖边界值

💡 推荐实践：调试时建议在至少两个 dtype（如 FP16 和 FP32）上用同一 shape + 同一数据验证。如果一种 dtype 通过另一种失败，可按下方对应的诊断模式快速缩小范围。

2. 检索 asc-devkit ⭐

禁止凭直觉修改代码

检索顺序：

1. 搜索 asc-devkit/examples/ 查找类似算子。
2. 查看 asc-devkit/docs/api/context/ API 文档。
3. 对比官方实现与当前实现。

3. 清理缓存和临时文件

rm -rf build input output
mkdir -p build/input build/output

快速决策树

[前置检查] 已固定用例？已检索API？已清理缓存？
    │
    └─ 否 → 先完成前置步骤
    └─ 是 → 继续
        │
        ├─ [第0步] ⭐ 代码修改后输出完全不变？
        │   ├─ 是 → 清理 build/ 和 kernel_cache 后重试
        │   └─ 否 → 继续
        │
        ├─ [第0.5步] ⭐ 多 dtype 交叉验证
        │   ├─ FP32通过但FP16/BF16失败 → 精度不足，见下方诊断模式
        │   ├─ BF16通过但FP16/FP32失败 → API fallback 路径差异 或 精度阈值差异，见下方诊断模式
        │   └─ 全部通过/全部失败 → 继续
        │
        ├─ [第一步] 排查数据搬运 ⭐⭐⭐
        │   ├─ 输出是否全为 0 或随机错误？
        │   │   ├─ 是 → 检查流水线同步（EnQue / DeQue）⭐⭐⭐
        │   │   │       └─ DataCopy 后直接计算？→ 添加 EnQue/DeQue
        │   │   │       └─ 临时验证：加 PipeBarrier，若正确则确认同步问题
        │   │   ├─ 检查 DataCopy 是否 32 字节对齐
        │   │   │       └─ 非对齐 → 改用 DataCopyPad
        │   │   └─ 检查是否使用 GlobalTensor.SetValue
        │   │           └─ 是 → 改用 LocalTensor.SetValue + DataCopyPad 搬出到 GM
        │   └─ 验证：用 "CopyIn → CopyOut" 测试搬运
        │
        ├─ [第二步] 对比分析
        │   └─ 对比官方示例与当前实现 → 发现差异
        │
        └─ [第三步] 诊断问题类型
            ├─ 所有结果都差 → 公式/常量/API选择
            ├─ 个别值错误 → 边界条件/除零/溢出
            └─ 误差整体偏大 → FP16精度不足 → 尝试FP32中间计算

症状-原因速查表

诊断模式："FP32 通过但 FP16/BF16 失败"

这是最常见的精度诊断信号：FP16/BF16 在 Ascend C 中通常共享相同的 Cast-to-FP32 计算路径（if constexpr (std::is_same_v<T, bfloat16_t> || std::is_same_v<T, half>)），FP32 通过说明核心算法正确，问题在半精度转换环节。

确认: FP32通过，FP16/BF16失败
    │
    ├─ 检查中间计算精度
    │   ├─ FP16/BF16 Cast→FP32 计算路径是否正确？
    │   ├─ 是否有未升精度的中间运算（如直接 Add<half>）？
    │   └─ 验证：将 FP16 路径的中间计算全部用 FP32，观察结果
    │
    ├─ 检查 Cast RoundMode
    │   ├─ half→float 应使用 CAST_NONE
    │   ├─ float→half 应使用 CAST_ROUND
    │   └─ 验证：对比 Cast 前后的数值
    │
    ├─ 检查 Pipeline 同步
    │   ├─ FP16/BF16 路径有额外的 Cast 操作，Cast 后是否 EnQue/DeQue？
    │   ├─ FP32 路径无 Cast，天然无此同步问题
    │   └─ 验证：在 Cast 后加 PipeBarrier，若正确则确认同步问题
    │
    └─ 检查 Buffer 大小
        ├─ FP16/BF16 路径需额外 Cast buffer（2× innerDim × sizeof(float)）
        ├─ FP32 路径不需要 Cast buffer
        └─ 验证：检查 Tiling 中 castBuf 大小计算

诊断模式："BF16 通过，但 FP16/FP32 失败"

这是一个有价值的诊断信号，可能由两类原因导致：

原因1：API 不支持导致 fallback 路径差异。部分 Ascend C 算术/归约 API 不支持 BF16，开发者为 BF16 实现更简单的 fallback 路径。BF16 fallback 通过说明逻辑正确，问题出在 FP16/FP32 路径中调用的复杂 API 上。

原因2：精度阈值 / 数值范围差异。BF16 (mantissa 7bit, 指数范围同 FP32) 与 FP16 (mantissa 10bit, 指数范围更小) 精度特性不同：BF16 不易溢出但尾数精度低，FP16 易溢出但尾数精度高。如果验证阈值（rtol / atol）未区分适配，或 FP16 发生溢出而 BF16 没有，就会出现 BF16 通过但 FP16 失败。

确认: BF16通过，FP16/FP32失败
    │
    ├─ [原因1] API fallback 路径差异
    │   ├─ 搜索代码中 if constexpr (std::is_same_v<T, bfloat16_t>) 分支
    │   ├─ BF16 走的 fallback 路径 vs FP16/FP32 走的主路径，差异在哪里？
    │   ├─ 列出 FP16 / FP32 路径中使用但 BF16 路径未使用的 API
    │   ├─ 逐个验证差异 API 的参数（mask、repeatTime、stride）
    │   └─ 临时将 FP16 路径改为与 BF16 相同的 fallback 实现，观察是否通过
    │
    ├─ [原因2] 精度阈值 / 数值范围差异
    │   ├─ FP16 是否溢出？（FP16 max ≈ 65504，BF16 指数范围同 FP32）
    │   ├─ 验证阈值（rtol/atol）是否按 dtype 区分？
    │   │   ├─ BF16: rtol=1e-2 级别（mantissa 仅 7bit）
    │   │   └─ FP16: rtol=1e-3 级别（mantissa 10bit）
    │   └─ 检查中间计算是否因 FP16 的更高精度要求暴露了算法缺陷
    │
    └─ 交叉验证
        ├─ 检查 asc-devkit 文档确认相关 API 是否支持 BF16
        ├─ 如果 API 不支持 BF16 → 优先按原因1排查
        └─ 如果 API 支持 BF16（BF16/FP16 走相同路径）→ 优先按原因2排查

常见陷阱速查

流水线同步调试

核心问题：DataCopy / DataCopyPad 是异步 DMA 操作，直接在搬运后的数据上做 Vector 计算可能读到未完成的数据！

// ❌ 错误：AllocTensor 后直接用
LocalTensor<T> x = inQueue.AllocTensor<T>();
DataCopy(x, gm, size);
Compute(x);  // 错！可能读到未完成搬运的数据

// ✅ 正确：DeQue 后再计算
LocalTensor<T> x = inQueue.AllocTensor<T>();
DataCopy(x, gm, size);
inQueue.EnQue(x);
LocalTensor<T> xIn = inQueue.DeQue<T>();  // 等待搬运完成
Compute(xIn);

临时调试方法：

DataCopy(x, gm, size);
PipeBarrier<PIPE_ALL>();  // 临时加，如果结果正确说明是同步问题
Compute(x);

如果 PipeBarrier 能解决问题，说明是同步问题 → 修复方案：改为 EnQue/DeQue 机制

详细说明见 references/common-traps.md

调试策略层级

调试方法
    │
    ├─ 快速方法（优先尝试，≤7次）
    │   ├─ 误差分布分析 → 识别误差模式
    │   ├─ Printf 特定位置 → 缩小范围
    │   └─ 常见陷阱排查 → 对症下药
    │
    └─ 二分调试（保底手段）
        └─ 快速方法尝试≥7次或方法穷尽时立即切换

重要原则：不要盲目试错超过 7 次

问题定位方法

1. 对比法（与工作的代码对比）

找到正常工作的代码，逐行对比差异

2. 边界二分法

记录通过/失败的临界点，分析分支选择

3. 数值验证法

不要相信估算公式，用代码计算实际值

4. Buffer 调试要点

详细定位流程见 references/diagnosis-workflow.md

精度标准来源优先级

1. 优先级1：算子开发 Plan 中明确的精度要求
2. 优先级2：华为昇腾官方精度标准文档
3. 优先级3：本 Skill 默认值（仅作兜底）

Agent 使用指南

调试计数规则

计数器 = 0
每次尝试快速方法（误差分析/Printf/陷阱排查）→ 计数器+1
当 计数器 >= 7 或 快速方法穷尽 → 立即切换二分调试

💡 经验建议：如果多次尝试未取得进展（失败用例数量未减少），建议：

1. 检查是否清理了编译缓存（rm -rf build/ $HOME/atc_data/kernel_cache/）
2. 验证修改后二进制 sha256 是否确实改变
3. 切换到完全不同的调试策略（如二分法降级到最小工作路径）

调试总结要求

每步调试成功后必须形成总结：

• 文档描述不清晰的地方
• 需要改进的地方及推荐方案
• 给 Agent 造成困扰的点
• 调试过程记录

总结模板：references/debug-summary-template.md

检查清单

调试阶段：

• 已固定最小可复现用例
• 已检索 asc-devkit 确认 API 用法 ⭐
• 已清理缓存和临时文件
• 已排查流水线同步问题（DataCopy 后是否 EnQue/DeQue）⭐⭐⭐
• 已排查输出全为 0 问题（DataCopy 对齐 / GlobalTensor.SetValue → LocalTensor.SetValue + DataCopyPad）⭐⭐⭐
• 对比官方示例与当前实现
• 尝试次数 < 7
• 达到阈值立即切换二分调试

参考资料

工作流程

• diagnosis-workflow.md - 完整诊断工作流程
• binary-search-debug.md - 二分调试详细指南

问题诊断

• common-traps.md - 常见精度陷阱详解
• best-practices.md - 最佳实践

调试工具

• printf-debug.md - Printf 调试法
• data-comparison.md - 数据对比法
• tools-reference.md - 工具和命令参考

实战案例

• case-studies.md - 实战调试案例
• debug-summary-template.md - 调试总结模板