Ascend PyTorch Profiler接口采集

add_metadata

添加字符串标记，可取值：

• key：字符串键。
• value：字符串值。

示例：

prof.add_metadata("test_key1", "test_value1")

add_metadata_json

添加json格式字符串标记，可取值：

• key：字符串键。
• value：字符串值，json格式。

示例：

prof.add_metadata_json("test_key2", [1, 2, 3])

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_modules

modules层级的Python调用栈，即框架层的调用信息，Bool类型。取值为：

• True：开启。
• False：关闭。默认值。

开启torch_npu.profiler.ProfilerActivity.CPU时生效。

否

with_flops

算子浮点操作，Bool类型（该参数暂不支持解析性能数据）。取值为：

• True：开启。
• False：关闭。默认值。

开启torch_npu.profiler.ProfilerActivity.CPU时生效。

否

experimental_config

扩展参数，通过扩展配置性能分析工具常用的采集项。支持采集项和详细介绍请参见experimental_config参数说明。

否

use_cuda

昇腾环境不支持。开启采集cuda性能数据开关，Bool类型。取值为：

• True：开启。
• False：关闭。默认值。

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。

torch_npu.profiler.schedule

设置不同step的行为。取值为：

• skip_first：采集前先跳过的step轮数，int类型。默认为值0。动态Shape场景建议跳过前10轮保证性能数据稳定；对于其他场景，可以根据实际情况自行配置。可选。
• wait：每次重复执行采集跳过的step轮数，int类型。必选。
• warmup：预热的step轮数，int类型，默认值为0。建议设置1轮预热。可选。
• active：采集的step轮数，int类型。必选。
• repeat：重复执行wait+warmup+active的次数，int类型。默认为值0，表示重复执行repeat不停止，建议配置为大于0的整数。可选。

建议根据此公式配置schedule：step总数 >= skip_first+(wait+warmup+active)*repeat

默认不执行该操作。

torch_npu.profiler.tensorboard_trace_handler

将采集到的性能数据导出为TensorBoard工具支持的格式。取值为：

• dir_name：string类型，采集的性能数据的输出目录。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。可选。若配置tensorboard_trace_handler函数后未指定具体路径，性能数据默认落盘在当前目录。

  若代码中未使用on_trace_ready=torch_npu.profiler.tensorboard_trace_handler，那么落盘的性能数据为原始数据，需要使用离线解析。

  该函数优先级高于ASCEND_WORK_PATH，具体请参见《环境变量参考》。

• worker_name：string类型，用于区分唯一的工作线程，默认为{hostname}_{pid}。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。可选。
• analyse_flag：bool类型，性能数据自动解析开关，可取值True（开启自动解析，默认值）、False（关闭自动解析，采集完后的性能数据可以使用离线解析）。

torch_npu.profiler._KinetoProfile不支持该函数。

torch_npu.profiler.ProfilerAction

Profiler状态，Enum类型。取值为：

• NONE：无任何行为。
• WARMUP：性能数据采集预热。
• RECORD：性能数据采集。
• RECORD_AND_SAVE：性能数据采集并保存。

torch_npu.profiler._ExperimentalConfig

性能数据采集扩展，Enum类型。通过torch_npu.profiler.profile的experimental_config调用，详细介绍请参见experimental_config参数说明。

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的性能数据结果文件类型。

activities

CPU、NPU事件采集列表。取值为：

• CPU：框架侧数据采集的开关。
• NPU：CANN软件栈及NPU数据采集的开关。

默认情况下两个开关同时开启。

否

prof_dir

采集的性能数据的输出目录。默认路径为：./。路径格式仅支持由字母、数字和下划线组成的字符串，不支持软链接。

否

analyse

性能数据自动解析开关，可取值：

• true：开启自动解析。
• false：关闭自动解析，即手动解析，采集完后的性能数据可以使用离线解析，默认值。

否

record_shapes

算子的InputShapes和InputTypes。取值为：

• true：开启。
• false：关闭，默认值。

activities配置为CPU时生效。

否

profile_memory

算子的内存占用情况。取值为：

• true：开启。
• false：关闭，默认值。

否

with_stack

算子调用栈。包括框架层及CPU算子层的调用信息。取值为：

• true：开启。
• false：关闭，默认值。

activities配置为CPU时生效。

否

with_flops

算子浮点操作（该参数暂不支持解析性能数据）。取值为：

• true：开启。
• false：关闭，默认值。

activities配置为CPU时生效。

否

with_modules

modules层级的Python调用栈，即框架层的调用信息。取值为：

