ascendc-operator-performance-eval

Files (10)

• SKILL.md
• LAYER_NORM_PROFILER_PERF_GUIDE.md · examples/layer_norm_profiler_reference/
• README.md · examples/layer_norm_profiler_reference/
• benchmark_layer_norm_torch_npu_profiler.py · examples/layer_norm_profiler_reference/
• layer_norm_perf_cases.jsonl · examples/layer_norm_profiler_reference/
• layer_norm_profiler_common.py · examples/layer_norm_profiler_reference/
• sample_perf_cases.jsonl · examples/
• sample_report.md · examples/
• REFERENCE_JSON_CASE_FORMAT.md · references/
• REFERENCE_PROFILER_AND_METRICS.md · references/

SKILL.md (first lines)

# AscendC 算子 torch_npu.profiler 性能评估

## 本技能目录内参考文件

执行本技能时，应优先使用 **本目录** 下材料：

| 文件 / 目录 | 用途 |
|-------------|------|
| **`SKILL.md`**（本文件） | 流程、目录约定、**完整 JSONL 用例规范**、报告结构、**固定 schedule** |
| **`references/REFERENCE_JSON_CASE_FORMAT.md`** | 与下文「性能用例 JSONL 规范」**同文** |
| **`references/REFERENCE_PROFILER_AND_METRICS.md`** | `torch_npu.profiler`、`op_statistic.csv`、`*_ascend_pt` 路径 |
| **`examples/sample_perf_cases.jsonl`** | 最小 LayerNorm 风格 JSONL，可复制改名 |
| **`examples/layer_norm_profiler_reference/`** | **Layer Norm 参考实现**（`layer_norm_profiler_common.py`、`benchmark_layer_norm_torch_npu_profiler.py`、用例 JSONL、说明）；新算子可复制该目录到 `csrc/ops/<op>/test/` 再替换前向与文件名 |

---

## 角色

在 **ascend-kernel** 中，为 `csrc/ops/<算子名>/` 建立可复用的 **profiler 性能用例** 与 **自定义算子 vs 标杆** 的 Markdown 报告流程。采集必须走 **`torch_npu.profiler`**，且 **`warmup` 与 `active` 固定为 5**（见下节）。细节见 **`references/REFERENCE_PROFILER_AND_METRICS.md`**。

**核心原则（两条强制约束）**：

1. **对比报告始终必须呈现**：无论标杆路径是标杆 API 还是小算子拼接，最终报告都必须含自定义算子 vs 标杆的双路径对比表，**禁止使用单路径报告替代**，**标杆必须在NPU上运行**。
2. **用例生成必须先读 `design.md`**：在生成任何 JSONL 用例之前，必须读取算子目录下的 `csrc/ops/<op>/design.md`，从中提取参数约束、典型 shape、支持的 dtype 及关键属性值，用例须覆盖设计文档中描述的所有执行模式。

---

## 用例来源：从 testcase-gen 用例文档加载（MANDATORY）

**在生成或修改任何 JSONL 用例之前**，**MUST** 首先读取 testcase-gen 产出的用例文档：

### Step 0：读取 testcase-gen 用例文档

```
READ csrc/ops/<op>/test/<op>-test-cases.md
```

从中提取：

| 提取项 | 在用例文档中的位置 | 用途 |
|--------|-------------------|------|
| SUPPORTED_DTYPES | §测试配置 | JSONL 用例的 dtype 覆盖范围 |
| TEST_SHAPES | §测试配置 | 小/中/大规模 shape 的选取基准 |
| GENERAL_SHAPES | §测试配置 | 泛化 shape，可补充用于性能场景 |
| NPU 调用方式 | §算子标杆 | 自定义算子的前向调用 |
| CPU 参考实现 | §算子标杆 | 标杆路径的参考实现 |

### testcase-gen 输出 → JSONL 用例转换规则

