ops-profiling

NPU 性能采集与分析,支持 msprof application 标准可比较计时(每例 10 组 warmup→target 取中位数)、msprof 深度指标采集与算子级瓶颈定位、kernel-level 对比测试(--compare/--quick/--batch)和交互式可视化。核心工具:collect_perf_application.py(标准可比较计时)、msprof_profile

SKILL.md

GitHub

上板性能采集与调优

在真实 NPU 上采集算子性能数据,系统化解读指标文件,判定性能是否达标,定位瓶颈类型,并给出可操作的优化建议。

本技能保留 msprof、msprof op 两条独立路径。先按"外部选择优先"确定工具,只有 msprof 路径使用 10 组相邻预热与中位数的新计时协议;msprof op 保持自身的采集和归档口径。

高频问答速查(先查这里——本节答案即为权威结论,已与脚本实际行为对齐,无需再读源码验证)

问题 答案
compare 模式下用例文件加载优先级? ① <op>_perf_cases.jsonl(标准命名)→ ② 任意 *.jsonl → ③ 任意 *.json(非 .bak)→ ④ model.py 的 get_input_groups()。同时存在时选①(详见下文「用例加载优先级」)
怎么做标准可比较计时? collect_perf_application.py:一次 msprof application 覆盖完整 case 集,每例固定 10 组 warmup → target,取 target 中位数;大 case 集按会话上限自动拆分(详见「使用方式 1」与 application_runner_contract.md)
怎么生成交互式 HTML 性能报告? 使用 msopprof-visualization:已有含 collection_manifest.json 的采集目录用 run_pipeline.py --mode visualize 重渲染;有算子工程用其 run_pipeline.py 采集并生成报告。msprof_profile_run.sh 的 PROF_GROUP_* 归档不能直接用于此渲染链路。
怎么做加速比对比? msprof_profile_run.sh --compare(全量)/ --quick(1 轮快速),输出 performance.json + markdown 报告即完成,不走可视化子技能
quick / compare 如何保留原始 PROF? 在原命令上加 --keep-prof,两种模式均支持透传;默认在采集后清理原始 PROF。保留目录本身不需要手工备份或切换标准模式重采。保留已有数据与补采缺失指标是不同需求,不能把重采作为保留目录的前提,也不能承诺标准模式可提供未经确认的逐指令流水数据。
MC² / 多 rank(fork)算子用什么采集? 必须 msprof,禁止 msprof op(详见 msprof-guide.md「MC² 多 rank 算子采集」)
采集结果如何判定瓶颈? 用 msprof_perf_summary.py 解析 PROF_GROUP_*,输出瓶颈类型与各 pipe 占比,判定规则见 references/msprof-guide.md;需要 MBU/MFU/理论上限量化时用 compute_efficiency.py(cost-model-contract.md)

阅读纪律(防上下文爆炸,必须遵守)

  • scripts/msprof_perf_summary.py(2400+ 行)与 scripts/msprof_profile_run.sh 是可执行工具,不是文档。需要确认某个行为时,只允许 grep -n "<函数名/关键字>" scripts/msprof_perf_summary.py 定位后读命中处前后 ~30 行;禁止整文件通读。
  • references/ 下各文档按文末「参考资源」表的"何时查阅"按需加载;回答本文件已写明的事实性问题时,不需要打开任何 reference 或 script。
  • 本 SKILL.md 覆盖全部使用决策;若与脚本实际行为发现不一致,以脚本行为为准并在本文件勘误。

工具选择

工具优先级是"外部输入 > msprof > 环境不稳定时的 msprof op":

  1. 外部输入显式指定 msprof 或 msprof op:原样执行。
  2. 外部未指定:优先使用 msprof。
  3. msprof 不可用,或环境不稳定导致 application 数据无法通过身份、频率、launch 映射或波动门禁:回落到 msprof op。必须记录回落原因,不得混合两条路径的数据做前后对比。
  4. 两者都不可用:停止并报告环境缺失。