• true：开启。
• false：关闭，默认值。

activities配置为CPU时生效。

否

experimental_config

扩展参数，通过扩展配置性能分析工具常用的采集项。详见experimental_config参数说明（dynamic_profile动态采集场景）。

否

active

配置采集的迭代数，取值为正整数，默认值为1。

否

export_type

设置导出的性能数据结果文件格式。可取值：

• text：表示解析为.json和.csv格式的timeline和summary文件，详见Ascend PyTorch Profiler接口采集数据。
• db：表示解析为一个汇总所有性能数据的.db格式文件（ascend_pytorch.db、analysis.db），使用MindStudio Insight工具展示。仅支持on_trace_ready接口导出和离线解析导出，需配套安装支持导出db格式的Ascend-cann-toolkit开发套件包，即CANN 8.0.RC1及以上版本。

设置无效值或未配置均取默认值Text。

profiler_level

msprof_tx

打点控制开关，通过开关开启自定义打点功能。可取值true（开启）或false（关闭），默认关闭。该参数使用请参见采集并解析msprof_tx数据（可选）。

data_simplification

数据精简模式，开启后将在导出性能数据后删除FRAMEWORK目录数据以及删除多余数据，仅保留ASCEND_PROFILER_OUTPUT目录和PROF_XXX目录下的原始性能数据，以节省存储空间。可取值true（开启）或false（关闭），默认开启。

aic_metrics

AI Core的性能指标采集项。可取值如下：

l2_cache

控制L2 Cache数据采集开关。可取值true（开启）或false（关闭），默认关闭。该采集项在ASCEND_PROFILER_OUTPUT生成l2_cache.csv文件，结果字段介绍请参见l2_cache（L2 Cache命中率）。

op_attr

控制采集算子的属性信息开关，当前仅支持采集aclnn算子，bool类型。可取值True（开启）或False（关闭），默认关闭。该参数采集的性能数据仅支持export_type=torch_npu.profiler.ExportType.Db时解析的db格式文件。torch_npu.profiler.ProfilerLevel.Level_none时，该参数不生效。

record_op_args

控制算子信息统计功能开关。可取值true（开启）或false（关闭），默认关闭。开启后会在{worker_name}_{时间戳}_ascend_pt_op_args目录输出采集到算子信息文件。

export_type

设置导出的性能数据结果文件格式，Enum类型。可取值：

• torch_npu.profiler.ExportType.Text：表示解析为.json和.csv格式的timeline和summary文件，详见Ascend PyTorch Profiler接口采集数据。
• torch_npu.profiler.ExportType.Db：表示解析为一个汇总所有性能数据的.db格式文件（ascend_pytorch.db、analysis.db），使用MindStudio Insight工具展示。仅支持on_trace_ready接口导出和离线解析导出，需配套安装支持导出db格式的Ascend-cann-toolkit开发套件包，即CANN 8.0.RC1及以上版本。

设置无效值或未配置均取默认值torch_npu.profiler.ExportType.Text。

profiler_level

msprof_tx

打点控制开关，通过开关开启自定义打点功能，bool类型。可取值True（开启）或False（关闭），默认关闭。该参数使用请参见采集并解析msprof_tx数据（可选）。

开启此功能时，不能同时配置torch_npu.profiler.ExportType.Db和torch_npu.profiler.ProfilerLevel.Level_none。

data_simplification

数据精简模式，开启后将在导出性能数据后删除FRAMEWORK目录数据以及删除多余数据，仅保留ASCEND_PROFILER_OUTPUT目录和PROF_XXX目录下的原始性能数据，以节省存储空间，bool类型。可取值True（开启）或False（关闭），默认开启。

aic_metrics

AI Core的性能指标采集项，Enum类型。可取值如下：

l2_cache

控制L2 Cache数据采集开关，bool类型。可取值True（开启）或False（关闭），默认关闭。该采集项在ASCEND_PROFILER_OUTPUT生成l2_cache.csv文件，结果字段介绍请参见l2_cache（L2 Cache命中率）。

op_attr

控制采集算子的属性信息开关，当前仅支持采集aclnn算子，bool类型。可取值True（开启）或False（关闭），默认关闭。该参数采集的性能数据仅支持export_type=torch_npu.profiler.ExportType.Db时解析的db格式文件。torch_npu.profiler.ProfilerLevel.Level_none时，该参数不生效。

record_op_args

控制算子信息统计功能开关，bool类型。可取值True（开启）或False（关闭），默认关闭。开启后会在{worker_name}_{时间戳}_ascend_pt_op_args目录输出采集到算子信息文件。