ascendc-operator-performance-eval

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. 在报告中明确标注：报告头部须写明「无标杆等价接口，标杆路径为小算子拼接」，列明所用的基础算子。
4. 对比表格必须呈现：不得因「无标杆接口」而退化为单路径报告，必须保留「自定义算子 per-step」「标杆 per-step」「比值」三列。

NEVER：以「无标杆等价接口」为由输出单路径报告或跳过对比表。

---

固定 Profiler 步数（强制）

参数	值	说明
warmup	5	不允许脚本或 CLI 改为其它值
active	5	不允许脚本或 CLI 改为其它值
wait	默认 0	可保留 CLI 或常量，按需
repeat	默认 1	简单场景固定为 1；若 repeat>1，须在文档中说明 CSV 选取语义

每步末尾必须 prof.step()；循环总步数 = repeat * (wait + warmup + active)。

---

文件落点（统一在算子 test/ 子目录）

所有下列产物放在 ascend-kernel/csrc/ops/<op>/test/：

类别	命名约定（<op> 如 layer_norm）
用例 仅 JSONL	<op>_perf_cases.jsonl（一行一个 JSON 对象）；不维护、不生成 <op>_perf_cases.json
Markdown 报告	<op>_torch_npu_profiler_report.md（唯一结构化结果落盘；不生成 <op>_torch_npu_profiler_results.json）
Profiler 导出根目录	test/profiler_trace/（或 --trace-root 覆盖）

性能脚本、公共模块与上述文件 同处 test/。

---

性能用例 JSONL 完整规范

以下为用例文件的 完整 字段与类型说明；仅使用 .jsonl 作为用例载体。

1. 文件形态

形态	说明
JSONL	每行 一个 JSON 对象，行尾换行；空行忽略。扩展名 .jsonl。

禁止在本流程中生成或与用例同步维护 .json 数组文件。

2. 单条用例顶层结构

每个用例对象 必须 含键 "inputs"，值为 数组。

Layer Norm 示例（算子不同则替换 build_inputs 约定，结构仍须含 inputs 数组）：

{
  "inputs": [
    { "name": "x", "type": "tensor", "required": true, "dtype": "float16", "shape": [8, 128] },
    { "name": "normalized_shape", "type": "attr", "required": true, "dtype": "int", "value": [128] },
    { "name": "use_affine", "type": "attr", "required": false, "dtype": "bool", "value": true },
    { "name": "eps", "type": "attr", "required": false, "dtype": "float", "value": 1e-05 }
  ]
}

• inputs 内各元素的 name 在同一用例内唯一。
• 其它算子：张量 / tensor_list / attr / 整数张量 range 等规则见 references/REFERENCE_JSON_CASE_FORMAT.md。

3. JSONL 完整示例（两行，Layer Norm）

{"inputs":[{"name":"x","type":"tensor","required":true,"dtype":"float16","shape":[2,128]},{"name":"normalized_shape","type":"attr","required":true,"dtype":"int","value":[128]},{"name":"use_affine","type":"attr","required":false,"dtype":"bool","value":true},{"name":"eps","type":"attr","required":false,"dtype":"float","value":1e-05}]}
{"inputs":[{"name":"x","type":"tensor","required":true,"dtype":"float16","shape":[4,256]},{"name":"normalized_shape","type":"attr","required":true,"dtype":"int","value":[256]},{"name":"use_affine","type":"attr","required":false,"dtype":"bool","value":false},{"name":"eps","type":"attr","required":false,"dtype":"float","value":1e-05}]}

更完整的字段说明（tensor_list、int 张量 range 等）见 references/REFERENCE_JSON_CASE_FORMAT.md。

---

Profiler 与目录语义（摘要）

