前提条件
- 请确保完成使用前准备。
- 准备好基于PyTorch 1.11.0或更高版本开发的训练模型以及配套的数据集，并按照《Ascend Extension for PyTorch 训练模型迁移调优指南》中的“迁移适配”完成PyTorch原始模型向昇腾AI处理器的迁移。
采集并解析性能数据
- 使用Ascend PyTorch Profiler接口开启PyTorch训练时的性能数据采集。
在训练脚本（如train_*.py文件）内添加如下示例代码进行性能数据采集参数配置，之后启动训练。下列示例代码中，加粗字段为需要配置的参数、方法、类和函数。
- 示例一（使用torch_npu.profiler.profile类采集性能数据）：
import torch 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, data_simplification=False ) with torch_npu.profiler.profile( activities=[ torch_npu.profiler.ProfilerActivity.CPU, torch_npu.profiler.ProfilerActivity.NPU ], schedule=torch_npu.profiler.schedule(wait=1, warmup=1, active=2, repeat=2, skip_first=10), on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./result"), record_shapes=False, profile_memory=False, with_stack=False, with_flops=False, experimental_config=experimental_config) as prof: for step in range(steps): train_one_step(step, steps, train_loader, model, optimizer, criterion) prof.step()或
import torch import torch_npu ... experimental_config = torch_npu.profiler._ExperimentalConfig( aic_metrics=torch_npu.profiler.AiCMetrics.ArithmeticUtilization, profiler_level=torch_npu.profiler.ProfilerLevel.Level1 ) prof = torch_npu.profiler.profile( activities=[ torch_npu.profiler.ProfilerActivity.CPU, torch_npu.profiler.ProfilerActivity.NPU ], schedule=torch_npu.profiler.schedule(wait=0, warmup=0, active=1, repeat=1, skip_first=1), on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./result"), experimental_config=experimental_config) prof.start() for step in range(steps): train_one_step() prof.step() prof.stop()除了使用tensorboard_trace_handler导出性能数据外，还可以使用以下方式导出：import torch import torch_npu ... with torch_npu.profiler.profile() as prof: for step in range(steps): train_one_step(step, steps, train_loader, model, optimizer, criterion) prof.export_chrome_trace('./chrome_trace_14.json') - 示例二（使用torch_npu.profiler._KinetoProfile类采集性能数据）：
import torch import torch_npu ... prof = torch_npu.profiler._KinetoProfile(activities=None, record_shapes=False, profile_memory=False, with_stack=False, with_flops=False, with_modules=False, experimental_config=None) for epoch in range(epochs): trian_model_step() if epoch == 0: prof.start() if epoch == 1: prof.stop() prof.export_chrome_trace("result_dir/trace.json")该方式不支持使用schedule和tensorboard_trace_handler导出性能数据。
表1 torch_npu.profiler.profile和torch_npu.profiler._KinetoProfile配置参数说明 参数名称
参数含义
是否必选
activities
CPU、NPU事件采集列表，Enum类型。取值为：
- torch_npu.profiler.ProfilerActivity.CPU：框架侧数据采集的开关。
- torch_npu.profiler.ProfilerActivity.NPU：CANN软件栈及NPU数据采集的开关。
默认情况下两个开关同时开启。
否
schedule
设置不同step的行为，Callable类型，由schedule类控制。
torch_npu.profiler._KinetoProfile不支持该参数。
否
on_trace_ready
采集结束时自动执行操作，Callable类型。当前仅支持执行tensorboard_trace_handler函数的操作，默认不执行任何操作。当采集的数据量过大时，在当前环境下不适合直接解析性能数据，或者采集过程中中断了训练进程，只采集了部分性能数据，可以采用离线解析。
torch_npu.profiler._KinetoProfile不支持该参数。
否
record_shapes
算子的InputShapes和InputTypes，Bool类型。取值为：
- True：开启。
- False：关闭。默认值。
开启torch_npu.profiler.ProfilerActivity.CPU时生效。
否
profile_memory
算子的内存占用情况，Bool类型。取值为：
- True：开启。
- False：关闭。默认值。
否
with_stack
算子调用栈，Bool类型。包括框架层及CPU算子层的调用信息。取值为：
- True：开启。
- False：关闭。默认值。
开启torch_npu.profiler.ProfilerActivity.CPU时生效。
否
with_flops
算子浮点操作，Bool类型（该参数暂不支持解析性能数据）。取值为：
- True：开启。
- False：关闭。默认值。
开启torch_npu.profiler.ProfilerActivity.CPU时生效。
否
experimental_config
扩展参数，通过扩展配置性能分析工具常用的采集项。支持采集项和详细介绍请参见experimental_config扩展参数。
否
use_cuda
昇腾环境不支持。开启采集cuda性能数据开关。取值为：
- True：开启。
- False：关闭。默认值。
torch_npu.profiler._KinetoProfile不支持该参数。
否
表2 torch_npu.profiler.profile和torch_npu.profiler._KinetoProfile方法说明 方法名
含义
step
划分不同迭代。
torch_npu.profiler._KinetoProfile不支持该方法。
export_chrome_trace
导出trace。在指定的.json文件里写入trace数据。Trace为Ascend PyTorch Profiler接口整合框架侧CANN软件栈及NPU数据后展示的各算子和接口的运行时间及关联关系。包含参数：
- path：trace文件（.json）路径。指定文件所在的路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。
在设置了torch_npu.profiler.tensorboard_trace_handler的情况下，export_chrome_trace不生效。
多卡场景下需要将不同卡设置不同的文件名，示例代码：
pid = os.getpid() prof.export_chrome_trace(f'./chrome_trace_{pid}.json')export_stacks
导出堆栈信息到文件。包含参数：
- path：堆栈文件保存路径，需要配置文件名为“*.log”，可以指定路径，例如：/home/*.log，直接配置文件名时，文件保存在当前目录。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。
- metric：保存的芯片类型可选择CPU或NPU，配置为“self_cpu_time_total”或“self_npu_time_total”。
与export_chrome_trace方法在训练脚本中的位置相同，示例如下：
export_stacks("resule_dir/stack.log", metric='self_npu_time_total')导出的结果文件可使用FlameGraph工具进行查看，操作方法如下：
git clone https://github.com/brendangregg/FlameGraph cd FlameGraph ./flamegraph.pl –title “NPU time” –countname “us.” profiler.stacks > perf_viz.svg
start
设置采集开始的位置。可参考如下样例，在需要采集性能数据的训练代码前后添加start和stop：
prof = torch_npu.profiler.profile( on_trace_ready=torch_npu.profiler.tensorboard_trace_handler("./result")) for step in range(steps): if step == 5: prof.start() train_one_step() if step == 5: prof.stop()stop
设置采集结束的位置，需要先执行start。
表3 torch_npu.profiler类、函数说明 类、函数名
含义
torch_npu.profiler.schedule
设置不同step的行为。取值为：
- skip_first：采集前先跳过的step轮数。默认为值0。动态Shape场景建议跳过前10轮保证性能数据稳定；对于其他场景，可以根据实际情况自行配置。可选。
- wait：每次重复执行采集跳过的step轮数。必选。
- warmup：预热的step轮数，int类型，默认值为0。建议设置1轮预热。可选。
- active：采集的step轮数。必选。
- repeat：重复执行wait+warmup+active的次数。默认为值0，表示重复执行repeat不停止，建议配置为大于0的整数。可选。
建议根据此公式配置schedule：step总数 >= skip_first+(wait+warmup+active)*repeat
默认不执行该操作。
将采集到的性能数据导出为TensorBoard工具支持的格式。取值为：
- dir_name：采集的性能数据的输出目录。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。可选。若配置tensorboard_trace_handler函数后未指定具体路径，性能数据默认落盘在当前目录。
若代码中未使用on_trace_ready=torch_npu.profiler.tensorboard_trace_handler，那么落盘的性能数据为原始数据，需要使用离线解析。
该函数优先级高于ASCEND_WORK_PATH，具体请参考《环境变量参考》。
- worker_name：用于区分唯一的工作线程，默认为{hostname}_{pid}。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。可选。
- use_gzip：文件压缩。暂不支持。
torch_npu.profiler._KinetoProfile不支持该函数。
torch_npu.profiler.ProfilerAction
Profiler状态，Enum类型。取值为：
- NONE：无任何行为。
- WARMUP：性能数据采集预热。
- RECORD：性能数据采集。
- RECORD_AND_SAVE：性能数据采集并保存。
torch_npu.profiler.supported_activities
查询当前支持采集的activities参数的CPU、NPU事件。
torch_npu.profiler.supported_profiler_level
查询当前支持的experimental_config扩展参数的profiler_level级别。
torch_npu.profiler.supported_ai_core_metrics
查询当前支持的experimental_config扩展参数的AI Core性能指标采集项。
torch_npu.profiler.supported_export_type
查询当前支持的torch_npu.profiler.ExportType的性能数据结果文件类型。
性能数据会占据一定的磁盘空间，可能存在磁盘写满导致服务器不可用的风险。性能数据所需空间跟模型的参数、采集开关配置、采集的迭代数量有较大关系，须用户自行保证落盘目录下的可用磁盘空间。
- 示例一（使用torch_npu.profiler.profile类采集性能数据）：
- （可选）以自定义字符串键和字符串值的的形式标记性能数据采集过程。
- 示例一
with torch_npu.profiler.profile(…) as prof: prof.add_metadata(key, value) - 示例二
with torch_npu.profiler._KinetoProfile(…) as prof: prof.add_metadata_json(key, value)
add_metadata和add_metadata_json可以分别配置在torch_npu.profiler.profile和torch_npu.profiler._KinetoProfile下，须添加在profiler初始化后，finalize之前，即性能数据采集过程的代码中。
表4 add_metadata接口说明 类、函数名
含义
add_metadata
添加字符串标记，可取值：
- key：字符串键。
- value：字符串值。
示例：
prof.add_metadata("test_key1", "test_value1")add_metadata_json
添加json格式字符串标记，可取值：
- key：字符串键。
- value：字符串值，json格式。
示例：
prof.add_metadata("test_key2", [1, 2, 3])调用此接口传入的metadata数据写入到Ascend PyTorch Profiler接口的采集结果根目录下的profiler_metadata.json文件中。
- 示例一
- 查看采集到的PyTorch训练性能数据结果文件。
训练结束后，在torch_npu.profiler.tensorboard_trace_handler接口指定的目录下生成Ascend PyTorch Profiler接口的采集结果目录。
└── localhost.localdomain_139247_20230628101435_ascend_pt // 解析结果目录，命名格式：{worker_name}_{时间戳}_ascend_pt，默认情况下{worker_name}为{hostname}_{pid} ├── profiler_info.json // 多卡或集群场景命名规则为profiler_info_{Rank_ID}.json，用于记录Profiler相关的元数据 ├── ASCEND_PROFILER_OUTPUT // Ascend PyTorch Profiler接口采集性能数据 │ ├── ascend_pytorch_profiler_{rank_id}.db // export_type=torch_npu.profiler.ExportType.Db时该目录下仅生成.db文件，其他.json和.csv文件不生成，使用Ascend Insight工具展示 │ ├── analysis.db // 多卡或集群等存在通信的场景下，设置export_type=torch_npu.profiler.ExportType.Db时该目录下仅生成.db文件，其他.json和.csv文件不生成，使用Ascend Insight工具展示 │ ├── communication.json // 为多卡或集群等存在通信的场景性能分析提供可视化数据基础，配置experimental_config的profiler_level=torch_npu.profiler.ProfilerLevel.Level1或profiler_level=torch_npu.profiler.ProfilerLevel.Level2生成 │ ├── communication_matrix.json // 通信小算子基本信息文件，配置experimental_config的profiler_level=torch_npu.profiler.ProfilerLevel.Level1或profiler_level=torch_npu.profiler.ProfilerLevel.Level2生成 │ ├── data_preprocess.csv // 配置experimental_config profiler_level=torch_npu.profiler.ProfilerLevel.Level2生成 │ ├── kernel_details.csv │ ├── l2_cache.csv // 配置experimental_config的l2_cache=True生成 │ ├── memory_record.csv │ ├── npu_module_mem.csv │ ├── operator_details.csv │ ├── operator_memory.csv │ ├── step_trace_time.csv // 迭代中计算和通信的时间统计 │ ├── op_statistic.csv // AI Core和AI CPU算子调用次数及耗时数据 │ └── trace_view.json ├── FRAMEWORK // 框架侧的性能原始数据，无需关注，data_simplification=True时删除此目录 │ ├── torch.memory_usage │ ├── torch.op_mark │ ├── torch.op_range │ ├── torch.python_func_call // with_stack=True时生成 │ └── torch.python_module_call // with_stack=True时生成 └── PROF_000001_20230628101435646_FKFLNPEPPRRCFCBA // CANN层的性能数据，命名格式：PROF_{数字}_{时间戳}_{字符串}，data_simplification=True时，仅保留此目录下的原始性能数据，删除其他数据 ├── analyze // 配置experimental_config的profiler_level=torch_npu.profiler.ProfilerLevel.Level1或profiler_level=torch_npu.profiler.ProfilerLevel.Level2生成 ├── device_* ├── host ├── mindstudio_profiler_log └── mindstudio_profiler_output ├── localhost.localdomain_139247_20230628101435_ascend_pt_op_args // 算子信息统计文件目录，配置experimental_config的record_op_args=True生成 ├── 进程ID │ ├── operator_name+data_type+timestamp.json // 算子信息统计文件
experimental_config扩展参数
experimental_config扩展参数均为可选参数，支持扩展的采集项如下：
参数 |
描述 |
|---|---|
export_type |
设置导出的性能数据结果文件格式，可取值：
设置无效值或未配置均取默认值。 |
profiler_level |
采集的Level等级，Enum类型。可取值如下：
|
data_simplification |
数据精简模式，开启后将在导出性能数据后删除FRAMEWORK目录数据以及删除多余数据，仅保留ASCEND_PROFILER_OUTPUT目录和PROF_XXX目录下的原始性能数据，以节省存储空间。可取值True（开启）或False（关闭），默认开启。 |
aic_metrics |
AI Core的性能指标采集项，Enum类型。可取值如下： 以下采集项的结果数据含义可参见op_summary（AI Core、AI Vector Core和AI CPU算子数据），但具体采集结果请以实际情况为准。
|
l2_cache |
控制L2 Cache数据采集开关。可取值True或False，默认为False。该采集项在ASCEND_PROFILER_OUTPUT生成l2_cache.csv文件，结果字段介绍请参见L2 Cache数据。 |
record_op_args |
控制算子信息统计功能开关，可取值True或False，默认为False。开启后会在{worker_name}_{时间戳}_ascend_pt_op_args目录输出采集到到算子信息文件。 说明：
该参数在AOE工具执行PyTorch训练场景下调优时使用，且不建议与其他性能数据采集接口同时开启。详见《AOE工具使用指南》。 |
离线解析
当使用Ascend PyTorch Profiler接口采集的性能数据较大时，若在当前环境直接使用on_trace_ready接口进行自动解析，则可能导致资源占用过大出现卡顿，那么可以取消on_trace_ready接口，并通过环境变量ASCEND_WORK_PATH设置落盘目录（例如：export ASCEND_WORK_PATH=xx/xx），在采集完成性能数据后，使用如下方式进行离线解析：
- 创建{file_name}.py文件，{file_name}自定义，并编辑如下代码：
from torch_npu.profiler.profiler import analyse if __name__ == "__main__": analyse(profiler_path="./result_data", max_process_number=max_process_number)表6 参数说明 参数
描述
可选/必选
profiler_path
PyTorch性能数据路径。指定的目录下保存PyTorch性能数据目录{worker_name}_{时间戳}_ascend_pt。
必选
max_process_number
离线解析最大进程数。取值范围为1~CPU核数，默认为CPU核数的一半。若设置超过该环境的CPU核数，则自动取CPU核数；若设置为非法值，则取默认值CPU核数的一半。
可选
离线解析接口支持多性能数据目录并行解析，当性能数据量较大且数据目录较多的情况下，可能因环境内存不足导致解析失败，此时可以通过自定义最大进程数（max_process_number）来控制资源的占用。
- 保存文件后执行如下命令解析性能数据：
python3 {file_name}.py - 解析完成后请参见《MindStudio Ascend Insight用户指南》进行数据分析。