configure_hook
概述
设置dump范围。建议在PrecisionDebugger模块与模型初始化之间的任意位置添加，不添加此函数时默认使用mode="API_stack" dump整网数据。
接口原型
- Dump功能：
debugger.configure_hook(mode="API_stack", scope=[], API_list=[], filter_switch="ON", acl_config=None, backward_input=[], input_output_mode=["all"])
- 溢出检测功能：
debugger.configure_hook(mode=None, acl_config=None, overflow_nums=1)
表1 参数说明 参数名
说明
是否必选
mode
dump模式。可取值"all"、"list"、"range"、"stack"、"acl"、"API_list"、"API_stack"，各参数含义请参见接口示例。参数示例：mode="list"。默认为API_stack。该参数配置值将作为dump数据文件名的前缀，详情请参见《PyTorch模型迁移和训练指南》中的“dump数据存盘说明”。
否
scope或API_list
dump范围。根据model配置的模式选择dump的API范围，mode="API_list"时，需要配置API_list=[]，其他模式有需要时配置scope=[]。参数示例：scope=["Tensor_permute_1_forward"， "Tensor_transpose_2_forward"]、API_list=["relu"]。默认为空。
否
filter_switch
开启dump bool和整型的tensor以及浮点、bool和整型的标量。可取值"ON"或"OFF"。参数示例：filter_switch="OFF"。默认不配置，即filter_switch="ON"，表示不dump上述数据。
否
acl_config
acl dump的配置文件。mode="acl"时，该参数必选；mode为其他值时，该参数不选。参数示例：acl_config='./dump.json'。dump.json配置文件详细介绍请参见《PyTorch模型迁移和训练指南》中的“dump.json配置文件说明”。
否
backward_input
该输入文件为首次运行训练dump得到反向API输入的.npy文件。例如若需要dump Functional_conv2d_1 API的反向过程的输入输出，则需要在dump目录下查找命名包含Functional_conv2d_1、backward和input字段的.npy文件。
否
input_output_mode
dump数据过滤。可取值"all"、"forward"、"backward"、"input"和"output"，表示仅保存dump的数据中文件名包含"forward"、"backward"、"input"和"output"的前向、反向、输入或输出的.npy文件。参数示例input_output_mode=["backward"]或input_output_mode=["forward"， "backward"]。默认为all，即保存所有dump的数据。除了all参数只能单独配置外，其他参数可以自由组合。
否
overflow_nums
控制溢出次数，表示第N次溢出时，停止训练，过程中检测到溢出API对应ACL数据均dump。参数示例：overflow_nums=3。配置overflow_check时可配置，默认不配置，即检测到1次溢出，训练停止。
否
接口示例
configure_hook可配置多种dump模式，示例如下：
以下均以dump部分API数据为例，API名可以从首次dump整网数据的结果csv文件中的NPU Name或Bench Name列获取。
- 示例1：dump指定API列表。
debugger.configure_hook(mode="list", scope=["Tensor_permute_1_forward", "Tensor_transpose_2_forward", "Torch_relu_3_backward"])
- 示例2：dump指定范围。
debugger.configure_hook(mode="range", scope=["Tensor_abs_1_forward", "Tensor_transpose_3_forward"])
- 示例3：STACK模式，只dump堆栈信息。
debugger.configure_hook(mode="stack", scope=["Tensor_abs_1_forward", "Tensor_transpose_3_forward"])
- 示例4：dump指定前向API的ACL级别数据。
debugger.configure_hook(mode="acl", scope=["Tensor_permute_1_forward"], acl_config="./dump.json")
- 示例5：dump指定反向API的ACL级别数据。
debugger.configure_hook(mode="acl", scope=["Functional_conv2d_1_backward"], acl_config="./dump.json", backward_input=["./NPU_dump/dump_conv2d_v2.0/rank0/dump/Functional_conv2d_1_backward_input.0.npy"])
mode='acl'时scope列表仅允许填一个API名字。
- 示例6：dump指定某一类API的API级别输入输出数据。
debugger.configure_hook(mode="API_list", API_list=["relu"])
mode="API_stack"时不配置scope。
- 示例7：dump全部API级别输入输出数据以及相应堆栈信息。
debugger.configure_hook(mode="API_stack")
配置filter_switch="OFF"同时也可以配置mode、scope和API_list，除dump ACL级别数据。
- 示例8： dump全部API级别输入输出数据并包含bool和整型的tensor以及浮点、bool和整型的标量，默认不配置为ON，会过滤bool和整型数据。
debugger.configure_hook(filter_switch="OFF")
- 示例9：仅保存dump的数据文件名包含“backward”的反向.npy文件。
debugger.configure_hook(input_output_mode=["backward"])
- 示例10：溢出检测dump。
debugger.configure_hook(overflow_nums=1)
仅支持NPU环境，dump执行时会在PrecisionDebugger模块的dump_path参数指定的目录下生成ptdbg_dump_{version}目录，保存溢出数据。
多卡场景时，需要检测到至少有一张卡溢出次数达到overflow_nums时，训练结束。
- 示例11：dump指定API的ACL级别溢出数据。
debugger.configure_hook(mode="acl", acl_config="./dump.json")
仅支持NPU环境，该场景PrecisionDebugger模块的dump_path参数不生效，由acl_config中的dump.json文件配置溢出数据目录。