# External Mindstudio Cluster Fast Slow Rank Detector

> 专门用于 Ascend 集群 Profiling 性能数据的“快慢卡”诊断专家技能。当用户提供【集群性能数据目录/路径】并要求分析【快慢卡】、【慢节点】、【负载不均衡】或【集群瓶颈】时，必须触发此技能。该技能会自动接收集群路径，调度相关工具输出快慢卡的宏观定性与微观根因（如 Host 下发瓶颈、算子计算劣化）。

- Skill: `ascend-ai-coding/external-mindstudio-cluster-fast-slow-rank-detector` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ascend-ai-coding/external-mindstudio-cluster-fast-slow-rank-detector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ascend-ai-coding/external-mindstudio-cluster-fast-slow-rank-detector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: UNKNOWN
- Author: ascend-ai-coding (https://skillmd.com/u/ascend-ai-coding)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ascend-ai-coding/external-mindstudio-cluster-fast-slow-rank-detector

---


# 集群快慢卡诊断

## 1. 技能目标
在 Ascend 多卡/集群场景下，利用 Advisor 工具结合专家规则，自动识别因计算、通信或 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. 硬性约束 (MUST DO)

1. **执行已有脚本，严禁造轮子**：微观下钻环节（Step 3）**必须且只能**通过在终端执行 `scripts/` 下的对比脚本获取差异数据。严禁在未执行脚本前自行读取 CSV/DB 进行 Diff 分析。
2. **禁止 Trace 分析**：本技能流程不包含 Timeline 级分析，Step 4 输出报告后立即结束，禁止主动读取 `trace_view.json`。

## 4. 标准操作流程 (SOP)

1. **宏观体检**：强制调用 `msprof-analyze-advisor` 工具输入集群路径，获取总体耗时极差与“慢卡分析”矩阵。
2. **瓶颈定性**：对照【先验知识库】，判定核心瓶颈属于 `Host下发慢`、`计算慢` 还是 `纯通信慢`，并锁定真正的“慢卡 RankID”。
3. **微观下钻**：根据瓶颈类型，在终端直接执行下方对应的对比脚本（计算慢用 OP 脚本，下发慢用 API 脚本）。仅当路径自动发现失败报错时，才可通过补充 `--slow-path` 参数重试。
4. **输出报告**：按以下结构输出最终回复：
   * **诊断结论**：瓶颈类型及真正慢卡的 RankID。
   * **宏观证据**：引用 Advisor 报告中的极差数据（如 Free Time 对比）。
   * **微观根因**：结合脚本输出的 Top 差异数据（特定 API 或算子的耗时比对），解释物理原因。
   * **优化建议**：给出针对性建议（如绑核、切分策略、排查算子Shape差异等）。

## 5. 脚本调用手册

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

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

# 【下发类瓶颈】调用 API 对比脚本
python <本技能目录>/scripts/compare_api_stats.py <集群数据根目录> <慢卡RankID> <快卡RankID> [--top N]
```
参数说明：
* cluster_pah: 集群数据根目录（包含 profiler_info_{rank}.json）。 
* slow_rank / fast_rank: 慢卡与快卡（基准）的 Rank ID。 
* --top N: （可选）输出差异最大的前 N 条，默认 20。 
* --slow-path / --fast-path: （可选）当集群自动发现机制报错时，用于手动指定慢/快卡的 *.csv 或 *.db 绝对路径。 
* --json: （可选）以 JSON 格式结构化输出。