Skip to main contentexternal-gitcode-ascend-ascendc-operator-performance-eval
在 ascend-kernel 的 csrc/ops/<op>/test 下维护仅含 JSONL 的 profiler 性能用例，使用 torch_npu.profiler（固定 warmup=5、active=5）采集，汇总 ASCEND_PROFILER_OUTPUT/op_statistic.csv 的 Total Time(us)，输出含 DType 列的统一 Markdown 对比报告（自定义算子 vs 标杆）。不生成 perf_cases.json 与 *_profiler_results.json。参考实现见 examples/layer_norm_profiler_reference/。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/ascend-ai-coding/awesome-ascend-skills --skill external-gitcode-ascend-ascendc-operator-performance-evalيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
المزيد من هذا المستودع
评估 CANN 算子仓的「进阶教程 / 开发指南」类文档质量——通读文档 + 对照算子代码**静态**查证(默认不跑),按五轴(找得到/信得过/学得会/可操作/读得懂)找出 漏讲/讲不清/过时/对不上代码/概念讲错,产出带证据与改进建议的体检报告(MD + HTML)。涉及「评进阶教程 / 开发指南文档质量 / 文档对不对得上代码 / 教程审稿 / tutorial 体检 / 文档信不信得过」等意图时使用。只评不改不跑,只对着文档与代码出诊断。
Run NPU inference/training tests on a remote SSH server with vllm-ascend Docker container. Use when the user asks to test models on NPU, run inference on Ascend devices, or deploy models to an SSH server.
vllm-daily-pr-issue-tracker Track daily PRs and Issues from vllm-project/vllm and vllm-project/vllm-ascend, filter by model (DeepSeek/Qwen/GLM/MiniMax/Kimi) and tech topics (PD disaggregation, MTP, quantization, graph mode, performance), analyze with LLM, and generate a Markdown report. Use when user wants vllm daily tracker, PR/Issue digest, or Ascend inference ecosystem monitoring.
المهن ذات الصلةSOC
استنادا إلى تصنيف SOC المهني
| name | external-gitcode-ascend-ascendc-operator-performance-eval |
| description | 在 ascend-kernel 的 csrc/ops/<op>/test 下维护仅含 JSONL 的 profiler 性能用例，使用 torch_npu.profiler（固定 warmup=5、active=5）采集，汇总 ASCEND_PROFILER_OUTPUT/op_statistic.csv 的 Total Time(us)，输出含 DType 列的统一 Markdown 对比报告（自定义算子 vs 标杆）。不生成 perf_cases.json 与 *_profiler_results.json。参考实现见 examples/layer_norm_profiler_reference/。 |
| argument-hint | 可选：算子名、对比 API（自定义算子 torch.ops.npu.* / 标杆 F.* 或 npu_*）、用例是否与精度 JSONL 对齐。 |
| original-name | ascendc-operator-performance-eval |
| synced-from | https://gitcode.com/Ascend/agent-skills |
| synced-date | 2026-05-26 |
| synced-commit | 1f7666e7768a0ceb21bb1d40ce4b5179fcb6f1d6 |
| license | UNKNOWN |
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。
核心原则（两条强制约束）：
- 对比报告始终必须呈现：无论标杆路径是标杆 API 还是小算子拼接，最终报告都必须含自定义算子 vs 标杆的双路径对比表，禁止使用单路径报告替代，标杆必须在NPU上运行。
- 用例生成必须先读
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 用例转换规则
- 从 TEST_SHAPES + GENERAL_SHAPES 中选取代表性 shape（覆盖小/中/大规模），避免重复
- 每个 shape 遍历 SUPPORTED_DTYPES 中的全部 dtype
- 结合 design.md 中的属性值（如 block_size、eps 等）填充 JSONL 的
inputs 字段
- JSONL 用例总数 ≥ 8
- 算子标杆中的 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：验证用例
参考路径决策树（强制）
性能评估始终需要双路径对比（自定义算子 vs 标杆），按以下顺序确定标杆路径：
算子是否有标杆等价 API？
├─ 是（如 torch.nn.functional.*、torch_npu 内置算子）
│ └─ 使用标杆 API 作为标杆路径
└─ 否（无标杆等价接口）
└─ 必须实现「小算子拼接」标杆路径 ← 本技能的强制要求
└─ 用设计文档 §「参考实现」或「伪代码」中的 PyTorch 基础算子组合实现
小算子拼接标杆路径要求
- 从 design.md 读取参考实现：设计文档通常包含 PyTorch 参考实现（伪代码或 Python 函数），以该实现为基础构建标杆路径。
- 使用 PyTorch 基础算子组合：
torch.zeros、切片赋值、.permute()、torch.cat 等。不得使用循环+Python 标量赋值（否则 profiler 采集的是 CPU 算子而非 NPU 算子，无法公平对比）；整个标杆实现必须以张量操作为主，可在 NPU 上执行。
- 在报告中明确标注：报告头部须写明「无标杆等价接口，标杆路径为小算子拼接」，列明所用的基础算子。
- 对比表格必须呈现：不得因「无标杆接口」而退化为单路径报告，必须保留「自定义算子 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 覆盖） |
性能用例 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。
指标（摘要）
- 对单次
with 对应 CSV：各算子行 Total Time(us) 求和。
- 除以
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 同时完成下列事项，不得只输出「报告已生成」和路径而不展示数据：
- 粘贴主要性能内容（用户无需打开文件即可阅读结论，展示内容与报告结构一致）：
- 统一对比表：表头
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.pylayer_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/。
检查清单（助手自检）