环境稳定性必须由实际探测与采集产物判断,不能仅凭工具是否安装推断。调用方工作流或其他 skill 给出的 profiler 选择属于外部输入,本 skill 不解析其业务约束,也不覆盖其选择。

MC² / 多 rank(fork)算子是硬约束:算子通过 fork() 创建多个子进程绑定不同 NPU 卡、子进程间经 SHMEM UDMA / BarrierAll / CrossCoreFlag 协同通信(如 alltoall_matmul、allgather_matmul、matmul_reducescatter)时,无论外部是否指定,都必须使用 msprof、禁止 msprof op(msprof op 对 fork 程序的采集行为未定义)。加载 references/msprof-guide.md 的「MC² 多 rank 算子采集」章节,同时参考 ascendc-perf-optimize skill 的 references/comm-compute/index.md「性能采集方法」章节。

工具 流程文档 用途
collect_perf_application.py references/application_runner_contract.md msprof application 标准可比较计时:每例固定 10 组 warmup → target,取 target 中位数;内置 CANN 版本适配(--aic-mode=task-based 版本相关、不完整安装预检、单会话 relevant-launch 上限(默认 540)自动拆分与空导出重试)
msprof_profile_run.sh references/msprof-guide.md msprof 深度指标采集、兼容对比测试和批量并行
msprof_perf_summary.py references/msprof-guide.md 统一解析入口:瓶颈分析、对比报告生成、批量汇总
perf_summary.py references/msprof-op-guide.md msprof op 归档(需 msopprof)
compute_efficiency.py references/cost-model-contract.md 实测耗时 → MBU/MFU/瓶颈类型/理论上限 + 优化结论;成本模型(FLOP/字节)可注册或 CLI 直传

使用方式

采集 CANNBotDSL 算子的性能摸底数据时,读取 DSL 公开入口测量,按该方法区分编译、公开入口与设备耗时,并保留完整设备任务证据。

1. msprof 标准可比较计时

一次 msprof application 覆盖完整 case 集。每个 case 固定执行 10 组相邻的 warmup → target,只统计每组 target 的完整 kernel sequence 总耗时,最终取 10 个 target 总耗时的中位数。不得改为均值、丢弃前若干次或追加样本择优。

warmup 固定按以下优先级选择:

  1. 默认使用现成 ops:普通目标使用 ArgMax,目标属于 ArgMax 家族时使用 Max。
  2. 只有 ops probe 失败时,才构建并使用内置 OpsProfilingWarmup 包。
  3. ops probe 和内置包构建都失败时,采集失败。

先把内置包源码落地到目标工程,作为无 ops 环境时的构建后备;此步骤不默认编包:

python3 scripts/install_compiled_warmup.py --project-dir /path/to/operator-project

工程内持久 runner 有现成模板(references/application_runner_contract.md「现成 runner 模板」):有 torch/框架接口用 assets/app_runner/torch/torch_app_runner.py;只有 aclnn 接口(算子已注册并编出 vendor 包、无框架绑定)用 assets/app_runner/aclnn/ 纯 C++ 模板——warmup 直接走 aclnnArgMax/aclnnMax,不依赖 torch。两类模板只改标记的 ADAPTER 段,命令行、execution manifest 与 warmup 协议完全一致。

再按 references/application_runner_contract.md 实现工程内持久 runner,执行:

python3 scripts/collect_perf_application.py \
  --cases ./cases.csv \
  --runner-file ./run_cases.py \
  --identity-manifest ./perf-identity.json \
  --target-op Exp \
  --ops-warmup-probe-cmd 'python3 ./run_cases.py --probe-warmup-op {warmup_op}' \
  --warmup-build-cmd "bash ./ops_profiling_warmup_ext/build.sh --soc=ascend950" \
  --compiled-warmup-binary ./ops_profiling_warmup_ext/ops_profiling_warmup/_C.so \
  --application-cmd 'python3 ./run_cases.py --cases ./cases.csv --case-ids {case_ids} --samples {samples} --execution-manifest {execution_manifest} --warmup-mode {warmup_mode} --warmup-op {warmup_op}' \
  --aic-metrics PipeUtilization \
  --out-dir ./perf/baseline

