集群快慢卡诊断

1. 技能目标

在 Ascend 多卡/集群场景下，利用msprof-analyze命令工具结合专家规则，自动识别因计算、通信或 Host 下发导致的性能瓶颈卡（慢卡），并下钻定位微观根因。

2. 诊断先验知识库 (Expert Rules)

禁止仅凭单项指标字面意思下结论，必须严格遵守以下华为官方诊断逻辑：

• 【Host 下发瓶颈 (伪快卡)】
  • 现象：某卡（Rank X）的 Free Time 极长（占比 > 10% 或远超均值），且 Compute 和 Communication 时间异常偏短。
  • 定性：Rank X 绝非快卡，而是导致集群阻塞的“慢卡”。 CPU 下发慢导致其 NPU 饿死（产生巨大 Free Time）。当它终于发起通信时，其他卡已等待多时（其他卡 Wait 长），故其通信瞬间完成。
  • 动作：调用 scripts/compare_api_stats.py，重点观察 launch、aclrtSynchronizeDevice 等下发/同步 API 的耗时与间隙差异。
• 【纯计算快慢卡】
  • 现象：各卡 Free Time 普遍较短且均匀，但某卡 Compute Time 显著大于均值。
  • 定性：计算型慢卡。若单算子调用次数 (count) 不同，为负载切分不均；若次数相同但平均耗时 (avg_time) 激增，为算子硬件劣化或动态 Shape 导致。
  • 动作：调用 scripts/compare_op_stats.py 对比算子执行差异。
• 【通信/慢链路瓶颈】
  • 现象：各卡通信带宽远低于理论值（如 SDMA < 2GB/s）。
  • 定性：通常为小包通信（ZeRO3 切分过细）、SDMA 地址未对齐或硬件问题。

3. 标准操作流程 (SOP)

请严格按照以下流程执行：

1. 输入数据类型判断

先判断用户提供的路径或文件属于哪一类，并把后续分析所需证据统一整理为“集群级宏观证据”和“Rank 级明细证据”两类：

（1）明确当前输入数据的类型

• 路径下若存在Profiling数据：
  • 共识别到多少个 Rank；
  • Profilng数据的类型是DB or Text，若路径下存在ascend_pytorch_profiler_{rank_id}.db文件，则为 DB 类型数据，否则为 Text；
  • 各 Rank 的 profiling 文件夹是否齐全。
• 路径下是否已存在 msprof-analyze 的分析结果目录cluster_analysis_output：若存在，输出已包含哪些内容
• 告知用户，当前数据类型、Rank数量等信息

（2）路由后续操作

• 用户给的输入数据是 text 格式：请参考 skills/ascend-msprof-analyze-cli SKILL 的能力二：专家建议分析 (Advisor) 部分进行分析，然后直接进入流程 3 基于证据做快慢卡判定
• 用户给的输入数据是 db 格式，判断是否已经存在cluster_analysis_output 结果文件夹：
  • 若存在，检查是否包含 cluster_time_summary、compute_op_sum、hccl_sum、slow_rank、slow_link、cann_api_sum 等结果。记录缺失项，直接进入流程 2 调用 msprof-analyze 集群分析能力补齐；如果结果已完整，直接进入流程 3 基于证据做快慢卡判定
  • 不存在，直接进入流程 2 调用 msprof-analyze 集群分析能力
• 用户输入只存在 cluster_analysis_output 结果文件夹：直接进入流程 3 基于证据做快慢卡判定

2. 调用 msprof-analyze 集群分析能力 流程 2 只负责生成分析结果，不负责直接下结论。 必须调用 msprof-analyze 执行集群分析。请参考 skills/ascend-msprof-analyze-cli SKILL 中 “集群综合分析 (Cluster)” 的部分 要求不是只跑 all，而是将 README 中与集群分析相关的 -m 能力逐项跑全，至少覆盖下列能力：