1. 从 TEST_SHAPES + GENERAL_SHAPES 中选取**代表性 shape**（覆盖小/中/大规模），避免重复
2. 每个 shape 遍历 SUPPORTED_DTYPES 中的全部 dtype
3. 结合 design.md 中的属性值（如 block_size、eps 等）填充 JSONL 的 `inputs` 字段
4. JSONL 用例总数 **≥ 8**
5. 算子标杆中的 NPU 调用方式和 CPU 参考实现用于构建自定义算子路径和标杆路径

> **若 `<op>-test-cases.md` 不存在**：回退为完全从 design.md 自行设计用例（按下方流程），但需在报告中注明"用例为自行设计，非 testcase-gen 产出"。

---

## 用例生成：必须先读 design.md（强制）

**在生成或修改任何 JSONL 用例之前**（无论是否已加载 testcase-gen 用例文档），必须执行以下步骤：

### Step 1：读取设计文档

```
READ csrc/ops/<op>/design.md
```

从中提取：

| 提取项 | 在 design.md 中的位置 | 用途 |
|--------|----------------------|------|
| 支持的数据类型 | §1「支持的数据类型」 | 用例的 dtype 覆盖范围 |
| 参数约束与取值范围 | §1「参数说明」约束条件列 | 属性值的合法范围（如 block_size ≤ 128） |
| 典型 shape / 输入规模 | §2「计算逻辑」/ §3「Tiling 策略」 | 小/中/大规模用例的 shape 基准 |
| 关键属性的模式组合 | §2「伪代码」/ §1「参数说明」 | 需要各自覆盖的执行路径（如 do_transpose=True/False、is_input_split=True/False） |
| 性能关键点 | §6「性能优化」/ §3「Tiling 策略」 | 影响性能的分支（如转置 vs 非转置走不同 DMA 路径） |

### Step 2：用例设计规则

| 规则 | 说明 |
|------|------|
| **覆盖所有执行模式** | design.md 描述了多个执行路径（如转置/非转置、input_split 模式）时，每种模式必须有至少一个用例 |
| **覆盖所有支持的 dtype** | 每种支持的数据类型至少有一组用例，典型中等规模 shape |
| **小/中/大规模 shape 各一组** | 小规模（内核 launch 开销主导）、中规模（典型生产场景）、大规模（访存带宽主导）各需覆盖 |
| **参数值来自约束范围** | 属性值（如 block_size）必须从 design.md 的约束条件中选取，不得随意设定 |
| **整数/索引张量值须语义合法** | win_lengths、offsets 等张量的具体值需满足算子语义（如 offsets 必须是合法的 window 起始偏移） |

### Step 3：验证用例

生成用例后检查：
- [ ] 所有 dtype 均已覆盖
- [ ] 所有执行模式（由 design.md 定义）均有对应用例
- [ ] 参数值（含属性值和整数张量值）在 design.md 约束范围内
- [ ] 包含至少一个「小 shape」用例和一个「大 shape」用例

---

## 参考路径决策树（强制）

性能评估**始终**需要双路径对比（自定义算子 vs 标杆），按以下顺序确定标杆路径：

```
算子是否有标杆等价 API？
  ├─ 是（如 torch.nn.functional.*、torch_npu 内置算子）
  │    └─ 使用标杆 API 作为标杆路径
  └─ 否（无标杆等价接口）
       └─ 必须实现「小算子拼接」标杆路径 ← 本技能的强制要求
            └─ 用设计文档 §「参考实现」或「伪代码」中的 PyTorch 基础算子组合实现
```

### 小算子拼接标杆路径要求

当无标杆等价接口时，**必须**：

1. **从 design.md 读取参考实现**：设计文档通常包含 PyTorch 参考实现（伪代码或 Python 函数），以该实现为基础构建标杆路径。
2. **使用 PyTorch 基础算子组合**：`torch.zeros`、切片赋值、`.permute()`、`torch.cat` 等。不得使用循环+Python 标量赋值（否则 profiler 采集的是 CPU 算子而非 NPU 算子，无法公平对比）；整个标杆实现必须以张量操作为主，可在 NPU 上执行。
3. **在报告中明确标注**：报告头部须写明「无标杆等价接口，标杆路径为小算子拼接」，列明所用的基础算子。

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills