Compare Analyzer

功能概述

本 Skill 支持两种工作模式：

• 模式一（直比）：用户提供两张 Prof 数据路径（GPU vs NPU、NPU vs NPU），自动检测/安装 msprof-analyze，调用 compare 生成 performance_comparison_result_*.xlsx，随后自动进入分析流程
• 模式二（xlsx 分析）：用户已持有 compare 输出的 performance_comparison_result_*.xlsx，直接解析分析

分析流程针对每个 Sheet 页提炼关键数据并进行分析，最终生成：

1. 中间件 JSON：包含所有 Sheet 的结构化分析结果
2. HTML 报告：可视化呈现性能比对分析结论（改善亮点/劣化风险双维度）
3. 中文 xlsx：将原版英文表头翻译为中文的 xlsx 文件（多 Sheet 标签页 + 同步 CSV）

使用方法

模式一：直接比对两张 Prof（自动调用 compare）

# 最简用法：默认开启全部比对能力（msprof-analyze 未安装时自动从 PyPI 安装）
python scripts/run_compare.py -d <待比对prof路径> -bp <基准prof路径>

# 指定输出目录
python scripts/run_compare.py -d ./ascend_pt -bp ./base_ascend_pt -o ./out

# 透传 compare 的额外参数（开关、step 过滤等）
python scripts/run_compare.py -d ./ascend_pt -bp ./gpu_trace.json --compare_args "--enable_operator_compare --use_input_shape"

# 只生成 compare xlsx，不生成分析报告
python scripts/run_compare.py -d ./ascend_pt -bp ./gpu_trace.json --compare_only

参数说明

参数	必选	说明
-d / --profiling_path	是	待比对 Prof 路径（通常是 NPU 数据 / 优化后数据 / 新版本数据）
-bp / --benchmark_profiling_path	是	基准 Prof 路径（通常是 GPU 数据 / 优化前数据 / 旧版本数据）
-o / --output	否	输出目录，默认 ./compare_output_<时间戳>
--compare_args	否	透传给 compare 的额外参数字符串，详见 references/compare_quickstart.md
--compare_only	否	只执行 compare 生成 xlsx，跳过后续分析
--skip_install	否	跳过 msprof-analyze 检测与自动安装

msprof-analyze 安装策略（run_compare.py 自动执行，按序尝试，任一成功即止）：

1. 已安装则直接使用（检测 msprof-analyze 命令或 msprof_analyze 包）
2. 未安装则在线安装：pip install msprof-analyze——msprof-analyze 官方发布于 PyPI（MindStudio 官方维护，Python ≥ 3.7，建议 3.9+），在线环境开箱即用

Prof 数据要求（详见 references/compare_quickstart.md）：

• NPU：指定到 *_ascend_pt（TorchNPU）或 *_ascend_ms（MindSpore）层级，目录内含 ASCEND_PROFILER_OUTPUT/（Text 或 Db 格式均可，同时存在时优先 Db）
• GPU：torch profiler 导出的目录（含 *.pt.trace.json）
• 建议只采集一个 step；多 step 时用 --compare_args "--base_step=1 --comparison_step=1" 固定

模式二：分析已有 compare 结果 xlsx

# 完整流程：解析 xlsx → 生成中间件 JSON → 生成 HTML 报告 → 生成中文 xlsx
python scripts/main_analyzer.py <xlsx_file_path> [-o <output_dir>]

# 示例
python scripts/main_analyzer.py ./performance_comparison_result_20250101.xlsx -o ./report_output

文件结构

ascend-prof-compare/
├── SKILL.md                          # Skill 说明文件
├── references/
│   ├── analysis_methodology.md       # 分析方法论（各 Sheet 指标含义与分析经验）
│   └── compare_quickstart.md         # compare 参数速查与 Prof 数据准备要求
└── scripts/
    ├── run_compare.py                # 直比编排：检测/安装 msprof-analyze → compare → 自动分析
    ├── main_analyzer.py              # 主调度脚本
    ├── html_generator.py             # HTML 报告生成器
    ├── csv_translator.py             # 中文翻译器（xlsx + CSV 同步输出）
    └── parsers/                      # 8 个解析器模块
        ├── __init__.py
        ├── common.py                 # 公共工具：safe_float、safe_int、get_sheet_data
        ├── overall_metrics.py        # 总体性能：维度拆解 + 改善/劣化双方向
        ├── operator.py               # 算子统计+明细（合并）
        ├── module.py                 # 模块统计+明细（合并）
        ├── memory.py                 # 内存统计+明细（合并）
        ├── kernel.py                 # Kernel比对+类型+负载均衡（合并）
        ├── communication.py          # 通信比对
        └── api_compare.py            # API比对

compare 常用参数速查（用于 --compare_args）

完整参数说明与数据准备要求见 references/compare_quickstart.md。

参数	用途
（不设任何开关）	默认开启全部比对能力（总体/算子/内存/通信/API/Kernel）
--enable_profiling_compare	只看总体性能（计算/通信/调度/E2E 拆解）
--enable_operator_compare	只看算子性能（较耗时，建议单 step 数据）
--enable_communication_compare	只看通信性能
--enable_memory_compare	只看内存差异（较耗时）
--enable_kernel_compare	只看 Kernel 比对（仅 NPU vs NPU）
--enable_api_compare	只看 Host 侧 API 比对
--base_step=N --comparison_step=N	固定比对某个 step（需成对配置）
--disable_details	隐藏明细 Sheet，只输出统计级比对（更快）
--use_input_shape	算子按输入 Shape 精准匹配
--use_kernel_type	Kernel 比对改用 op_statistic.csv，输出简化且更快
--gpu_flow_cat=<id>	GPU trace 的 CPU-kernel 连线标识（GPU Device Duration 全为 0 时使用）
--force	跳过文件属主 / 大小校验，强制执行