采集和复用门禁见 references/msprof-guide.md 与 runner 契约。

2. msprof 深度瓶颈分析(标准采集模式)

对单个可执行文件采集 7 组 aic-metrics + sample-based:

bash scripts/msprof_profile_run.sh --warm-up=3 --output=./msprof_output -- \
    ./matmul_tutorial_mxfp4_pingpong 8448 4096 4096

# 解析结果
python3 scripts/msprof_perf_summary.py ./msprof_output/PROF_GROUP_* <ops_dir>

该入口用于补充诊断。其多指标结果不能替代第 1 节的标准 total_us,也不能混入 baseline/candidate 的可比较计时。

若源码含循环内跨核同步或重复目标写入,按 references/msprof-guide.md 联合查看逐核负载、同步频次和任务依赖;把同步开销与负载不均衡作为待验证假设,不用聚合 busy 比例直接换算某个屏障的耗时。

3. 对比测试模式(kernel-level 加速比)

对算子目录下的 model.py vs model_new_ascendc.py 做对比测试:

bash scripts/msprof_profile_run.sh --compare --output-dir=./output/GELU --warm-up=3 --device=0

输出:performance.json + performance.log + perf_report.md

4. 快速模式(1 轮采集,只获取 kernel 时间)

对算子目录做快速对比测试,只跑 1 轮 msprof,不采集 7 个 aic-metrics:

bash scripts/msprof_profile_run.sh --quick --output-dir=./output/GELU --warm-up=3 --device=0

输出:performance.json + performance.log + perf_report.md

5. 批量并行模式(多 NPU)

扫描目录下所有算子子目录,多 NPU 并行执行对比测试:

bash scripts/msprof_profile_run.sh --batch --base-dir=./output_performance --max-jobs=7 --device-start=1

输出:各子目录 performance.json + batch_performance.log + batch_report.md + batch_summary.json


输入目录结构(对比模式)

传统模式(端到端自动开发):

{output_dir}/
├── model.py              # 参考 PyTorch 实现
├── model_new_ascendc.py  # AscendC 实现
├── <op_name>.json        # 测试用例(JSON Lines)
└── kernel/               # AscendC kernel + whl 包

JSONL 模式(ascend-kernel 工程结构):

csrc/ops/<op>/test/
├── <op>_perf_cases.jsonl   # JSONL 用例
├── model.py                # 参考实现
├── model_new_ascendc.py    # AscendC 实现
└── kernel/                 # kernel 工程

用例加载优先级

  1. 优先:<op>_perf_cases.jsonl(标准 JSONL 命名)
  2. 回退:任意 *.jsonl 文件
  3. 回退:任意 *.json 文件(非 .bak,JSON Lines 格式)
  4. 回退:从 model.py 的 get_input_groups() 加载

输出格式(对比模式)

Markdown 报告包含:

  • 对比表:Case | Shape | DType | 自定义算子(us) | 标杆(us) | 加速比
  • 全量汇总:用例数、平均加速比、自定义/标杆更优条数
  • 按数据类型汇总:分 dtype 的统计
  • 简短分析:整体趋势结论
  • 深度瓶颈分析入口:提供 msprof 深度分析命令

额外输出:

  • performance.json — 结构化数据(含 geomean/mean/median/min/max 加速比)
  • performance.log — 屏显日志

深度分析:msprof / msprof op

当性能不达标或需要根因分析时,使用深度分析流程。

arch22(A2/A3)支持详细性能分析,可按 CANN 官方算子性能分析文档 解读采集结果。该链接对应 CANN 8.0.0 alpha001;实际参数、指标与功能以目标 CANN/工具版本为准。arch35 的 RegBase/VF/RVEC 指标不用于推断 arch22 瓶颈,缺失字段不按零值处理。

