ascend-ai-coding/awesome-ascend-skills/ascendc-precision-debug

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 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 路径差异
    │   ├─ 搜索代码中 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排查

// ❌ 错误：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);

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

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