ascendc-operator-precision-debug

Files (7)

• SKILL.md
• async-sync-missing.md · examples/
• fp16-no-upcast.md · examples/
• gm-offset-error.md · examples/
• multicore-tiling-overlap.md · examples/
• tail-tile-misalign.md · examples/
• debug_precision_template.py · scripts/

SKILL.md (first lines)

# AscendC 算子精度调试

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

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

---

## Phase 1：误差分析

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

收集失败用例的 shape、dtype、MaxAbsErr/MeanAbsErr/CosineSim，然后基于 [`scripts/debug_precision_template.py`](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 起始偏移 → 搬运预期字节数
```

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills