メニュー
MindStudio Profiler Analyze（msprof-analyze）是面向 AI 训练与推理场景的性能分析工具，基于采集得到的 profiling 数据进行统计、比对和诊断，帮助定位计算、通信、调度及集群场景下的性能瓶颈。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
面向 Ascend PyTorch Profiler / msprof DB（如 ascend_pytorch_profiler*.db、msprof_*.db）的 SQL 分析技能。将自然语言问题（算子耗时、通信、下发、调度、schema/table 查询）转为安全可执行 SQL，并按需从官方文档提取表结构详情。
计算算子（如 matmul/GEMM/FlashAttention）的 MFU（Machine FLOP Utilization），并给出清晰的公式和推导过程。支持两类输入：用户手填维度，或从 Ascend PyTorch Profiler 落盘（kernel_details.csv / *.db）批量提取 shape+耗时后聚合 MFU（含转置安全的 M/N/K 推导、cube_utilization 与 MFU 的区别、算子达成率 vs 端到端 step MFU 两种口径）。
为一次性能 profiling 数据计算 0-100 的性能健康度评分 (PHS, Performance Health Score) 与等级 (S/A/B+/B/C/D)，作为报告"结论速览"首行的仪表盘指标。复合公式涵盖计算利用率、通信效率、调度效率、内存带宽利用率四个子项；按工作负载场景（大模型多卡训练 / 单卡训练或推理 / 单算子调优 / 集群慢卡）自动切换权重；子项缺数据时按比例归一化剩余权重。另含一个独立诊断指标"显存容量利用率（HBM 占用率，从 memory_record.csv / npu_module_mem.csv / NPU_MEM 表提取，不计入 PHS）"，用于回答显存占用 / OOM 风险类问题。
面向 Ascend Profiling timeline（trace_view.json / msprof_*.json 及 db 中带 startNs/endNs 的区间表）的"泳道时序结构"分析技能。专门补齐聚合统计型 skill 无法给出的几何派生指标——关键路径（最长链路）、计算-通信重叠率、算子利用率（AI Core time-based）、泳道空挡比例、PP 流水线 bubble 率、step 间抖动、通信抖动（逐 step 通信 CV）、per-step 周期归一，以及推理 prefill/decode 时序拆解。
基于 msprof op 工具的端到端 Ascend NPU 算子性能调优技能。当用户提供算子源码目录，并要求使用 msprof op 完成从性能采集、瓶颈分析、代码优化到优化效果验证的完整闭环时，必须使用此 skill。典型触发词包括"端到端调优"、"代码优化"、"msprof op 调优"、"完整调优"、"性能优化闭环"、"端到端"、"调优全流程"。此 skill 自动执行：编译运行 → msprof op 上板/仿真性能采集 → 瓶颈诊断 → 代码优化 → 重新采集 → 优化前后性能对比。注意：此 skill 专门使用 msprof op 工具进行性能采集和分析，覆盖 msot-msopprof-operator-profiler（纯分析），并额外包含编译运行和性能采集的自动化流程。
专门用于 Ascend 集群 Profiling 性能数据的"快慢卡"诊断专家技能。当用户提供【集群性能数据目录/路径】并要求分析【快慢卡】、【慢节点】、【负载不均衡】或【集群瓶颈】时，必须触发此技能。该技能会自动接收集群路径，调度相关工具输出快慢卡的宏观定性与微观根因（如 Host 下发瓶颈、算子计算劣化）。
| name | msprof-analyze-cli |
| description | MindStudio Profiler Analyze（msprof-analyze）是面向 AI 训练与推理场景的性能分析工具，基于采集得到的 profiling 数据进行统计、比对和诊断，帮助定位计算、通信、调度及集群场景下的性能瓶颈。 |
目前提供两个功能，根据用户需求自动选择对应工具：
| 能力 | 工具命令 | 侧重点 |
|---|---|---|
| 集群分析 (cluster analyse) | msprof-analyze -m <mode> | 涵盖集群多维信息汇总、拆解对比、通信瓶颈定位和下发问题分析等专题。 |
| 专家建议 (advisor) | msprof-analyze advisor <subcommand> | 基于性能数据自动识别计算、调度、通信等潜在问题，并输出优化建议。 |
⚠️ 重要：在开始分析前，必须先根据以下规则确定使用哪个功能。
| 条件 | 优先使用的分析能力 | 原因 |
|---|---|---|
| 卡数 ≥ 64 或数据量很大（db大于1G） | 集群分析 | 集群分析专门优化了大数据量场景，能快速汇总数据 |
| 数据格式为 db | 集群分析 | 集群分析仅支持 db 格式 |
| 数据格式为 text (json/csv) | 专家建议 | 专家建议支持 text 和 db 格式 |
| 需要分析慢卡/慢链路原因 | 集群分析后，再用专家建议 | 先定位慢卡，再用专家建议深入诊断 |
| 需要算子优化建议 | 专家建议 | 专家建议输出详细的调优建议 |
| 单卡数据一般以'ascend_pt'或者'ascend_ms'结尾 | 专家建议 | 直接使用专家建议进行诊断 |
用户提出分析需求
│
▼
┌─────────────────────────────┐
│ 数据量评估：卡数、数据规模 │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 数据格式判断：db 还是 text？ │
└─────────────────────────────┘
│
├──────────────────────────────┐
▼ ▼
【db格式且为多卡数据】 【text格式或者单卡数据】
│ │
▼ ▼
优先集群分析 只能专家建议
│ (跳过第3步)
▼
┌─────────────────────────────┐
│ 集群分析是否找到慢卡？ │
└─────────────────────────────┘
│
├─────────────┬─────────────┐
▼ ▼ ▼
是慢卡 不是慢卡 无瓶颈
│ │ │
▼ │ ▼
对该慢卡用 分析其他问题 结论输出
专家建议深入
| 用户需求场景 | 推荐能力 | 理由 |
|---|---|---|
| "分析这个 16 卡集群的慢卡问题" | 集群分析 → 专家建议 | 先定位慢卡，再深入诊断 |
| "这个单卡的数据有算子执行慢" | 专家建议 | 单卡场景专家建议更全面 |
| "帮我看看这个 profiling 数据" | 先判断数据格式 | 格式决定能力选择 |
| "通信带宽低是什么原因" | 集群分析 | 通信矩阵分析是集群分析强项 |
| "这个算子为什么慢" | 专家建议 | 算子问题诊断是专家建议强项 |
| "数据格式是 csv 的" | 专家建议 | 集群分析仅支持 db |
在 Ascend 多卡/集群场景下，利用 msprof-analyze 的 -m 参数指定分析能力，对集群训练数据进行综合分析。用户只需说明要分析什么，系统自动选择对应的 -m 参数执行分析。
| 分析能力 | 介绍 |
|---|---|
| cluster_time_summary | 提供集群训练过程中迭代耗时的拆解，帮助用户找到性能瓶颈。 |
| compute_op_sum | device侧运行的计算类算子汇总。 |
| freq_analysis | 识别aicore是否存在空闲（频率为800MHz）、异常（频率不为1800MHz或800MHz）的情况并给出分析结果。 |
| ep_load_balance | moe负载信息汇总分析。 |
| communication_time_sum | 集群场景通信时间和带宽汇总分析。 |
| hccl_sum | 通信类算子信息汇总。 |
| slow_rank | 根据当前的快慢卡统计算法，展示各个rank得出的快慢卡影响次数，识别慢卡出现的原因。 |
| cann_api_sum | CANN层API的汇总。 |
| free_analysis | 提供对Device侧大块空闲时间的自动分析能力，能够识别空闲时间产生的原因，帮助用户定位性能问题。 |
| all | 同时解析通信矩阵communication_matrix和通信耗时数据communication_time。 |
# 【集群综合分析】
msprof-analyze -m <mode> -d <cluster_data_path> [-o <output_path>] [--force] --agent
命令示例：
# -o 必须指向被分析数据目录之外的新目录，禁止省略 -o（省略会污染 ./cluster_data 原始数据目录）
msprof-analyze -m cluster_time_summary -d ./cluster_data -o ./cluster_data_profiling_analysis_20260521/cluster_time --agent
msprof-analyze -m free_analysis -d ./cluster_data -o ./cluster_data_profiling_analysis_20260521/free_analysis --agent
msprof-analyze -d ./cluster_data -o ./cluster_data_profiling_analysis_20260521/all --agent # 默认为all
⚠️ 集群分析 (Cluster) 专用诊断规则 禁止仅凭单项指标字面意思下结论，必须严格遵守以下华为官方诊断逻辑：
Free Time 极长（占比 > 10% 或远超均值），且 Compute 和 Communication 时间异常偏短。free_analysis 分析空闲时间原因，使用 freq_analysis 检查频率是否异常低。Free Time 普遍较短且均匀，但某卡 Compute Time 显著大于均值。Bandwidth(GB/s) 显著低于同类型链路的均值。communication_matrix_sum 查看各链路带宽。freq_analysis 检测频率异常。communication_bottleneck 分析是 Host 侧下发慢还是 Device 侧计算慢导致通信等待。msprof-analyze 命令进行集群分析。⚠️ 集群分析 (Cluster) 专用流程
确认分析模式：
-m 参数值（参见第2节映射表）。all 模式。执行分析命令：
msprof-analyze -m <mode> -d <cluster_data> -o <output_path> [--force] --agent-o，且输出路径不能落在被分析的 profiling 数据目录内（避免污染原始数据）。
./<标识词>_profiling_analysis_YYYYMMDD/msprof_analyze/<mode>/（命名规则见规则 3）-m 模式建议各自独立子目录，避免覆盖profiling-workflow/SKILL.md 规则 3。读取输出结果：
数据解读与瓶颈定位：
输出报告：MUST 按 profiling-workflow/SKILL.md 规则 1 的 5 章骨架输出，不再使用本 skill 历史的"分析概要/详细数据/瓶颈定位/优化建议"四段结构。本步骤产物落位：
| msprof-analyze 输出 | 5 章骨架对应位置 |
|---|---|
| 头号瓶颈定性 + 预估收益上限 | 第 1 章 结论速览 |
| 各 Rank/链路问题表（含预期收益、修改难度） | 第 2 章 行动清单 主表 |
| 每个问题的证据（具体数值/占比/Rank ID）+ 修复操作（含改动位置）+ 问题修改完成的验证方式 | 第 3 章 问题详情 各小节 |
| 已验证正常的项（如各 Rank Compute 极差 < 5%） | 第 4 章 已确认无问题 |
使用的分析模式、执行的完整命令、-o 输出路径、advisor 状态 | 第 5 章 数据与方法（附录） |
suggestion 字段的内容并入第 2 章行动清单 / 第 3 章修复操作，不要单独成段export_type=["db"]。⚠️ Advisor 默认必跑：advisor 是每次 Profiling 分析的默认必跑步骤。无论单卡还是多卡（集群场景在集群分析定位慢卡后），都必须对相应数据调用
msprof-analyze advisor并将建议并入报告。仅当数据格式/工具不支持或命令执行失败时才可不跑，并在报告第 5 章"Advisor 状态"如实写明原因（见profiling-workflow/SKILL.md规则 2），禁止无理由跳过。
基于 Ascend PyTorch Profiler 或 MindSpore Profiler 采集的性能数据，使用 msprof-analyze advisor 功能进行自动分析，并输出性能调优建议。
使用 msprof-analyze advisor <subcommand> 命令格式，支持三种分析模式，默认使用all：
| 子命令 | 说明 | 包含功能 |
|---|---|---|
all | 总体性能瓶颈 | 全部功能（计算 + 通信 + 调度） |
computation | 计算瓶颈 | computation + Kernel compare |
schedule | 调度瓶颈 | schedule + API compare |
| 维度 | 功能 | 说明 |
|---|---|---|
| overall | Overall Summary | 计算、通信、空闲等维度拆解 |
| overall | Environment Variable Issues | 环境变量设置推荐 |
| overall | slow rank | 慢卡识别 |
| overall | slow link | 慢链路识别 |
| computation | AICPU Issues | AI CPU 调优 |
| computation | Operator Dynamic Shape Issues | 识别动态Shape算子 |
| computation | AI Core Performance Analysis | MatMul、FlashAttentionScore 等算子分析 |
| computation | Block Dim Issues | Block Dim 算子调优 |
| computation | Operator No Bound Issues | 算子瓶颈分析 |
| computation | Fusion Issues | 融合算子图调优 |
| computation | AI Core Frequency Issues | AI Core 算子降频分析 |
| communication | Packet Analysis | 通信小包检测 |
| communication | Bandwidth Contention Analysis | 通信计算带宽抢占检测 |
| communication | Communication Retransmission Analysis | 通信重传检测 |
| communication | Byte Alignment Analysis | 通信算子字节对齐检测 |
| schedule | Affinity API Issues | 亲和API替换调优 |
| schedule | Operator Dispatch Issues | 识别算子下发问题(路径3/路径5) |
| schedule | SyncBatchNorm Issues | BatchNorm同步检测 |
| schedule | Synchronize Stream Issues | 流同步检测 |
| schedule | GC Analysis | 垃圾回收事件检测 |
| schedule | Fusible Operator Analysis | 检测 Host/MTE 瓶颈算子序列 |
| dataloader | Slow Dataloader Issues | 异常 dataloader 检测 |
| memory | Memory Operator Issues | 识别异常的内存申请释放操作 |
| comparison | Kernel compare | 标杆性能数据 Kernel 对比 |
| comparison | API compare | 标杆性能数据 API 对比 |
# 【总体性能瓶颈】
msprof-analyze advisor <subcommand> -d <profiling_path> [-o <output_path>] [-bp <benchmark_path>] [--force] --agent
命令示例：
# -o 必须指向被分析数据目录之外的新目录，禁止省略 -o
# 单卡场景
msprof-analyze advisor all -d ./profiling_data -o ./profiling_data_profiling_analysis_20260521/advisor --force --agent
# 集群场景
msprof-analyze advisor all -d ./cluster_profiling -o ./cluster_profiling_profiling_analysis_20260521/advisor --force --agent
| 场景 | 路径要求 |
|---|---|
| 单卡 | 指定到 *_ascend_pt 或 *_ascend_ms 目录 |
| 多卡/集群 | 指定到 *_ascend_pt 或 *_ascend_ms 的父目录 |