分析能力	介绍
all	组合能力，可作为补充，但不能替代逐项执行。
cluster_time_summary	提供集群训练过程中迭代耗时拆解，作为判断 Free/Compute/Communication/Wait 异常的宏观入口。
compute_op_sum	汇总 device 侧计算类算子，用于定位计算型慢卡和负载切分不均。
hccl_sum	汇总通信类算子，用于定位通信型慢卡、慢链路和通信带宽异常。
slow_rank	展示各 Rank 的快慢卡影响次数和慢卡候选原因。
slow_link	分析集群异常耗时链路，用于辅助识别慢链路或通信瓶颈。
cann_api_sum	汇总 CANN 层 API，用于定位 Host 下发、同步点和 launch 间隙问题。

命令示例：

msprof-analyze -m cluster_time_summary -d ./cluster_data -o ./output/cluster_time_summary

如环境允许，优先为每个 -m 能力使用独立输出目录，避免不同分析结果互相覆盖。若某项能力执行失败，必须记录失败命令、错误摘要和缺失影响，后续结论中不得把该项当成已验证证据。

3. 基于证据做快慢卡判定

流程 3 只在证据集可用后执行。agent 不能只引用单项指标直接给结论，必须综合流程 1/2 得到的宏观证据和必要的 Rank 级明细证据，明确回答以下问题：

（1）是否存在快慢卡现象； （2）真正的慢卡 Rank ID 是谁，以及候选快卡 Rank ID 是谁； （3）问题属于哪一类：

• Host 下发慢 / 调度瓶颈；
• 计算型慢卡；
• 通信型慢卡 / 慢链路；
• 负载不均衡；
• 多种问题叠加；
• 证据不足，暂不能判定。

（4）判定依据是什么：至少引用 cluster_time_summary、slow_rank 或 slow_link 中的一类宏观证据；若涉及计算型或 Host 下发瓶颈，还应继续调用流程 4 中的对比脚本，用 compare_op_stats.py 或 compare_api_stats.py 给出微观证据。

4. 快卡vs慢卡比对

对比脚本统一存放在本技能目录的 scripts/ 文件夹中，支持自动发现集群目录或手动指定文件（优先 CSV，次选 DB）。

核心命令模板：

# 【计算类瓶颈】调用算子对比脚本（将 <本技能目录> 替换为 get_skill 返回中的路径）
python <本技能目录>/scripts/compare_op_stats.py <集群数据根目录> <慢卡RankID> <快卡RankID> [--top N]

# 【下发类瓶颈】调用 API 对比脚本
python <本技能目录>/scripts/compare_api_stats.py <集群数据根目录> <慢卡RankID> <快卡RankID> [--top N]

参数说明：

• cluster_path: 集群数据根目录（包含 profiler_info_{rank}.json）。
• slow_rank / fast_rank: 慢卡与快卡（基准）的 Rank ID。
• --top N: （可选）输出差异最大的前 N 条，默认 20。
• --slow-path / --fast-path: （可选）当集群自动发现机制报错时，用于手动指定慢/快卡的 *.csv 或 *.db 绝对路径。
• --json: （可选）以 JSON 格式结构化输出。

5. 对慢卡目录执行 advisor，并给出调优建议（可选）

当流程3已锁定慢卡 Rank ID 后，必须进入该慢卡对应的 profiling 文件夹，再执行：

msprof-analyze advisor all -d <slow-rank-profiling-dir>

然后基于 advisor 输出，给出该慢卡的针对性调优建议。建议内容必须与瓶颈类型对应，例如：

• Host 下发慢：排查下发线程绑核、同步点、launch 间隙、CPU 饥饿、数据准备阻塞；
• 计算型慢卡：排查算子 count 不一致、动态 shape、算子劣化、融合缺失、AICore 利用率问题；
• 通信型慢卡：排查小包通信、并行切分策略、链路带宽、通信域配置、SDMA/HCCL 异常；
• 负载不均衡：排查数据切分、专家负载、pipeline stage 分配、rank 侧 workload 偏斜。

若 advisor 输出与流程3的集群判断不一致，必须显式指出这一点，并说明以哪类证据为主、为什么。