各 Sheet 分析思路

1. OverallMetrics（总体性能比对）

• 分析目标：定界性能方向（计算/通信/调度），区分改善和劣化
• 关键指标：E2E Time、Computing Time、Uncovered Communication Time、Free Time
• 分析方法：提取四大维度的基准/比对值和差异比率，分别识别改善最大维度和劣化最大维度，计算各维度对总变化的贡献占比
• 下钻分析：提取子类别（FA前向/反向、Conv、Matmul、Vector等），分改善/劣化两组排序
• 特殊检测：Not minimal profiling 警告

2. OperatorCompareStatistic（算子统计比对）

• 分析目标：定位劣化 TOP 算子
• 关键指标：Diff Duration(ms)、Diff Ratio
• 分析方法：按 Diff Duration 降序排列，提取 Top 10，计算累计劣化占比（集中度），判断劣化是否集中于少数算子

3. OperatorCompare（算子明细比对）

• 分析目标：查看 TOP 算子的 Kernel 级详情
• 关键指标：Device Duration(us)、Kernel Details、Input Shape
• 分析方法：关联统计页 TOP 算子，提取对应明细行的 Kernel 信息，分析 Kernel 数量变化

4. ModuleCompareStatistic（模块统计比对）

• 分析目标：定位劣化 TOP 模块
• 关键指标：Device Total Time Diff(ms)、Device Self Time Diff(ms)
• 分析方法：筛选 [ TOTAL ] 行，按总耗时差异降序，提取 Top 10 模块

5. ModuleCompare（模块明细比对）

• 分析目标：结合调用栈定位代码位置
• 关键指标：Call Stack、Device Self Time(us)
• 分析方法：提取劣化模块下算子的调用栈信息

6. CommunicationCompare（通信比对）

• 分析目标：定位通信改善/劣化算子，区分等待 vs 传输
• 关键指标：Total Duration(us)、Diff Ratio、Wait/Transmit 拆解
• 分析方法：按差异绝对值排序，分别识别改善最大和劣化最大的算子，标记极端改善（ratio < 0.1）

7. MemoryCompareStatistic（内存统计比对）

• 分析目标：定位内存增长 TOP 算子
• 关键指标：Diff Memory(MB)、Diff Ratio
• 分析方法：按内存差异降序，提取 Top 10。检测全零内存场景（NPU vs NPU 无内存差异）

8. MemoryCompare（内存明细比对）

• 分析目标：查看 TOP 算子内存分配详情
• 关键指标：Size(KB)、Allocated Details
• 分析方法：关联统计页 TOP 算子，提取分配明细

9. KernelCompare（Kernel比对）

• 分析目标：定位劣化 Kernel，分析负载均衡
• 关键指标：Total/Avg/Max/Min Duration(us)、Calls、Diff Total/Avg Ratio
• 分析方法：
  • 全局统计：劣化/改善总量、净趋势判断
  • 显著劣化：ratio > 1.05 的 Kernel 单独标记
  • 通信/计算分离：hcom_ 前缀的通信算子排除出 Top10 和负载均衡分析，单独折叠展示
  • 两卡数据量比对：计算每个算子的输入数据量（Shape 各维度相乘后所有 tensor 求和），汇总两卡总数据量和总 calls，判断负载是否均衡
  • Top 10 计算算子数据量明细：展示单次数据量、基准/比对 calls、基准/比对总数据量、耗时对比
  • 负载均衡分析：仅对 calls > 10 的计算算子做 max/min 方差分析，方差 > 2x 标记预警
  • 多 Shape 分布：同名 Kernel 不同 Shape 的数据量和耗时对比

10. KernelTypeCompare（Kernel类型比对）

• 分析目标：按类型汇总 Kernel 劣化
• 关键指标：Kernel Type、Core Type、Total Duration
• 分析方法：按类型聚合，识别劣化集中的 Kernel 类型

11. ApiCompare（API比对）

• 分析目标：定位劣化 Host 侧 API
• 关键指标：Total Duration(ms)、Self Time(ms)、Calls
• 分析方法：按总耗时差异排序，区分纯耗时变化（calls_ratio=1.0）vs 调用次数变化，统计净趋势

异常处理

所有解析器均处理以下异常情况：

• Sheet 不存在（比对开关未开启）
• Sheet 为空（无数据行）
• 列数不匹配（数据格式变化）
• 数值解析失败（非数字字段）
• 比率为 inf 或 NaN（基准值为 0）
• 全零内存场景（NPU vs NPU 无内存差异）
• 通信算子空 Shape（排除出负载均衡分析）

输出件

输出件	文件名	说明
中间件 JSON	compare_analysis_result.json	所有 Sheet 的结构化分析结果
HTML 报告	compare_analysis_report.html	改善/劣化双维度可视化报告
中文 xlsx	compare_chinese_result.xlsx	英文表头翻译为中文，多 Sheet 标签页
中文 CSV	chinese_csv/*.csv	每个 Sheet 一个独立 CSV（与 xlsx 同步生成）

分析方法论

详细的分析方法论请参考 references/analysis_methodology.md，包含：

• 各 Sheet 指标详解（每个字段的含义和分析要点）
• 综合分析决策树（先定界方向 → 再定位瓶颈 → 最后下钻根因）
• 常见场景与解读（GPU→NPU 迁移、版本升级、MoE 通信瓶颈、KV Cache 优化）
• 指标单位速查表和比率解读速查表