| name | msprof-analyze-cli |
| description | MindStudio Profiler Analyze（msprof-analyze）是面向 AI 训练与推理场景的性能分析工具，基于采集得到的 profiling 数据进行统计、比对和诊断，帮助定位计算、通信、调度及集群场景下的性能瓶颈。 |
Ascend 性能数据综合分析
目前提供两个功能，根据用户需求自动选择对应工具：
| 能力 | 工具命令 | 侧重点 |
|---|
| 集群分析 (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 |
能力一：集群综合分析 (Cluster)
1.1 技能目标
在 Ascend 多卡/集群场景下，利用 msprof-analyze 的 -m 参数指定分析能力，对集群训练数据进行综合分析。用户只需说明要分析什么，系统自动选择对应的 -m 参数执行分析。
1.2 分析模式选择 (-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。 |
1.3 集群分析命令模板
msprof-analyze -m <mode> -d <cluster_data_path> [-o <output_path>] [--force] --agent
命令示例：
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
1.4. 诊断先验知识库 (Expert Rules)
⚠️ 集群分析 (Cluster) 专用诊断规则
禁止仅凭单项指标字面意思下结论，必须严格遵守以下华为官方诊断逻辑：
- 【Host 下发瓶颈 (伪快卡)】
- 现象：某卡（Rank X）的
Free Time 极长（占比 > 10% 或远超均值），且 Compute 和 Communication 时间异常偏短。
- 定性：Rank X 绝非快卡，而是导致集群阻塞的"慢卡"。 CPU 下发慢导致其 NPU 饿死（产生巨大 Free Time）。当它终于发起通信时，其他卡已等待多时（其他卡 Wait 长），故其通信瞬间完成。
- 验证：使用
free_analysis 分析空闲时间原因，使用 freq_analysis 检查频率是否异常低。
- 【纯计算快慢卡】
- 现象：各卡
Free Time 普遍较短且均匀，但某卡 Compute Time 显著大于均值。
- 定性：计算型慢卡。
- 【慢链路定位】
- 现象：某条链路的
Bandwidth(GB/s) 显著低于同类型链路的均值。
- 定性：根据 Transport Type 判断链路类型，LOCAL（片内拷贝，速度最高）> HCCS/PCIE（节点内片间拷贝）> RDMA（节点间拷贝，速度最低）。同类型链路带宽差异过大表示存在慢链路。
- 验证：使用
communication_matrix_sum 查看各链路带宽。
- 【频率异常】
- 现象：NPU 频率为 800MHz（空闲状态）或非 1800MHz/800MHz。
- 定性：频率异常可能表示算子等待或调度问题。
- 验证：使用
freq_analysis 检测频率异常。
- 【通信瓶颈】
- 现象：通信耗时占比高，快慢卡明显。
- 定性：使用
communication_bottleneck 分析是 Host 侧下发慢还是 Device 侧计算慢导致通信等待。
1.5. 硬性约束 (MUST DO)
- 必须使用 msprof-analyze 工具：使用
msprof-analyze 命令进行集群分析。
- 分析能力选择：根据提示词选择分析模式，如果根据提示词无法确定使用哪个分析能力，请让用户明确使用哪一个分析能力，不能自己尝试。
- 禁止孤立分析单卡：在集群场景下，严禁仅分析单个 Rank 数据而不进行多卡对比，最好只基于最后输出的文件进行分析。命令行失败后不能继续读取各个rank的数据。
- 必须分析时间占比：输出报告必须包含各 Rank 的计算、通信、内存拷贝、空闲时间占比分析（适用于 cluster_time_summary 模式）。
- 时间单位统一规范：所有原始数据（单位为微秒），报告中必须自动换算为毫秒（ms）展示，并明确标注单位。
1.6. 标准操作流程 (SOP)
⚠️ 集群分析 (Cluster) 专用流程
-
确认分析模式：
- 根据用户需求确定
-m 参数值（参见第2节映射表）。
- 若用户要求"完整分析"或"全部"或没有明确要求分析哪一方面，默认使用
all 模式。
-
执行分析命令：
- 执行命令：
msprof-analyze -m <mode> -d <cluster_data> -o <output_path> [--force] --agent
- MUST 显式传
-o，且输出路径不能落在被分析的 profiling 数据目录内（避免污染原始数据）。
- 推荐：项目根下新建带"被分析对象标识词 + 时间戳"的一级目录，如
./<标识词>_profiling_analysis_YYYYMMDD/msprof_analyze/<mode>/（命名规则见规则 3）
- 用户已指定输出根目录时听从用户；未指定时按上方推荐自行选位置
- 不同
-m 模式建议各自独立子目录，避免覆盖
- 详细落盘规则见
profiling-workflow/SKILL.md 规则 3。
-
读取输出结果：
- 根据命令运行返回的结果，读取生成的文件。
- 如果返回信息有 error，或者 JSON 里 message 为空，不用往下运行。提示让用户自己执行命令（去掉 --agent 参数），查看日志定位原因。
- 后续的分析可以结合json中的'suggestion'字段。
-
数据解读与瓶颈定位：
-
输出报告：MUST 按 profiling-workflow/SKILL.md 规则 1 的 5 章骨架输出，不再使用本 skill 历史的"分析概要/详细数据/瓶颈定位/优化建议"四段结构。本步骤产物落位：
| msprof-analyze 输出 | 5 章骨架对应位置 |
|---|
| 头号瓶颈定性 + 预估收益上限 | 第 1 章 结论速览 |
| 各 Rank/链路问题表（含预期收益、修改难度） | 第 2 章 行动清单 主表 |
| 每个问题的证据（具体数值/占比/Rank ID）+ 修复操作（含改动位置）+ 问题修改完成的验证方式 | 第 3 章 问题详情 各小节 |
| 已验证正常的项（如各 Rank Compute 极差 < 5%） | 第 4 章 已确认无问题 |
使用的分析模式、执行的完整命令、-o 输出路径、advisor 状态 | 第 5 章 数据与方法（附录） |
- 所有时间单位统一换算为 ms 后填入证据字段
- JSON
suggestion 字段的内容并入第 2 章行动清单 / 第 3 章修复操作，不要单独成段
- 命令行失败时，在第 5 章 "Advisor 状态" 写明失败原因，并在第 1 章结论速览注明"基于不完整数据"
1.7 集群分析故障
- 【时间单位混淆】
- 现象：输出的时间字段单位不明确。
- 规避：所有时间相关字段统一使用毫秒（ms），在报告中明确说明。
- 【profiler_level 设置过低】
- 现象：无法获取通信带宽和通信矩阵信息。
- 规避：profiler_level 建议设置为 Level1 或更高。
- 【db 类型数据缺失】
- 现象：Recipe 分析能力无法使用，报错缺少 db 文件。
- 规避：确认使用 db 类型数据，Ascend PyTorch Profiler 需指定
export_type=["db"]。
- 【Rank/Step ID 无效】
- 现象：指定 --rank_list 或 --step_id 后无输出或报错。
- 规避：确认配置的 ID 在实际数据中存在。
能力二：专家建议分析 (Advisor)
⚠️ Advisor 默认必跑：advisor 是每次 Profiling 分析的默认必跑步骤。无论单卡还是多卡（集群场景在集群分析定位慢卡后），都必须对相应数据调用 msprof-analyze advisor 并将建议并入报告。仅当数据格式/工具不支持或命令执行失败时才可不跑，并在报告第 5 章"Advisor 状态"如实写明原因（见 profiling-workflow/SKILL.md 规则 2），禁止无理由跳过。
2.1 技能目标
基于 Ascend PyTorch Profiler 或 MindSpore Profiler 采集的性能数据，使用 msprof-analyze advisor 功能进行自动分析，并输出性能调优建议。
2.2 分析模式
使用 msprof-analyze advisor <subcommand> 命令格式，支持三种分析模式，默认使用all：
| 子命令 | 说明 | 包含功能 |
|---|
all | 总体性能瓶颈 | 全部功能（计算 + 通信 + 调度） |
computation | 计算瓶颈 | computation + Kernel compare |
schedule | 调度瓶颈 | schedule + API compare |
2.3 功能详情表
| 维度 | 功能 | 说明 |
|---|
| 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 对比 |
2.4 Advisor 命令模板
msprof-analyze advisor <subcommand> -d <profiling_path> [-o <output_path>] [-bp <benchmark_path>] [--force] --agent
命令示例：
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
2.5 数据路径要求
| 场景 | 路径要求 |
|---|
| 单卡 | 指定到 *_ascend_pt 或 *_ascend_ms 目录 |
| 多卡/集群 | 指定到 *_ascend_pt 或 *_ascend_ms 的父目录 |