工具路由只使用上方「工具选择」一节,不得在深度分析阶段重新选路。选择 msprof 时加载 references/msprof-guide.md;选择 msprof op 时加载 references/msprof-op-guide.md。

可视化报告(上板数据 → HTML)

当用户要求把上板采集数据可视化为交互式 HTML 报告(Details、Roofline、Timeline、Cache 热力图、Source 等页面)时,加载子技能 msopprof-visualization/SKILL.md:

  • 有算子工程可上板 replay → 用其 run_pipeline.py 做最小非重复采集并生成报告;
  • 已有含 collection_manifest.json 的采集目录 → 只用 visualize 模式重渲染,不得重复采集。

以下场景不加载可视化子技能:

  • 加速比对比(compare / quick / batch):输出 performance.json + markdown 即完成;
  • MC² / fork 多进程算子:子技能基于 msprof op,该场景对 msprof op 禁用;
  • 纯瓶颈分析或 CSV 指标解读且用户未提及可视化。

注意两套链路输出不互通:本技能的 PROF_GROUP_* 归档不能直接喂给可视化渲染,可视化子技能的采集目录结构由其自身 collect.py 产生。

参考资源

文件 内容 何时查阅
references/msprof-guide.md msprof:标准可比较计时、深度采集 / 归档 / 主 Bound 判定 / MC² 多 rank 采集(文末章节) 选用 msprof 时,或 MC² / fork 多进程算子
references/msprof-op-guide.md msprof op:构建 / 采集 / 归档 / 判定 / 瓶颈 / 回归 外部选择或环境回落到 msprof op 时(不适用于 MC²)
references/application_runner_contract.md application runner、manifest、launch 映射与中位数协议 msprof 可比较计时
references/csv_fields_reference.md CSV 字段定义与阈值 理解指标含义时
references/optimization_quickref.md 瓶颈类型与优化方法 定位瓶颈后
references/cost-model-contract.md 成本模型契约、MBU/MFU/天花板计算、峰值口径 需要量化 bound / 天花板 / 前置剪枝时
references/compiled_warmup.md 内置 warmup 包的构建与使用 ops probe 失败需要构建后备 warmup 时

错误处理

  • 外部显式指定的工具不可用:直接报告缺失,不擅自换工具。
  • 默认 msprof 路径持续无法通过环境或数据门禁:保存失败证据,记录原因后回落到 msprof op。
  • application launch 映射不完整、乱序或身份不一致:整份 collection 作废,不手工补值。

适用场景总览

场景 推荐命令 说明
标准可比较性能采集 collect_perf_application.py msprof application,每例 10 组 warmup → target,取 target 中位数;大 case 集自动按会话上限拆分
MC² 多 rank 算子采集 msprof --aic-mode=task-based 必须用 msprof,禁止 msprof op,详见 msprof-guide.md「MC² 多 rank 算子采集」章节
算子开发完成后的性能验收 msprof_profile_run.sh --compare 快速对比自定义算子 vs 标杆
性能问题定位 msprof_profile_run.sh + msprof_perf_summary.py 深度瓶颈分析
优化效果验证 msprof_profile_run.sh + msprof_perf_summary.py 对比优化前后的归档数据
算子生成阶段快速测试 msprof_profile_run.sh --quick 快速对比测试(1 轮采集,只获取时间)
Agent team 测试阶段 --quick / --compare + 标准采集 先快速对比,不达标再深度分析
端到端自动开发 Phase 5 msprof_profile_run.sh --quick 集成到 tilelang2ascendc-ops-generator 流程(只获取加速比)
进化优化前基线测试 msprof_profile_run.sh --quick 快速获取基线加速比
批量性能测试 msprof_profile_run.sh --batch 多 NPU 并行批量测试
上板数据可视化报告 msopprof-visualization 子技能 交互式 HTML:Details/Roofline/Timeline/Cache/Source 等页面