msot-msopprof-operator-profiler
当用户希望使用 msOpProf(`msprof op` / `msprof op simulator`)对昇腾 AI 算子做上板或仿真性能调优、解释 `aic-metrics`/`trace.json`/`visualize_data.bin`、选择 device vs simulator 路径、排查 `--soc-version`/`--export`/`signal 6`/`Bad addr
Файлы4
Открыть в GitHubSKILL.mdskills/operator/msot-msopprof-operator-profiler/SKILL.md
GitHubmsOpProf 算子性能调优
使用本技能时,咨询和执行任务都必须先完成资料查询:在代码仓 https://gitcode.com/Ascend/msopprof 查询 msopprof 与 msopprof simulator 使用资料。下文及 references 中的参数、能力边界和命令模板按返回的相关正文核验后使用;查询失败时查找本地相关工具或本地资料参考用法回答和命令执行。
何时必须使用本技能
当用户问题包含以下任一类需求时,应优先使用本技能:
- 明确提到
msprof op、msprof op simulator、msOpProf - 询问如何做 算子性能调优 / 上板调优 / 仿真调优
- 询问如何查看或解释:
visualize_data.bintrace.jsonOpBasicInfo.csvPipeUtilization.csvMemoryDetailRooflinePMSampling
- 询问如何在 device vs simulator 之间选择
- 询问
application/config/export三种输入形态的差别 - 询问如何生成 固定报告 / 模板化结论 / Top 5 总结
- 遇到以下高频故障:
signal 6Bad address--soc-version不生效--kernel-name不生效--export目录如何组织TimelineDetail/PMSampling/--core-id为什么行为不符合预期
不要在这些场景误用本技能
- 用户只是在问通用 CANN 安装,而不是 msOpProf 本身
- 用户只想修一个普通编译错误,且问题与 msOpProf 调优流程无关
- 用户只是要翻译某段文档,而不是要执行或理解调优流程
- 用户要分析的是其他 profiling 工具(如纯 DB 分析、整机 profiler、非 msOpProf 产物)
技能目标
帮助算子开发者在 上板(device) 或 仿真(simulator) 模式下:
- 选对运行模式和输入形态(
application/config/export)。 - 生成最小可用且可解释的性能数据。
- 根据产物类型(CSV /
visualize_data.bin/trace.json)选择正确查看方式。 - 避免被模式差异、芯片限制、参数互斥和目录要求误导。
执行协议
每次使用本技能时,按下面顺序工作,不要跳步:
- 先识别用户当前模式
- 用户到底在问 device、simulator,还是还没决定?
- 再识别输入形态
application/config/export
- 再识别目标
- 采集数据、解释产物、选参数、排故、看热点图还是看流水图
- 只加载必要 reference
- 若用户重点是上板路径,优先读
references/device-tuning-guide.md - 若用户重点是仿真路径或 dump/trace 解析,优先读
references/simulator-tuning-guide.md - 若用户给了
signal 6/Bad address等仿真拉起错误,再读experiences/simulator-needs-sim-build.md
- 若用户重点是上板路径,优先读
- 输出时必须显式带条件
- 说明“这条建议适用于 device 还是 simulator”
- 说明“这条参数是否只对 application / config / export 生效”
使用本技能时的硬规则
- 先分模式,再谈参数。
msprof op ...= 上板调优。msprof op simulator ...= 仿真调优。
- 先分输入形态,再谈命令。
application:拉起可执行文件。config:基于 JSON 配置和.o文件。export:仅在 simulator 模式下,直接解析已有 dump。
- 不要把条件化事实说成统一结论。
- 很多参数只在特定模式、芯片或输入形态下生效。
- 区分官方事实与经验。
- 本技能的主说明以当前仓内
msopprof参考代码和 user guide 为准。 experiences/下的内容视为经验案例,不自动提升为通用规则。
- 本技能的主说明以当前仓内
- 遇到文档口径差异时必须明说。
- 例如仓内不同章节对通算流水图支持范围有不同表述;若用户追问精确支持范围,优先以当前安装版本帮助信息和对应专章为准。
禁止事项
- 不要把 simulator 的
trace.json和 device 的trace.json混成同一种语义。 - 不要把
TimelineDetail说成 simulator 参数。 - 不要把
--soc-version说成所有 simulator 场景都必选。 - 不要把
--kernel-name说成对config/export也有效。 - 不要把经验文件中的案例说成“所有工程都必须这样”。
- 不要在没有说明前提的情况下,直接给出一个看似通用的命令。
- 没有实际 profiling 数据时,不要强行输出 Top 5 固定报告。
- 数据不足 5 项时按真实数量输出,不要补齐、不造数。
- 不要把命令指导、环境准备或经验猜测伪装成“核心瓶颈”或“优化建议”。
- 不要给出与当前模式明显不兼容的建议(例如把 simulator 参数建议给 device)。
快速决策树
- 你有真实 NPU 卡,且要看真实硬件瓶颈吗?
- 是:优先走 上板调优。
- 你没有卡,或者要看指令级流水 / 代码热点吗?
- 是:优先走 仿真调优。
- 你的输入是什么?
- 可执行文件:
application - JSON +
.o:config - 已有 dump:
export(仅 simulator)
- 可执行文件:
- 你要的是哪类结论?
- 真实耗时 / 内存 / Cache / Roofline:优先上板
- 指令流水 / 每核热点 / 指令级冲突:优先仿真
默认输出契约
默认按两条分支输出,不要混用:
分支 A:结果分析 / 调优结论 / 报告化输出
满足以下任一条件时,最终回复默认使用固定四段报告模板:
- 用户已经给出 profiling 产物或结果现象,要求解释 / 总结 / 诊断 / 调优建议
- 用户明确要求“报告”“模板化输出”“Top 5 结论”
- 当前任务重点是解释
csv/visualize_data.bin/trace.json/ 热点图 / 流水图,而不是教用户先跑命令
分支 B:命令指导 / 模式选择 / 采集前排障
满足以下场景时,不强制使用固定报告模板,继续使用 guidance-first 输出:
- 用户还没有 profiling 数据,只是在问怎么采集
- 用户重点是选 device / simulator / application / config / export
- 用户处于启动失败、环境不通、参数不会配的阶段
此时优先输出:
- 建议路径
- 先明确推荐 device 还是 simulator,以及原因
- 可直接执行的最小命令
- 给出与用户当前场景匹配的最小正确命令
- 关键限制
- 只列当前问题真正相关的 2~5 条限制
- 怎么看结果
- 告诉用户跑完后看哪一个文件、用什么工具打开、重点看什么
- 下一步
- 若这是首轮采集:告诉用户下一步该加什么指标
- 若这是排障:告诉用户下一步该补什么信息或切哪条路径
固定报告模板(默认用于结果分析)
模板启用规则
- 默认
TOPx = TOP5 - 如果用户明确指定别的
x,可覆盖默认值 - 数据不足 5 项时按真实数量输出,不补齐
- 每个 Top 条目都应尽量带
数据来源 - 如果当前模式或数据集不支持某项,写
N/A、未采集或不适用当前模式
固定标题
结果分析场景下,最终回复默认使用以下四段标题,不要自行改名:
## 1. 算子基本信息
## 2. 关键数据 TOP5
## 3. 核心瓶颈 TOP5
## 4. 优化建议 TOP5
1. 算子基本信息
使用短表格或键值表,不使用 Top 5。默认字段:
| 字段 | 内容 |
|---|---|
| 模式 | device / simulator |
| 输入形态 | application / config / export |
| 算子名 / 目标对象 | 当前分析对象 |
| 芯片 / 仿真器 | 芯片型号或 simulator 类型 |
| 采集指标 | 当前启用的 aic-metrics 或主要分析视图 |
| 主要产物 | 当前引用的 CSV / bin / trace |
| 数据来源 | 文件或产物类型 |
缺字段时写 未提供 / 未采集,不要脑补。
2. 关键数据 TOP5
使用短表格,固定列:
| 排名 | 指标/对象 | 数值/现象 | 意义 | 数据来源 |
|---|
填充规则:
- 只放最值得看的关键数据,不要变成全量指标列表
- device 场景优先来自:
OpBasicInfo.csv、PipeUtilization.csv、ArithmeticUtilization.csv、Memory.csv、L2Cache.csv、ResourceConflictRatio.csv - simulator 场景优先来自:
trace.json、core*_code_exe.csv、core*_instr_exe.csv、PMSampling
3. 核心瓶颈 TOP5
使用短表格,固定列:
| 排名 | 瓶颈结论 | 判断依据 | 影响 | 数据来源 |
|---|
填充规则:
- 必须把“结论”和“依据”分开
- 没有足够证据时写
待确认,不要把猜测写成确定事实 - 不要直接复述经验案例;只有当前现象匹配时,才能把经验作为辅助说明
4. 优化建议 TOP5
使用短表格,固定列:
| 排名 | 建议 | 对应瓶颈 | 预期收益/目的 | 前提/来源 |
|---|
填充规则:
- 建议必须与“核心瓶颈 TOP5”逐项关联
- 不要给与当前模式不兼容的建议
- 纯命令指导、环境准备或尚未验证的假设,不应冒充优化建议
报告模板的模式差异处理
固定模板只有一套,但字段解释按 mode 变化:
- simulator 的
trace.json= 指令流水图依据 - device 的
trace.json= 通算 / 通信相关流水图依据 PMSampling只应出现在支持的 simulator 场景TimelineDetail只应出现在支持的 device 场景
统一原则:
- 标题和表格列固定
- 数据来源允许按 mode 变化
- 不适用项明确写
N/A或不适用当前模式
高频踩坑(优先提醒用户)
--kernel-name只支持 application 模式;对--config/--export无效。- simulator 的
--config场景应通过LD_LIBRARY_PATH指定仿真器;--soc-version在该场景不生效。 --export仅用于 simulator,且目录中应包含 dump 数据;如需代码行映射,还应包含aicore_binary.o。TimelineDetail是 device 模式能力,在 simulator 模式下无效。--replay-mode=range必须配合--mstx=on。--replay-mode=range不能与TimelineDetail/Source/MemoryDetail同时使用。- simulator 默认指标是
PipeUtilization + ResourceConflictRatio;PMSampling默认不开启。 PMSampling解析全部核,--core-id对它不生效。- 输出、配置、导出目录会做权限与软链接检查;权限不对时工具会直接报错。
- device 模式里的
--dump/--core-id是与特定能力和芯片绑定的特殊行为,不要当成 simulator 通用参数理解。
模式与输入形态矩阵
| 模式 | 输入形态 | 是否支持 | 备注 |
|---|---|---|---|
| device | application |
Y | 最常见;支持 --kernel-name、--launch-skip-before-match |
| device | config |
Y | 基于 JSON + .o,--kernel-name 不生效 |
| device | export |
N | 仅 simulator 支持 |
| simulator | application |
Y | 可用 --soc-version 或 LD_LIBRARY_PATH 指定仿真器 |
| simulator | config |
Y | 应使用 LD_LIBRARY_PATH;--soc-version 不生效 |
| simulator | export |
Y | 只解析已有 dump,不重新仿真 |
常用命令模板
上板调优(application)
# 单算子默认采集
msprof op --output=./output_npu ./execute_add_op
# 采集全量基础指标 + Roofline
msprof op --aic-metrics=Roofline,Default --output=./output_npu ./execute_add_op
# 多算子:采集前 10 个匹配 Add/Sub 的算子
msprof op --launch-count=10 --kernel-name="Add|Sub" --output=./output_npu ./test
上板调优(config)
msprof op --config=./add_test.json --aic-metrics=Default --output=./output_npu
仿真调优(application)
# 方式 1:显式指定仿真器
msprof op simulator --soc-version=Ascend910B4 --output=./output_sim ./execute_add_op
# 方式 2:通过环境变量指定仿真器
export LD_LIBRARY_PATH=${INSTALL_DIR}/tools/simulator/Ascend910B4/lib:$LD_LIBRARY_PATH
msprof op simulator --output=./output_sim ./execute_add_op
仿真调优(config)
export LD_LIBRARY_PATH=${INSTALL_DIR}/tools/simulator/Ascend910B4/lib:$LD_LIBRARY_PATH
msprof op simulator --config=./add_test.json --output=./output_sim
仿真调优(export)
msprof op simulator --soc-version=Ascend910B4 --export=./dump_dir --output=./output_sim
参数边界速查
适用于两个模式,但要看输入形态
| 参数 | 说明 | 备注 |
|---|---|---|
--output |
输出目录 | 默认当前目录,受权限与软链接限制 |
--launch-count |
最大采集算子数量 | 默认 1,范围 [1,5000] |
--mstx |
使能 mstx | on/off |
--mstx-include |
只使能指定 mstx message | 必须配合 --mstx=on |
--kernel-name |
匹配目标算子名 | 仅 application 模式有效 |
device 模式
| 参数 | 说明 |
|---|---|
--aic-metrics |
选择上板指标能力 |
--replay-mode |
kernel / application / range |
--launch-skip-before-match |
跳过前 N 个算子不采集 |
--kill |
采集完成后自动停止程序 |
--warm-up |
预热次数,默认 5 |
simulator 模式
| 参数 | 说明 |
|---|---|
--soc-version |
application/export 场景可用;config 下不生效 |
--export |
解析已有 dump |
--timeout |
超时后强制终止仿真并进入解析 |
--core-id |
只解析指定核,范围 [0,49] |
--dump |
是否保留 dump;存在芯片和场景限制 |
指标与产物速查
上板 --aic-metrics
| 指标 | 作用 | 常见产物 | 备注 |
|---|---|---|---|
Default |
基础 CSV 指标 | 多个 CSV | 默认基础采集能力 |
Roofline |
Roofline 瓶颈分析 | visualize_data.bin |
与 Default 绑定 |
Occupancy |
核间负载分析 | visualize_data.bin |
仅部分芯片支持 |
Source |
代码热点图 | visualize_data.bin |
通常需 -g 编译 |
MemoryDetail |
L2 / 内存细节增强 | CSV + visualize_data.bin |
与 Default 绑定 |
TimelineDetail |
指令流水 + 上板热点图增强 | visualize_data.bin |
device-only,且限制较多 |
PipeTimeline |
Pipe 流水图 | trace.json + visualize_data.bin |
仅Ascend 950PR&950DT系列产品 |
KernelScale |
指定代码段采集 | CSV / 可视化 | 依赖 Kernel 侧插桩 API |
PcSampling |
SIMT stall 信息 | visualize_data.bin |
仅Ascend 950PR&950DT系列产品 |
BasicInfo |
只采集基础信息 | OpBasicInfo.csv |
轻量模式 |
说明:
- 如果用户既要
TimelineDetail又要常规 CSV / 计算内存热力图,通常需要显式带上Default。TimelineDetail/Source/MemoryDetail与range replay不能共存。
仿真 --aic-metrics
| 指标 | 作用 | 默认情况 |
|---|---|---|
PipeUtilization |
指令流水 | 默认开启 |
ResourceConflictRatio |
同步事件 / 冲突细节 | 默认开启 |
PMSampling |
内存通路吞吐率波形图 | 默认关闭 |
输出产物结构
上板模式(单算子常见结构)
OPPROF_{timestamp}_XXX/
├── dump/
├── OpBasicInfo.csv
├── PipeUtilization.csv
├── ArithmeticUtilization.csv
├── Memory.csv
├── MemoryL0.csv
├── MemoryUB.csv
├── L2Cache.csv
├── ResourceConflictRatio.csv
├── visualize_data.bin
└── trace.json # 仅在支持的通算/特定视图场景下生成
仿真模式(单算子常见结构)
OPPROF_{timestamp}_XXX/
├── dump/
└── simulator/
├── core0.veccore0/
│ ├── core0.veccore0_code_exe.csv
│ ├── core0.veccore0_instr_exe.csv
│ └── trace.json
├── core0.veccore1/
│ ├── core0.veccore1_code_exe.csv
│ ├── core0.veccore1_instr_exe.csv
│ └── trace.json
├── ...
├── visualize_data.bin
└── trace.json # 全核汇总流水图
多算子补充说明
- device 多算子输出通常会按
OpName/<order>/...组织,单算子时工具可能自动平铺整理。 - simulator 多算子输出会按
OpName/<order>/dump|simulator组织,且 simulator 目录中的 CSV 常带时间戳后缀。
如何看结果
- CSV 文件:适合快速查总耗时、带宽、利用率、冲突占比。
visualize_data.bin:用 MindStudio Insight 查看热力图、Roofline、热点图、流水图等。trace.json:- device:主要用于通算/通信相关流水图;
- simulator:主要用于指令流水图(每核与全核汇总)。
- 如果用户只说“看 trace.json”:必须先判断该文件来自 device 还是 simulator,再决定解释方式。
推荐分析流程
上板
- 用
Default跑通一版,先看OpBasicInfo.csv和PipeUtilization.csv。 - 开
Roofline判断 Compute Bound / Memory Bound / Latency Bound。 - 若偏内存:继续看
Memory.csv/MemoryDetail。 - 若偏计算:继续看
ArithmeticUtilization.csv、必要时看Source。 - 若怀疑核间不均衡:开
Occupancy。 - 若是通算融合算子:再看
trace.json。
仿真
- 先用默认指标(
PipeUtilization + ResourceConflictRatio)拿到基本流水。 - 看 MTE 与 VECTOR/CUBE 是否并行,是否有明显 bubble。
- 看
SET_FLAG/WAIT_FLAG是否造成不必要等待。 - 如需内存通路波形,再显式开
PMSampling。 - 数据太大时优先用
--timeout,热点集中到少数核时再用--core-id精细化。
结果解读提醒
Roofline与 pipeline 占比的推断是分析线索,不是唯一真相;需要结合 CSV/热点图交叉验证。- simulator 提供的指令级视角更细,但它不等同于真实硬件最终耗时。
- 上板结果更接近真实运行瓶颈,但指令级细节通常不如 simulator 丰富。
深度参考
经验沉淀
- 经验案例:部分工程的仿真拉起需要仿真兼容构建产物 - 适用于
signal 6 / Bad address一类仿真拉起故障的经验排查