From 185f044fb9b8f02480c4f1d5867ebdef6845488a Mon Sep 17 00:00:00 2001 From: fanglanyue Date: Mon, 18 Aug 2025 20:01:00 +0800 Subject: [PATCH] msprof-analyze readme update --- profiler/msprof_analyze/README.md | 200 ++++++++++++------------------ 1 file changed, 82 insertions(+), 118 deletions(-) diff --git a/profiler/msprof_analyze/README.md b/profiler/msprof_analyze/README.md index f19938079..d4a5284c8 100644 --- a/profiler/msprof_analyze/README.md +++ b/profiler/msprof_analyze/README.md @@ -1,96 +1,9 @@ -# 性能工具 +# msprof-analyze -MindStudio Training Tools工具针对训练&大模型场景，提供端到端性能调优工具msprof-analyze：用户采集到性能数据后，由MindStudio Training Tools的性能工具msprof-analyze提供统计、分析以及相关的调优建议。 +## 📌 简介 +msprof-analyze（MindStudio Profiler Analyze）是MindStudio全流程工具链推出的性能分析工具，基于落盘的Profiler性能数据进行分析，识别AI作业中的性能瓶颈。 -## NPU性能数据采集 - -目前MindStudio Training Tools工具主要支持对Ascend PyTorch Profiler接口采集的性能数据进行分析，请参考官方文档：[Ascend PyTorch Profiler数据采集与分析](https://www.hiascend.com/document/detail/zh/canncommercial/80RC1/devaids/auxiliarydevtool/atlasprofiling_16_0006.html)。 - -### 环境和依赖 - -- 硬件环境请参见《[昇腾产品形态说明](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F80RC22%2Fquickstart%2Fquickstart%2Fquickstart_18_0002.html)》。 -- 软件环境请参见《[CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F80RC22%2Fsoftwareinst%2Finstg%2Finstg_0000.html%3FMode%3DPmIns%26OS%3DUbuntu%26Software%3DcannToolKit)》安装昇腾设备开发或运行环境，即toolkit软件包。 - -以上环境依赖请根据实际环境选择适配的版本。 - -### 版本配套说明 - -- Ascend PyTorch Profiler接口支持AscendPyTorch 1.11.0或更高版本，支持的PyTorch和CANN以及PyTorch和Python软件版本配套关系请参见《[Ascend Extension for PyTorch插件](https://gitee.com/ascend/pytorch)》。 -- MindSpore Profiler接口支持MindSpore 2.5.0或更高版本，支持的MindSpore和CANN以及MindSpore和Python软件版本配套关系请参见《[MindSpore-安装](https://www.mindspore.cn/install/)》。 -- Ascend PyTorch Profiler接口支持的固件驱动版本与配套CANN软件支持的固件驱动版本相同，开发者可通过“[昇腾社区-固件与驱动](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fhardware%2Ffirmware-drivers%2Fcommunity%3Fproduct%3D2%26model%3D28%26cann%3D8.0.RC3.alpha003%26driver%3D1.0.25.alpha)”页面根据产品型号与CANN软件版本获取配套的固件与驱动。 - -### 采集方式一：通过with语句进行采集 - -```python -import torch_npu -experimental_config = torch_npu.profiler._ExperimentalConfig( - aic_metrics=torch_npu.profiler.AiCMetrics.PipeUtilization, - profiler_level=torch_npu.profiler.ProfilerLevel.Level1, - l2_cache=False -) -with torch_npu.profiler.profile( - activities=[ - torch_npu.profiler.ProfilerActivity.CPU, - torch_npu.profiler.ProfilerActivity.NPU - ], - record_shapes=True, - profile_memory=True, - with_stack=True, - experimental_config=experimental_config, - schedule=torch_npu.profiler.schedule(wait=10, warmup=0, active=1, repeat=1), - on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./profiling_data") -) as prof: - # 模型训练代码 - for epoch, data in enumerate(dataloader): - train_model_one_step(model, data) - prof.step() -``` - -### 采集方式二：start，stop方式进行采集 - -```python -import torch_npu -experimental_config = torch_npu.profiler._ExperimentalConfig( - aic_metrics=torch_npu.profiler.AiCMetrics.PipeUtilization, - profiler_level=torch_npu.profiler.ProfilerLevel.Level1, - l2_cache=False -) -prof = torch_npu.profiler.profile( - activities=[ - torch_npu.profiler.ProfilerActivity.CPU, - torch_npu.profiler.ProfilerActivity.NPU - ], - record_shapes=True, - profile_memory=True, - with_stack=True, - experimental_config=experimental_config, - on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./profiling_data")) -# 模型训练代码 -for epoch, data in enumerate(dataloader): - if epoch == 11: - prof.start() - train_model_one_step(model, data) - prof.step() - if epoch == 11: - prof.stop() -``` - -### NPU性能数据目录结构 - -ascend pytorch profiler数据目录结构如下： - -``` -|- ascend_pytorch_profiling - |- * _ascend_pt - |- ASCEND_PROFILER_OUTPUT - |- trace_view.json - |- FRAMEWORK - |- PROF_XXX - |- profiler_info.json - |- * _ascend_pt -``` - -## 安装 +## 🔧 安装 性能工具的安装方式包括：**pip安装**、**下载whl包安装**和**源代码编译安装**。 @@ -205,50 +118,101 @@ Successfully installed msprof-analyze-{version} pip3 install ./msprof_analyze-{version}-py3-none-any.whl ``` -## 卸载和更新 +### 卸载和更新 -若需要更新工具，请先卸载旧版本后再重新安装新版本，如下操作： +若需要更新工具，请先卸载旧版本后再重新安装新版本，操作如下： +```bash +# 卸载旧版本 +pip3 uninstall msprof-analyze +# 安装新版本 +pip3 install ./msprof_analyze-{version}-py3-none-any.whl +``` -1. 卸载 - ```bash - pip3 uninstall msprof-analyze - ``` +## 🚀 快速入门 +### 前置条件 +* 安装 Python 3.8 及以上版本 +* 安装 `msprof-analyze` 工具 +* 采集性能数据： + * msprof 场景：参见“性能数据采集 > [msprof采集通用命令](https://www.hiascend.com/document/detail/zh/mindstudio/81RC1/T&ITools/Profiling/atlasprofiling_16_0008.html)”。 + * PyTorch 场景：参见“性能数据采集 > [PyTorch](https://www.hiascend.com/document/detail/zh/mindstudio/81RC1/msquickstart/atlasquick_train_0018.html)”。 + * MindSpore 场景：参见“性能数据采集 > [MindSpore](https://www.hiascend.com/document/detail/zh/mindstudio/81RC1/msquickstart/atlasquick_train_0017.html)”。 -2. 更新 +### 核心功能 +msprof-analyze 提供了三个核心子功能，帮助您从不同维度分析性能数据并获取优化建议： - ```bash - pip3 install ./msprof_analyze-{version}-py3-none-any.whl - ``` - -## 工具使用 +#### 1. 集群分析（cluster_analyse） +针对分布式训练场景，深度剖析多机多卡集群的性能特征与协同问题，精准定位慢卡、通信瓶颈、负载不均衡等集群特有问题，提升分布式训练效率。 ```bash -msprof-analyze advisor [-h] -``` +# 基础用法：基于通信域的通信分析和迭代耗时分析 +msprof_analyze cluster_analyse -m all -d ./cluster_data -o ./cluster_output -```bash -msprof-analyze compare [-h] +# 专项分析：指定分析能力（如慢卡诊断） +msprof_analyze cluster_analyse -m slow_rank -d ./cluster_data -o ./cluster_output ``` +支持的核心分析能力： +* 通信域性能画像：分析集群内通信耗时、带宽，识别通信瓶颈。 +* 慢卡定位与根因：检测集群中慢卡，分析负载不均衡等问题。 +* 集群耗时拆解：按迭代周期拆分细粒度计算、传输、搬运等耗时，定位低效环节。 +* 集群统计分析：解析 mstx 打点信息，对集群内 Hccl 通信、CANN API 调用等核心操作的耗时、调用频次进行统计汇总，生成结构化统计报告。 + +> 完整分析能力说明及参数配置，请参考 [msprof-analyze cluster 专项文档](./cluster_analyse/README.md) + +#### 2. 性能诊断（advisor） +自动分析性能数据，识别算子执行效率、下发调度、集群通信等潜在瓶颈，并生成分级优化建议，助力快速定位问题。 + ```bash -msprof-analyze cluster [-h] +# 基础用法 +msprof_analyze advisor all -d ./prof_data -o ./advisor_output ``` +分析完成后，在执行终端打印关键问题与优化建议，并生成 +* `mstt_advisor_{timestamp}.html`按重要程度标记的优化建议 +* `mstt_advisor_{timestamp}.xlsx`问题综述与详细的分析信息 + +> 详细分析规则、参数配置及结果解读，请参考 [msprof-analyze advisor 专项文档](./advisor/README.md)。 + +#### 3. 性能对比（compare） +支持GPU与NPU之间、NPU与NPU之间两组性能数据的深度对比，通过多维度量化指标直观呈现性能差异。 + ```bash -msprof-analyze auto-completion [-h] +# 基础用法：对比昇腾NPU与GPU性能数据 +msprof_analyze compare -d ./ascend_pt # 昇腾NPU性能数据目录 + -bp ./gpu_trace.json # GPU性能数据文件 + -o ./compare_output # 对比结果输出目录 ``` -``` -msprof-analyze [-h] [-v] -``` +对比报告`performance_comparison_result_{timestamp}.xlsx`包含： +* 宏观性能拆分：按计算、通信、空闲三大维度统计耗时占比差异，快速识别性能损耗主要场景。 +* 细粒度对比：按算子（如 Conv、MatMul）、框架接口等粒度展示耗时差异，定位具体性能差距点。 + +> 对比规则维度、参数说明及报告解读，请参考 [msprof-analyze compare 专项文档](./cluster_analyse/README.md)。 + -| 参数 | 说明 | -| -------------------- |-------------------------------------------------------------------------------------------------------------------------| -| advisor | [advisor](./advisor/README.md)。将Ascend PyTorch Profiler或者MindSpore采集的PyThon场景性能数据进行分析，并输出性能调优建议。 | -| compare | [compare_tools（性能比对工具）](./compare_tools/README.md)。提供NPU与GPU性能拆解功能以及算子、通信、内存性能的比对功能。 | -| cluster | [cluster_analyse（集群分析工具）](./cluster_analyse/README.md)。提供多机多卡的集群分析能力（基于通信域的通信分析和迭代耗时分析）, 当前需要配合Ascend Insight的集群分析功能使用。 | -| auto-completion | 自动补全。配置后在当前视图下配置msprof-analyze工具所有的子参数时，可以使用Tab将所有子参数自动补全。 | +### 参数说明 +msprof-analyze工具参数列表如下： + +| 参数 | 说明 | +|---------------------|-------------------------------------------------------------------------------------------------------------------------| +| advisor | [advisor](./advisor/README.md)。将Ascend PyTorch Profiler或者MindSpore采集的PyThon场景性能数据进行分析，并输出性能调优建议。 | +| compare | [compare_tools（性能比对工具）](./compare_tools/README.md)。提供NPU与GPU性能拆解功能以及算子、通信、内存性能的比对功能。 | +| cluster | [cluster_analyse（集群分析工具）](./cluster_analyse/README.md)。提供多机多卡的集群分析能力（基于通信域的通信分析和迭代耗时分析）, 当前需要配合Ascend Insight的集群分析功能使用。 | +| auto-completion | 自动补全。配置后在当前视图下配置msprof-analyze工具所有的子参数时，可以使用Tab将所有子参数自动补全。 | | -v，-V
--version | 查看版本号。 | | -h，-H
--help | 命令行参数帮助信息。 | + +## 🌟 特性介绍 + +| 分析能力 | 介绍 | Released | +|---------|----------------------------------------|-----| +| 集群细粒度拆解 | [link](./docs/cluster_time_summary.md) | ✅ | +| pp流水图 | [link](./docs/pp_chart.md) | ✅ | + +## 📚 版本说明 +### 版本配套说明 +* Ascend PyTorch Profiler接口支持AscendPyTorch 1.11.0或更高版本，支持的PyTorch和CANN以及PyTorch和Python软件版本配套关系请参见《[Ascend Extension for PyTorch插件](https://gitee.com/ascend/pytorch)》。 +* MindSpore Profiler接口支持MindSpore 2.5.0或更高版本，支持的MindSpore和CANN以及MindSpore和Python软件版本配套关系请参见《[MindSpore-安装](https://www.mindspore.cn/install/)》。 +* Ascend PyTorch Profiler接口支持的固件驱动版本与配套CANN软件支持的固件驱动版本相同，开发者可通过“[昇腾社区-固件与驱动](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fhardware%2Ffirmware-drivers%2Fcommunity%3Fproduct%3D2%26model%3D28%26cann%3D8.0.RC3.alpha003%26driver%3D1.0.25.alpha)”页面根据产品型号与CANN软件版本获取配套的固件与驱动。 \ No newline at end of file -- Gitee