• 每次 with torch_npu.profiler.profile(...)，在 handler 目录下生成 以 _ascend_pt 为后缀 的导出目录；CSV 路径 …/*_ascend_pt/ASCEND_PROFILER_OUTPUT/op_statistic.csv。
• 每个用例、每种实现（如 custom / baseline）一次独立 with；子路径建议 {trace_root}/{op_trace_tag}/{custom|baseline}/case_XXX/，运行前清空 case_XXX。

详见 references/REFERENCE_PROFILER_AND_METRICS.md。

指标（摘要）

1. 对单次 with 对应 CSV：各算子行 Total Time(us) 求和。
2. 除以 active×repeat（divisor_mode=active_steps 时）或仅 active（active_only）。本技能固定 active=5；若 repeat=1，则 divisor = 5。

---

性能对比报告（Markdown）必备结构

报告格式严格参照 examples/sample_report.md，结构如下：

1. 标题

# 性能评估结果

2. 对比表（统一单表，强制双路径）

所有用例在同一张表中展示，表头固定为 Case | Shape | DType | 自定义算子(us) | 标杆(us) | 加速比。

示例：

## 性能对比

| Case | Shape | DType | 自定义算子(us) | 标杆(us) | 加速比 |
| ---- | ----- | ----- | ------------- | -------- | -------------- |
| 0 | [128, 4096] | float16 | 9.75 | 10.10 | 1.036 |
| 1 | [128, 5120] | float16 | 10.52 | 9.39 | 0.893 |
| 2 | [128, 6144] | float16 | 10.99 | 14.36 | 1.307 |
| 3 | [64, 6400] | float16 | 9.13 | 9.49 | 1.040 |
| 4 | [2, 1024, 4096] | float16 | 57.01 | 84.92 | 1.490 |
| 5 | [2, 1024, 6144] | float16 | 73.80 | 139.56 | 1.891 |
| 6 | [1, 2048, 6400] | float16 | 75.60 | 143.09 | 1.893 |
| 7 | [64, 4096] | float32 | 8.45 | 7.14 | 0.846 |

3. 全量汇总

使用 ## 全量汇总 二级标题，内含键值对表：

## 全量汇总

| 指标 | 值 |
| ---- | -- |
| 用例数 | N |
| 平均 加速比（>1 表示自定义算子更快） | X.XXX |
| 自定义算子更优（比值>1） | M |
| 标杆更优（比值<1） | K |

紧接其下用 ### 按数据类型汇总 三级标题，展示分 dtype 的汇总表：

### 按数据类型汇总

| DType | 用例数 | 平均 加速比 | 自定义算子更优 | 标杆更优 |
| ----- | ------ | ------------------- | ------------- | -------- |
| float16 | 7 | 1.364 | 6 | 1 |
| float32 | 1 | 0.846 | 0 | 1 |

4. 简短分析

使用 ## 简短分析 二级标题，列出 ≥3 条 无序列表形式的简短结论，内容涵盖：整体趋势、不同 dtype / shape 规模差异、访存与计算特征等。

## 简短分析

- 平均 加速比 大于 1，自定义算子整体略有优势。
- 大 shape 下自定义算子优势更明显，向量路径利用更充分。
- float32 小 shape 场景自定义算子略逊于标杆，可能与 kernel launch 开销占比较高有关。

其他约定

• 不写与报告重复的 *_profiler_results.json；中间统计仅存在于脚本内存中并写入 Markdown。

---

对话内展示结果（MANDATORY）

生成 csrc/ops/<op>/test/<op>_torch_npu_profiler_report.md（或已存在且本次运行已更新）后，助手在当前对话的回复中 MUST 同时完成下列事项，不得只输出「报告已生成」和路径而不展示数据：

1. 粘贴主要性能内容（用户无需打开文件即可阅读结论，展示内容与报告结构一致）：
   • 统一对比表：表头 Case | Shape | DType | 自定义算子(us) | 标杆(us) | 加速比，所有 dtype 在同一张表中展示。case 多时可截断并注明「其余见报告」。
   • 全量汇总：键值对形式的汇总指标（用例数、平均比值、自定义算子/标杆更优条数）及按数据类型汇总表。
   • 简短分析：≥3 条 无序列表结论，涵盖整体趋势、不同 dtype / shape 规模差异、访存与计算特征等。

NEVER：仅回复报告路径；NEVER 用「请自行打开 Markdown」替代在对话中展示核心数字与结论。

---

易错点

• warmup / active 被改为非 5，与技能约定不一致。
• 未使用 torch_npu.profiler 或 prof.step() 与 schedule 不一致。
• repeat>1 可能多份 *_ascend_pt 导出；按 mtime 取 CSV 时需说明语义。
• CSV 表头 BOM / 列名变化时须兼容 Total Time(us)。
• 自定义算子未注册时只做标杆路径；对比前须加载自定义库。
• 未读 <op>-test-cases.md 就直接自行设计用例：testcase-gen 已生成统一用例文档，应优先从中提取 shape 和 dtype，避免重复设计。
• 未读 design.md 就直接生成用例：导致 shape 不符合约束、缺少关键执行模式的覆盖（如漏掉 transpose=True 路径）。
• 以「无标杆等价接口」为由输出单路径报告：必须实现小算子拼接标杆路径，始终输出双路径对比表。
• 小算子拼接用 Python 循环逐标量赋值：profiler 采集的是 CPU 逻辑而非 NPU 算子，导致标杆路径耗时失真；标杆实现应以张量操作为主。
• 助手仅输出报告路径、未在当前对话中展示主要表格与汇总结论（违反「对话内展示结果」）。

---

参考实现（examples/layer_norm_profiler_reference/）

与 ascend-kernel/csrc/ops/layer_norm/test/ 中 profiler 相关文件保持同构，包含：

• layer_norm_profiler_common.py、benchmark_layer_norm_torch_npu_profiler.py
• layer_norm_perf_cases.jsonl（仅 JSONL，无 .json）
• LAYER_NORM_PROFILER_PERF_GUIDE.md、README.md

新算子从该目录 整体拷贝 到 csrc/ops/<op>/test/，再替换算子名、前向调用、build_inputs 与 trace 子目录名。若仓内 layer_norm/test/ 有更新，应同步回 examples/layer_norm_profiler_reference/。

---

检查清单（助手自检）

• 已读取 csrc/ops/<op>/test/<op>-test-cases.md（若存在），从中提取 SUPPORTED_DTYPES、TEST_SHAPES、GENERAL_SHAPES、算子标杆
• 已读取 csrc/ops/<op>/design.md，从中提取 dtype、参数约束、典型 shape、执行模式
• 用例覆盖 design.md 中描述的所有执行模式（如 transpose/非transpose、input_split 模式等）
• 用例中参数值（属性值与整数张量值）均在 design.md 约束范围内
• 已确认标杆路径类型（标杆 API 或小算子拼接），并在报告头部明确标注
• 若无标杆等价接口，已实现小算子拼接标杆路径，且标杆实现以张量操作为主（非 Python 标量循环）
• 已用 torch_npu.profiler，且 warmup=5、active=5 未被改写
• 已生成或更新 <op>_torch_npu_profiler_report.md，格式与 examples/sample_report.md 一致：含 DType 列的统一对比表 + 全量汇总 + 按数据类型汇总 + 简短分析
• 已在当前对话中展示含 DType 列的统一对比表、全量汇总、按数据类型汇总与 ≥3 条简短分析结论，不仅附路径
• 已说明固定步数约定与指标口径