# 查看诊断报告
Advisor分析profiling会输出html和xlsx两份文件。请优先查看html报告进行训练作业性能调优。xlsx中记录了html中全量数据，如集群计算、通信和下发的耗时，可以基于xlsx对计算耗时、下发耗时和带宽等列进行排序，从而快速过滤出计算慢卡、下发慢卡、带宽最小卡。
#### html总览
html中包括总体性能分析（overall）、快慢卡算子性能比对（comparison）和性能问题分析（performance problem analysis）三大模块。overall模块包含对单卡或者集群的性能统计数据，comparison模块包含目标集群profiling与标杆集群profiling或目标集群内部快慢卡的算子比对数据，performance problem analysis模块包含计算（computation）、下发（schedule）、通信（communication）、内存（memory）和数据加载（dataloader）五个维度的具体分析。用户首先需要查看overall模块初步明确是否存在计算维度的慢卡和下发维度慢卡，然后再重点关注performance problem analysis中对应维度的各项分析及其优先级。
红色为高优先级，黄色为中等优先级，绿色为低优先级。参考html进行分析调优时，请按照优先级从高到低依次进行并测试调优后性能，快速解决重点问题。
图1html报告总览-三大模块
当前advisor的performance problem analysis中包含如下分析项。
表1性能分析能力概览
| 分析维度 | 分析项 | 释义 |
|:---|:---|:---|
| overall | overall summary | 对于单卡profiling进行性能拆解，获取单步计算、下发和通信耗时。 |
| overall | slow rank | 对于集群profiling进行性能统计，获取每张卡不同step的计算、下发和通信耗时。 |
| overall | slow link | 对于集群profiling进行性能统计，获取每张卡不同step的带宽信息。 |
| overall | environment variable | 识别错误配置且会影响性能的环境变量，如PLOG日志级别，HCCL相关环境变量，依赖24年930版本的pta。 |
| comparison | kernel compare | 两张卡NPU侧计算算子对比。 |
| comparison | api compare | 两张卡CPU侧torch aten算子下发对比。 |
| performance problem analysis | computation - AI CORE frequency | 计算维度，识别降频的节点，节点降频会导致flash attention和matmul类算子计算性能变差。 |
| performance problem analysis | computation - AICPU | 计算维度，识别AICPU算子，部分AICPU算子计算性能较差。 |
| performance problem analysis | computation - operator dynamic shape | 计算维度，检测动态shape，动态shape会触发频繁的算子编译。 |
| performance problem analysis | computation - operator bound | 计算维度，算子计算性能分析，例如算子是否充分使用AICORE核数。 |
| performance problem analysis | schedule - synchronize stream | 下发维度，异常同步流分析，过多同步流会打断CPU侧任务异步下发。 |
| performance problem analysis | schedule - garbage collection(GC) | 下发维度，识别异常耗时的垃圾回收，垃圾回收会造成大段空闲。 |
| performance problem analysis | schedule - operator dispatch | 下发维度，算子下发时编译分析，大量算子编译会导致整体训练性能变差。 |
| performance problem analysis | schedule - syncBatchNorm | 下发维度，NPU上分布式训练使用syncBN性能较差。 |
| performance problem analysis | schedule - affinity api | 下发维度，自动识别可替换的亲和API（融合算子API如rms_norm，亲和优化器如NpuFusedAdamw）。 |
| performance problem analysis | communication - small packet | 通信维度，识别因batch过小或者梯度累积较少导致的未充分利用机内通信带宽。 |
| performance problem analysis | communication - bandwidth contention | 通信维度，识别计算和通信相互掩盖，可能会抢占通信带宽。 |
| performance problem analysis | communication - retransmission | 通信维度，识别通信重传问题，单次重传耗时4秒以上。 |
| performance problem analysis | memory | 内存维度，识别异常内存算子。 |
| performance problem analysis | dataloader | 数据加载维度，异常耗时的数据读取将会导致明显的训练性能劣化。 |
#### overall模块介绍
- **单卡** **overall summary**
下图展示了单卡上一个step的端到端耗时为1353ms，其中计算耗时（昇腾硬件上算子执行耗时）是57ms，未掩盖通信耗时为0ms，空闲耗时（硬件上没有进行计算和通信的其他时间）为1295ms。基于这三项数据可以初步判断当前训练任务的主要耗时瓶颈为空闲耗时。空闲耗时通常是任务下发(schedule)、数据加载(dataloader)和内存(memory)三个维度问题导致的，因此可以重点关注performance problem analysis中对应三个维度的分析。同理如果计算耗时占比较大，则应该重点关注计算维度的分析。
图2单卡性能拆解总体描述
图3单卡性能拆解详情
- **多卡** **slow rank \& slow link**
下图展示了多卡profiling分析的overall模块，包含集群快慢卡统计数值(slow rank，用于分析计算和任务下发的快慢卡)和集群带宽统计数值(slow link，用于分析集群中的网络通信慢链路)。点开slow rank模块，html中会基于表格展示每张卡不同step的计算耗时、通信耗时和空闲耗时。基于该表格，通常关注计算耗时(compute)和空闲耗时(free)这两列，可以初步分析当前瓶颈点是计算还是任务下发，以及是否存在计算快慢卡和下发快慢卡。如下图所示，可以看到8号卡的计算耗时明显大于其他卡，因此8号卡的"短板效应"将会拖慢集群的整体训练速度，后续性能分析需要重点关注8号卡的计算维度。
图4多卡不同step计算、下发和通信耗时统计值
图5多卡不同step通信带宽统计值
- **环境变量Environment Variable Issues**
识别模型训练环境中设置的昇腾相关环境变量并给出建议。
图6环境变量分析
表2当前支持的环境变量
| 环境变量名称 | 释义 |
|:---|:---|
| ASCEND_GLOBAL_LOG_LEVEL | plog日志级别，推荐设置为2（warning级别），低级别日志等级会导致CPU侧性能问题。 |
| HCCL_RDMA_TC | HCCL通信相关环境变量，通常无需设置该环境变量，建议unset该环境变量。具体参考[HCCL_RDMA_TC](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/800alpha001/apiref/envref/envref_07_0084.html)。 |
| HCCL_RDMA_SL | HCCL通信相关环境变量，通常无需设置该环境变量，建议unset该环境变量。具体参考[HCCL_RDMA_SL](https://www.hiascend.com/document/detail/zh/canncommercial/80RC2/apiref/envvar/envref_07_0082.html)。 |
| ACLNN_CACHE_LIMIT | 用于缓存cann侧的aclnn算子，当空闲时间（free）较大时，可以尝试设置一个较大的数值，如export ACLNN_CACHE_LIMIT=100000。 |
| HOST_CACHE_CAPACITY | 用于动态shape缓存，当存在动态shape时，设置一个非零正整数，如export HOST_CACHE_CAPACITY=20。 |
| ASCEND_ENHANCE_ENABLE | 使能HCCL的FFTS+模式，export ASCEND_ENHANCE_ENABLE=1。 |
| PYTORCH_NPU_ALLOC_CONF | 控制缓存分配，当存在内存碎片时，执行export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True。 |
| ASCEND_LAUNCH_BLOCKING | 是否启动同步下发，同步下发会导致严重的性能劣化，建议执行unset ASCEND_LAUNCH_BLOCKING。 |
#### comparison模块介绍
当同时指定目标集群profiling和标杆集群profiling或者目标集群内部存在快慢卡时，advisor会针对计算和下发性能存在差异的卡（快慢卡）进行算子级的对比。
如下图所示，当分析时显式指定了标杆集群profiling数据，advisor识别到两次训练任务中0号卡的step12存在计算性能差异，则会对目标集群的0号卡step12与标杆集群的0号卡step12进行kernel（npu侧计算的算子）性能对比。基于该对比数据，可以判断两张卡上的npu算子是否存在计算性能差异。
图7目标集群profiling数据与标杆集群profiling数据的kernel算子对比
如下图所示，当分析时显式指定了标杆集群profiling数据，advisor识别到两次训练任务中6号卡的step16存在api下发性能差异，对目标集群的6号卡step16与标杆集群的6号卡step16进行了api（cpu侧的torch aten算子任务下发）的性能对比。基于该对比数据，可以判断两张卡上的aten算子是否存在下发性能差异。
图8目标集群profiling数据与标杆集群profiling数据的api下发对比
如下图所示，分析时并没有指定标杆集群profiling数据，但advisor识别到目标集群存在任务下发快慢卡（16和19号卡）现象，因此对比了16号卡step175和19号卡step172的api下发性能。
图9目标集群（无标杆集群profiling）内部快慢卡api下发对比
#### performance problem analysis模块介绍
performance problem analysis中会细分为计算（computation），下发（schedule），通信（communication）、内存（memory）和数据加载（dataloader）五个维度，根据训练作业卡数、训练实际性能问题有不同的呈现，并非所有训练任务都有上述五个维度的分析。
图10html报告总览-性能分析五维度
- **computation**
计算维度通常包含如下几类问题：
- 降频：对应html中的'AI CORE Frequency Issues'。NPU AICORE主频降低，导致flash attention和matmul类算子计算性能严重劣化。
- AICPU算子：对应html中的'AICPU Issues'。部分算子因NPU支持度或者输入数据shape/dtype等原因，无法在AICORE上运行，因此会放在AICPU上进行计算，部分AICPU算子会存在明显的性能劣化。
- 动态shape：对应html中的'Operator Dynamic Shape Issues'。动态shape场景，部分昇腾算子会重复编译，导致计算延后，影响性能。
- operator bound等问题：算子未打满AICORE的核数，导致计算利用率较低。
具体介绍如下：
- **AI CORE Frequency Issues**
下图展示了高优先级的降频问题，从表格中可以看到flash attention算子耗时最长且降频比率最高，因此降频严重影响了整体的训练性能。对于降频问题，用户通常无法自行解决，需要联系服务方如华为云技术支持排查机器的温度和功耗。
图11降频分析
- **AICPU Issues**
下图展示了高优先级的AICPU问题，AICPU算子单步计算耗时313秒，GridSample2D算子单步计算耗时208秒，因此需要重点关注该算子。可以通过html中提供的堆栈信息查看源码中对该算子的调用是否可以替换成其他torch api，如果分析后无法替换可以求助昇腾算子侧的算子开发人员进行算子优化分析。
图12AICPU算子分析
- **Operator Dynamic Shape Issues**
下图展示了低优先级的动态shape问题，在NPU上动态shape可能导致频繁的算子编译从而影响训练性能，可以按照html中的提示在训练脚本开头加上如下红框中的两行代码（分布式训练请确保分布式训练的每个进程都可以使能这两行代码）。
图13动态shape分析
- **schedule**
下发维度通常包含如下几类问题
- 同步流：对应html中的'Synchronize Stream Issues'。用户设置了ASCEND_LAUNCH_BLOCKING环境变量，打断了CPU侧算子的异步下发，严重影响训练性能。
- GC：对应html中的'GC Analysis'。python garbage collection机制，大规模集群训练时GC任务会导致部分step训练耗时异常增大。
- 算子下发：对应html中的'Operator Dispatch Issues'。训练时如果频繁进行算子编译会严重影响训练性能，可以增加两行python代码关闭算子编译。
- 亲和API：对应html中的'Affinity API Issues'。通过使能亲和API（NPU融合算子API如rms_norm，NPU亲和优化器如NPUFusedAdamw）可以减少算子下发数量，从而提升训练性能。
- syncBatchNorm：对应html中的'SyncBatchNorm Issues'。多卡DDP训练时如果使用syncBatchNorm，会存在明显的算子下发和通信瓶颈。
具体介绍如下：
- **Synchronize Stream Issues**
下图展示了高优先级的同步流问题，html中提示发现大量同步算子，可以尝试\`unset ASCEND_LAUNCH_BLOCKING\` 环境变量后再进行训练。
图14异常同步流分析
- **GC Analysis**
下图展示了中优先级的GC问题，html中提示发现单步训练中存在200ms左右的空闲时间且在该时间窗内cpu侧没有进行训练算子下发，怀疑是GC导致，可以尝试加上\`gc.disable()\`关闭GC。
图15python垃圾回收（GC）分析
- **Operator Dispatch Issues**
下图展示了中优先级的算子下发问题，html中提示识别到单步训练中存在6678个算子进行了算子编译，编译耗时149ms，可以在训练脚本最开头加上suggestion中的两行代码关闭算子编译（分布式训练请确保每个进程都可以使能这两行代码）。
图16算子编译分析
- **Affinity API Issues**
下图展示了低优先的亲和API替换，通常仅在首次将训练任务从GPU迁移至NPU时需要关注这部分内容。已经在NPU上进行长训的任务出现性能问题，可以忽略该部分。html中提示存在torch_npu.confusion_transpose, 梯度裁剪和亲和优化器等多个可替换的API，用户可根据代码堆栈找到需要替换的具体源码，然后根据API instruction跳转后的参考文档修改源代码，从而使能亲和API提升训练性能。注意这里提示的亲和API并非都能提升训练性能，需要用户替换后实测，由于有一定代码修改和测试成本，因此优先级可以视作最低。
图17亲和API分析
- **SyncBatchNorm Issues**
下图展示了高优先级的syncBatchNorm问题，html中提示可以通过去除convert_sync_batchnorm代码使能普通的batchNorm，如果模型开发者评估认为对训练精度存在影响，可以使用html中给出的代码段替换torch_npu中syncbatchnorm.py文件的forward方法（可以在训练环境中执行\`pip show torch_npu\`查看torch_npu的安装路径）。这类优化通常可以较显著地提升训练速度。
图18SyncBatchNorm分析
- **memory**
内存维度当前识别的问题较为简单，通常是NPU HBM占用过大或者存在内存碎片导致自动触发昇腾内存释放/重整算子（Memory Operator Issues），进而影响了训练性能。
下图展示了高优先级的内存算子问题，html中提示对于1号卡存在大量aclrtFree和aclMalloc算子，导致存在较大的空闲时间。按照建议，对于aclrtFree算子类问题，首先观察NPU HBM是否已经打满，如果打满则尝试减小micro batch size或者调整训练策略，例如训练LLM模型时使用ZeRO 3优化内存。其次采集profiling时设置"with_stack=True参数"，然后基于MindInsight Studio可视化profiling数据查看代码中是否存在empty_cache操作，如果存在则注释对应代码。对于aclMalloc算子类问题，按照建议设置环境变量即可减少内存碎片。
图19内存算子分析
- **dataloader**
数据加载维度（Slow Dataloader Issues）通常包含如下几类问题：
- 数据放在读写性能较差的存储盘上，如云上的EVS和EFS。
- 多卡训练时使用单进程dataloader，即num_workers参数默认为0。
- 存在其他多进程操作影响了数据多进程读取。
- 数据格式问题，例如zip、tar.gz等压缩包。
- dataloader参数设置不合理，如没有配置锁页内存pin_memory=True。 下图中展示了高优先级的dataloader问题，较慢的数据加载将会严重影响训练速度。html中提示分别从数据盘、多进程、dataloader参数设置、数据格式等不同方向进行排查。
图20数据加载分析
- **communication**
通信维度当前支持检测如下几类问题。
- 通信计算并行时抢占通信带宽：对应html中的'BandWidth Contention Analysis'。在LLM类模型训练过程中，对于megatron类框架可以配置overlap相关参数使能计算和通信互相掩盖，进而提升训练性能。但部分场景中计算抢占通信带宽反而会导致性能劣化。
- 小包分析：对应html中的'Packet Analysis'。当BatchSize较小或其他场景，并没有打慢NPU HBM，卡间通信数据包较小，没有充分利用通信带宽。
- RDMA重传（跨节点通信）：对应html中的"Communication Retransmission Analysis"。当网络通信配置出现冲突情况下，RDMA通信传输可能出现重传，导致通信耗时异常大幅增加。
具体介绍如下：
- **BandWidth Contention Analysis**
下图展示了低优先级的通信带宽抢占问题，大部分场景中通信计算互相掩盖是有较大训练性能收益的，可以通过修改overlap或其他相关参数来测试是否存在性能提升。
图21通信带宽抢占分析
- **Packet Analysis**
下图展示了低优先级的通信小包问题，html中提示SDMA（机内通信）带宽相对较小，可以尝试增大batchSize或者梯度累积参数，如果配置了ZeRO3则推荐使用ZeRO1或者ZeRO2（如果内存够）。
图22通信小包分析
- **Communication Retransmission Analysis**
单次通信重传将会耗时4秒以上，会导致较严重的通信性能劣化，这类问题通常是由于节点网络配置错误导致，可以联系服务方如华为云技术支持排查网络配置。
图23通信重传分析
