接口函数说明

set_dump_path

用于设置dump文件的路径(不包含文件名)。

• fpath：必选，设置dump数据的路径。参数示例：“/var/log/dump”。默认在指定的dump_path路径下生成ptdbg_dump_{version}目录，{version}为当前安装ptdbg_ascend工具版本，并在该目录下生成dump.pkl文件以及dump数据文件保存目录。当set_dump_switch函数配置了mode参数时，dump.pkl文件以及dump数据文件保存目录名称添加mode参数值为前缀。
• dump_tag：可选，设置dump数据目录名称。参数示例：dump_tag='dump_conv2d'。配置该参数会将生成的ptdbg_dump_{version}目录名称变更为dump_tag配置的值，如dump_conv2d_{version}。
  注意：

  • dump文件的路径需要是一个已存在的目录。
  • 若以相同路径和dump_tag运行多次，则会因为同名导致文件被覆盖。若希望保留多次dump数据，建议修改dump_tag后再进行dump。

set_dump_switch

设置dump范围。

• switch：必选，dump开关。可取值"ON"或"OFF"。在模型脚本选定dump开始的位置配置set_dump_switch("ON")。取值为“ON”时dump功能开启，取值为“OFF”时dump功能关闭。
• mode：可选，dump模式。可取值"list"、"range"、"stack"、"acl"、"api_list"、"api_stack"。默认为空。
• scope或api_list：可选，根据model配置的模式选择dump的API范围，默认为空。dump参数中指定的API数据。如果在scope中设置了两个API，则dump这两个API中间的所有API数据。
• filter_switch：可选，开启dump bool和整型的tensor以及浮点、bool和整型的标量。可取值"ON"或"OFF"。参数示例：filter_switch="OFF"。默认不配置，即filter_switch="ON"，表示不dump上述数据。
• dump_mode：dump数据过滤。可取值“all”、“forward”和“backward”，表示仅保存dump的数据中文件名包含“forward”或“backward”的前向或反向.npy文件。参数示例dump_mode='backward'。默认为all，即保存所有dump的数据。

详细dump模式说明和函数配置样例可参考数据dump模式说明。

seed_all

固定随机数。

• seed：可选，随机数种子。参数示例：seed=1000。默认种子为1234。
• mode：可选，确定性计算模式。可配置True或False。参数示例：mode=True。默认为False。即使在相同的硬件和输入下，API多次执行的结果也可能不同，开启确定性计算是为了保证在相同的硬件和输入下，API多次执行的结果相同。确定性计算会导致API执行性能降低，建议在发现模型多次执行结果不同的情况下开启。

set_backward_input

设置反向算子级别dump时需要的反向输入的路径。

backward_input：必选，该输入文件为首次运行训练dump得到反向API输入的.npy文件。该参数需配合set_dump_switch参数使用。

函数配置样例如下：

set_backward_input(["acl_dump_xxx//Functional_conv2d_1_backward_input.0.npy"])

更多样例可以参考单卡场景步骤5。

register_hook

用于注册dump回调函数或溢出检测。

• model：必选，torch.nn.Module类的模型对象。
• hook：必选，选择工具执行dump比对（acc_cmp_dump）或溢出检测（overflow_check）。取值为acc_cmp_dump或overflow_check。
• overflow_nums：可选，设置为N时表示在发生第N次溢出时停止训练。设置为overflow_check时可配置，默认值为1。
• dump_mode：可选，控制针对溢出API的dump模式。可取值"api"或"acl"。配置为“acl”时表示dump 算子级别的溢出数据，此时set_dump_path参数不生效，dump数据目录由dump_config的.json文件配置。默认为“api”。
• dump_config：算子级别dump的配置文件。dump_mode为"acl"时，该参数必选；dump_mode为"api"时，该参数不选。配置文件示例请参考dump.json配置示例。
• rank：可选，控制dump数据保存的rank目录名称。默认自动读取dump数据所属的卡，并保存在该卡对应的rank目录下，可参考dump文件目录结构。

进行dump比对时，函数的基础配置方法如下：

register_hook(model, acc_cmp_dump)

进行溢出检测时，函数的基础配置方法如下：

register_hook(model, overflow_check) 

溢出检测的更多样例可以参考溢出检测场景步骤2。

compare

将GPU/CPU/NPU的dump文件进行比对，仅支持比较单张卡dump下来的数据。

• input_param：必选，配置dump数据文件及目录，配置样例请参考比对脚本compare.py配置示例。
• output_path：必选，配置比对结果csv文件存盘目录。存盘目录需提前创建。
• stack_mode：可选，配置stack_mode的开关，仅当set_dump_switch的mode为"api_stack"时需要设置为True。默认为False。
• auto_analyze：可选，自动精度分析，开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因。可取值True或False，参数示例：auto_analyze=False，默认为True。
• suffix：可选，标识比对结果的文件名。配置的suffix值在比对结果文件名的compare_result和{timestamp}中间插入，例如：compare_result_{suffix}_{timestamp}。默认为空。
• fuzzy_match：可选，模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。可取值True或False，参数示例：fuzzy_match=True，默认为False。

parse

提取dump文件信息中的堆栈信息及数据统计信息。

• pkl_file：必选，指定dump数据文件中的pkl文件名。
• module_name_prefix：必选，指定待提取的API接口前缀。

compare_distributed

将GPU/CPU/NPU的dump文件进行比对，支持单卡和多卡，可同时比对多卡的dump数据。多机场景需要每个设备单独执行比对操作。可自动检索和匹配对应卡和进程所dump的数据文件，再进行比对。单机单卡时与compare函数二选一。

• npu_dump_dir：必选，配置NPU环境下的dump目录，即set_dump_path函数的dump_tag参数对应的目录名称。参数示例：'npu_dump/dump_conv2d_v1.0'。
• bench_dump_dir：必选，配置CPU、GPU或NPU环境下的dump目录，即set_dump_path函数的dump_tag参数对应的目录名称。参数示例：'gpu_dump/dump_conv2d_v1.0'。
• output_path：必选，配置比对结果csv文件存盘目录。
• **kwargs：可选，支持compare的所有可选参数。

set_overflow_check_switch

配置溢出检测范围。默认不配置该函数，全量进行溢出检测。仅支持NPU环境。

• switch：必选，检测开关。可取值"ON"或"OFF"。如果只在特定的step溢出检测，则在期望溢出检测的step位置开始前插入set_overflow_check_switch("ON")，在step结束的位置插入set_overflow_check_switch("OFF")。
• filter_switch：可选，开启dump bool和整型的tensor以及浮点、bool和整型的标量。可取值"ON"或"OFF"。参数示例：filter_switch="OFF"。默认不配置，即filter_switch="ON"，表示不dump上述数据。

npu_pkl_path

指定NPU dump目录下的.pkl文件。

bench_pkl_path

指定CPU、GPU或NPU dump目录下的.pkl文件。

npu_dump_data_dir

指定NPU dump目录下的dump数据目录。

bench_dump_data_dir

指定CPU、GPU或NPU dump目录下的dump数据目录。

is_print_compare_log

配置是否开启日志打屏，可选。