mocchibird/ascend-agent-kit/ops-profiling

上板性能采集与调优

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

本技能基于 msprof 工具链，统一入口为两个脚本：

• `msprof_profile_run.sh` — 性能采集（标准采集 / 对比测试 / 批量并行）
• `msprof_perf_summary.py` — 结果解析（瓶颈分析 / 对比报告 / 批量汇总）

使用方式

1. 标准采集模式（深度瓶颈分析）

对单个可执行文件采集 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>

2. 对比测试模式（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

3. 批量并行模式（多 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

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

选用哪个工具：决策树

1. 用户显式指定工具

• 指定 msprof op / msopprof → 加载 `references/msprof-op-guide.md`
• 指定 msprof → 加载 `references/msprof-guide.md`

1. 用户未指定 — 探测环境：

• 仅 msopprof 可用 → `references/msprof-op-guide.md`
• 仅 msprof 可用 → `references/msprof-guide.md`
• 两者皆可用 → 须向用户确认或按项目约定选用其一
• 两者皆不可用 → 报错，提示检查 CANN / ASCEND_HOME 安装

参考资源

适用场景总览