diff --git "a/debug/accuracy_tools/ptdbg_ascend/doc/ptdbg_ascend\347\262\276\345\272\246\345\267\245\345\205\267\345\212\237\350\203\275\350\257\264\346\230\216_v4.0.T3.md" "b/debug/accuracy_tools/ptdbg_ascend/doc/ptdbg_ascend\347\262\276\345\272\246\345\267\245\345\205\267\345\212\237\350\203\275\350\257\264\346\230\216_v4.0.T3.md" index 120c70cddb231b9791a25c8279a4231a3633bd02..2d4207904a302df87d6f82db89ef0414ddd7b107 100644 --- "a/debug/accuracy_tools/ptdbg_ascend/doc/ptdbg_ascend\347\262\276\345\272\246\345\267\245\345\205\267\345\212\237\350\203\275\350\257\264\346\230\216_v4.0.T3.md" +++ "b/debug/accuracy_tools/ptdbg_ascend/doc/ptdbg_ascend\347\262\276\345\272\246\345\267\245\345\205\267\345\212\237\350\203\275\350\257\264\346\230\216_v4.0.T3.md" @@ -55,23 +55,23 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 ```python from ptdbg_ascend import * - + # 在main函数开始前固定随机数 seed_all() - + # 配置dump数据目录路径和名称 set_dump_path("./npu_dump", dump_tag='all') - + # 注册dump回调函数 register_hook(model, acc_cmp_dump) - + ... - + # 在第一个迭代开始的位置开启dump和堆栈模式，同时为保证数据完整性开启dump bool和整型的tensor以及浮点、bool和整型的标量 set_dump_switch("ON", mode="api_stack", filter_switch="OFF") - + ... - + # 在第一个迭代结束的位置关闭dump set_dump_switch("OFF") ``` @@ -118,7 +118,7 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 ```python from ptdbg_ascend import * - + # 提取dump信息中第1次调用的API：Torch_batch_normal的堆栈信息及数据统计信息 parse("./npu_dump/all_v2.0/rank0/api_stack_dump.pkl", "Torch_batch_normal_1_forward") ``` @@ -129,7 +129,7 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 python3 parse.py ``` - + 5. （可选）指定API dump数据。 @@ -137,17 +137,17 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 ```python from ptdbg_ascend import * - + # 固定随机数，开启确定性计算 seed_all(mode=True) set_dump_path("./dump_path", dump_tag='forward') register_hook(model, acc_cmp_dump, dump_mode='acl', dump_config='./dump.json') - + # dump指定前向API的ACL级别数据、bool和整型的tensor以及浮点、bool和整型的标量 set_dump_switch("ON", mode="acl", scope=["Tensor_permute_1_forward"], filter_switch="OFF") - + ... - + set_dump_switch("OFF") ``` @@ -155,18 +155,18 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 ```python from ptdbg_ascend import * - + # 固定随机数，开启确定性计算 seed_all(mode=True) set_dump_path("./dump_path", dump_tag='backward') register_hook(model, acc_cmp_dump, dump_mode='acl', dump_config='./dump.json') - + # dump指定反向API的ACL级别数据、bool和整型的tensor以及浮点、bool和整型的标量 set_dump_switch("ON", mode="acl", scope=["Functional_conv2d_1_backward"], filter_switch="OFF") set_backward_input(["./npu_dump/all_v2.0/rank0/api_stack_dump/Functional_conv2d_1_backward_input.0.npy"]) - + ... - + set_dump_switch("OFF") ``` @@ -185,20 +185,13 @@ PyTorch训练场景的精度问题分析建议参考以下思路进行精度比 说明：多机多卡场景需要每个设备单独执行比对操作。 -假设NPU dump npy数据目录为npu_dump/dump_conv2d_v3.0，GPU dump npy数据目录为gpu_dump/dump_conv2d_v3.0。 +假设NPU dump npy数据目录为npu_dump/dump_conv2d_v1.0，GPU dump npy数据目录为gpu_dump/dump_conv2d_v1.0。 1. 创建比对脚本，例如compare_distributed.py，拷贝如下代码。 ```python from ptdbg_ascend import * - compare_distributed('./npu_dump/dump_conv2d_v3.0', './gpu_dump/dump_conv2d_v3.0', './output') - ``` - - 若使用debugger方式dump数据，且配置了PrecisionDebugger模块的step参数，则compare_distributed指定到step目录层级，如下示例： - - ```python - from ptdbg_ascend import * - compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output') + compare_distributed('./npu_dump/ptdbg_dump_v2.0', './gpu_dump/ptdbg_dump_v2.0', './output') ``` 2. 执行比对： @@ -346,7 +339,7 @@ set_dump_switch("ON", mode="api_list", api_list=["distributed"]) ... # 设置检测到3次溢出后退出训练 register_hook(model, overflow_check, overflow_nums=3) - + ... ``` @@ -362,15 +355,15 @@ set_dump_switch("ON", mode="api_list", api_list=["distributed"]) ... # dump指定API的ACL级别溢出数据 register_hook(model, overflow_check, dump_mode='acl', dump_config='./dump.json') - + # 在期望溢出检测的step位置开始前打开溢出检测开关 set_overflow_check_switch("ON") - + ... - + # 在step结束的位置关闭溢出检测开关 set_overflow_check_switch("OFF") - + ... ``` @@ -386,12 +379,12 @@ set_dump_switch("ON", mode="api_list", api_list=["distributed"]) ... # 设置检测到3次溢出后退出训练 register_hook(model, overflow_check) - + ... ``` 2. dump指定反向API的ACL级别的溢出数据 - + ```python from ptdbg_ascend import * seed_all() @@ -424,9 +417,9 @@ set_dump_switch("ON", mode="api_list", api_list=["distributed"]) cd $ATT_HOME/debug/accuracy_tools/api_accuracy_checker/run_ut python run_overflow_check.py -forward ./forward_info_0.json ``` - + 反向过程溢出的API暂不支持精度预检功能。 - + 当重复执行溢出检测dump操作时，需要删除上一次dump目录下的溢出检测dump数据，否则将因重名而报错。 **注意事项** @@ -633,7 +626,7 @@ debugger.stop() debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="dump", step=[0,2], enable_dataloader=True) # 请勿将以上初始化流程插入到循环代码中 ``` - + - 示例2：开启溢出检测dump ```python @@ -652,18 +645,18 @@ debugger.stop() from ptdbg_ascend import * debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="dump", step=[0]) # 请勿将以上初始化流程插入到循环代码中 - + # 模型初始化 # 下面代码也可以用PrecisionDebugger.start()和PrecisionDebugger.stop() debugger.start() - + # 需要dump的代码片段1 - + debugger.stop() debugger.start() - + # 需要dump的代码片段1 - + debugger.stop() debugger.step() ``` @@ -674,23 +667,23 @@ debugger.stop() from ptdbg_ascend import * debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="overflow_check", step=[0]) # 请勿将以上初始化流程插入到循环代码中 - + # 模型初始化 # 下面代码也可以用PrecisionDebugger.start()和PrecisionDebugger.stop() debugger.start() - + # 需要dump的代码片段1 - + debugger.stop() debugger.start() - + # 需要dump的代码片段1 - + debugger.stop() debugger.step() ``` -## CPU或GPU及NPU精度数据dump +## CPU或GPU及NPU精度数据dump ### 总体说明 @@ -702,12 +695,12 @@ debugger.stop() - 工具性能：dump数据量较小时（小于5G），参考dump速度0.1GB/s；dump数据量较大时，参考dump速度0.2GB/s。 推荐环境配置：独占环境，CPU核心数192，固态硬盘（IO速度参考：固态硬盘 > 500MB/s，机械硬盘60 ~ 170MB/s）。 - + 用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。Dump速度的计算方式：Dump数据量/(单个step添加Dump耗时-原始单个step耗时）。 ### 约束 - 进行CPU或GPU数据dump时，请安装torch包而非torch_npu包，避免工具无法识别使用场景，导致失败。 - + - TASK_QUEUE_ENABLE环境变量会导致API下发和执行异步进行，因此在ACL dump前需要将TASK_QUEUE_ENABLE关闭，即export TASK_QUEUE_ENABLE=0。 - 不建议在PyTorch训练脚本中同时添加dump接口和性能数据采集（如Ascend PyThon Profiler）接口，二者可能相互影响导致数据不准确。 @@ -988,13 +981,13 @@ set_dump_switch可配置多种dump模式，示例如下： ``` 配置filter_switch="OFF"同时也可以配置mode、scope和api_list，除dump ACL级别数据。 - + - 示例8：仅保存dump的数据文件名包含“backward”的反向.npy文件 ```python set_dump_switch("ON", dump_mode=["backward"]) ``` - + - 示例9：仅dump pkl文件 ```python @@ -1071,9 +1064,9 @@ set_overflow_check_switch(switch, filter_switch='OFF') ```python register_hook(model, overflow_check) set_overflow_check_switch("ON") - + ... - + set_overflow_check_switch("OFF") ``` @@ -1084,15 +1077,15 @@ set_overflow_check_switch(switch, filter_switch='OFF') ```python register_hook(model, overflow_check, dump_mode='acl', dump_config='./dump.json') set_overflow_check_switch("ON") - + ... - + set_overflow_check_switch("OFF") ``` 该场景set_dump_path不生效，由dump_config中的dump.json文件配置溢出数据目录。 -### set_backward_input +### set_backward_input **功能说明** @@ -1167,7 +1160,7 @@ set_backward_input(["./npu_dump/dump_conv2d_v2.0/rank0/dump/Functional_conv2d_1_ │   └── TransData.trans_TransData_3.37.0.1675157077169473 ``` -## 模块级精度数据dump +## 模块级精度数据dump ### 总体说明 @@ -1235,17 +1228,17 @@ class ModuleOP(nn.Module): x2 = self.linear_2(x1) r1 = F.relu(x2) return r1 - + if __name__ == "__main__": module = ModuleOP() - + # 注册工具 set_dump_path("./dump_data/npu") set_dump_switch("ON") register_hook(module, acc_cmp_dump) - + x = torch.randn(2, 2) - + module_dump(module, "MyModule") # 开启模块级精度数据dump out = module(x) module_dump_end() # 结束模块级精度数据dump @@ -1271,14 +1264,12 @@ dump结果目录结构示例如下： │ ├── rank1 | | ├── dump | | | └── ... -| | └── dump.pkl +| | └── dump.pkl │ ├── ... │ | | └── rank7 ``` -dump过程中，npy文件在对应算子或者模块被执行后就会落盘，而pkl文件则需要在正常执行PrecisionDebugger.stop()或set_dump_switch("OFF")后才会被落盘保存，异常的程序终止会保存终止前被执行算子的相关npy文件，但是不会生成pkl文件。 - 其中ptdbg_dump_{version}为未设置set_dump_path的dump_tag参数时的默认命名；rank为设备上各卡的ID，每张卡上dump的数据会生成对应dump目录。 当使用debugger方式dump数据时，配置了PrecisionDebugger模块的step=[]参数，dump结果目录则以step为父目录，例如配置step=[0,1,2]时，dump结果目录为： @@ -1335,13 +1326,13 @@ register_hook设置了overflow_check时，检测API溢出，dump结果的文件 - 工具性能：比对数据量较小时（参考值单份文件小于10GB），参考比对速度0.1GB/s；比对数据量较大时，参考比对速度0.3GB/s。 推荐环境配置：独占环境，CPU核心数192，固态硬盘（IO速度参考：固态硬盘 > 500MB/s，机械硬盘60 ~ 170MB/s）。 - + 用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。比对速度的计算方式：两份比对文件大小/比对耗时。 ### 约束 - NPU自研API，在CPU或GPU若没有对应的API，该API的dump数据不比对。 - + - NPU与CPU或GPU的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个API因为输入的数据差异较大而无法比对的情况。 - CPU或GPU与NPU中两个相同的API会因为调用次数不同导致无法比对或比对到错误的API，不影响整体运行，该API忽略。 @@ -1392,7 +1383,7 @@ compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_mat | 参数名 | 说明 | 是否必选 | | ------------ | ------------------------------------------------------------ | -------- | -| input_param | 配置dump数据文件及目录。配置参数包括：
- "npu_pkl_path"：指定NPU dump目录下的.pkl文件。参数示例："npu_pkl_path": "./npu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump.pkl"。必选。
- "bench_pkl_path"：指定CPU、GPU或NPU dump目录下的.pkl文件。参数示例："bench_pkl_path": "./gpu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump.pkl"。必选。
- "npu_dump_data_dir"："指定NPU dump目录下的dump数据目录。参数示例："npu_dump_data_dir": "./npu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump"。可选，仅比对pkl文件时不选。
- "bench_dump_data_dir"："指定CPU、GPU或NPU dump目录下的dump数据目录。参数示例："npu_dump_data_dir": "./gpu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump"。可选，仅比对pkl文件时不选。
- "is_print_compare_log"：配置是否开启日志打屏。可取值True或False。可选。 | 是 | +| input_param | 配置dump数据文件及目录。配置参数包括：
- "npu_pkl_path"：指定NPU dump目录下的.pkl文件。参数示例："npu_pkl_path": "./npu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump.pkl"。必选。
- "bench_pkl_path"：指定CPU、GPU或NPU dump目录下的.pkl文件。参数示例："bench_pkl_path": "./gpu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump.pkl"。必选。
- "npu_dump_data_dir"："指定NPU dump目录下的dump数据目录。参数示例："npu_dump_data_dir": "./npu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump"。必选。
- "bench_dump_data_dir"："指定CPU、GPU或NPU dump目录下的dump数据目录。参数示例："npu_dump_data_dir": "./gpu_dump/ptdbg_dump_v2.0/rank0/api_stack_dump"。必选。
- "is_print_compare_log"：配置是否开启日志打屏。可取值True或False。可选。 | 是 | | output_path | 配置比对结果csv文件存盘目录。参数示例：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.csv`。 | 是 | | stack_mode | 配置stack_mode的开关。仅当dump数据时配置set_dump_switch的mode="api_stack"时需要开启。参数示例：stack_mode=True，默认为False。 | 否 | | auto_analyze | 自动精度分析，开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。可取值True或False，参数示例：auto_analyze=False，默认为True。 | 否 | @@ -1471,14 +1462,31 @@ PyTorch精度比对是以CPU或GPU的计算结果为标杆，计算Cosine（余 ptdbg_ascend.parse为命令行交互式界面解析工具，提供更多的数据解析功能并且展示结果。 -主要的使用场景包括： +### 进入parse交互式界面 + +安装ptdbg_ascend工具后，可以通过使用命令 **python -m ptdbg_ascend.parse** 进入交互式界面，如下所示： + +```bash +python -m ptdbg_ascend.parse +Parse >>> +``` + +可在parse的界面中执行Shell命令，以及如下场景的相关解析命令： - 支持指定ACL层级算子数据比对。 - 支持指定ACL层级算子数据转换及展示。 - 支持交互式指定pkl文件中API对应dump数据查看。 - 支持API进行可选层级比对和打印（统计级和像素级）。 -安装ptdbg_ascend工具后，可以通过使用命令 **python -m ptdbg_ascend.parse** 进入交互式界面，可在parse的界面中执行Shell命令，以及上述场景的相关解析命令。Ctrl+C可以退出该界面。 +Ctrl+C可以退出parse交互式界面。不退出parse交互式界面若需要执行非该界面下的内置Shell命令，且命令与parse交互式界面命令冲突时，非该界面命令需要使用run命令，在相关命令前加上run前缀，如下示例： + +```bash +python -m ptdbg_ascend.parse +Parse >>> run vim cli.py +Parse >>> vim cli.py +``` + +以上各场景详细介绍请参见下文章节。 ### ACL层级算子数据比对 @@ -1489,14 +1497,14 @@ ptdbg_ascend.parse为命令行交互式界面解析工具，提供更多的数 ```bash vc -m my_dump_path -g golden_dump_path [-out output_path] ``` - - | 参数名称 | 说明 | 是否必选 | - | -------- | ------------------------------------------------------------ | -------- | - | -m | 待比对dump数据目录。 | 是 | - | -g | dump数据目录。 | 是 | - | -out | 结果输出目录。 | 否 | - | -asc | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py。 | 否 | - + + | 参数名称 | 说明 | 是否必选 | + | --------- | ------------------------------------------------------------ | -------- | + | -m | 待比对dump数据目录。 | 是 | + | -g | dump数据目录。 | 是 | + | -out | 结果输出目录。 | 否 | + | -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py。 | 否 | + - 输出结果：result_{timestamp}.csv文件。 - 若指定-out参数需要用户传入输出路径，并且路径需要已存在。 - 若未指定输出目录， 则比对结束后将结果保存在默认目录 “./parse_data/comapre_result”中，比对结束后会打印log提示输出结果存放路径。 @@ -1505,7 +1513,7 @@ ptdbg_ascend.parse为命令行交互式界面解析工具，提供更多的数 ```bash # 传入待比对数据目录以及标杆数据目录 -Parse >>> vc -m ./my_dump_path -g ./golden_data_path +Parse >>> vc -m ./my_dump_path -g ./golden_data_path ...... # 比对结果打印 [INFO] The comparison result have been written to "./parse_data/compare_result/result_20230818104735.csv". @@ -1523,12 +1531,12 @@ Parse >>> vc -m ./my_dump_path -g ./golden_data_path dc -n file_name/file_path [-f format] [-out output_path] ``` - | 参数名称 | 说明 | 是否必选 | - | -------- | ------------------------------------------------------------ | -------- | - | -n | 需转换的dump数据文件或dump数据文件目录。 | 是 | - | -f | 开启format转换，指定该参数时需要配置format格式，若未指定该参数，则直接转换为npy格式。 | 否 | - | -out | 结果输出目录。 | 否 | - | -asc | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | + | 参数名称 | 说明 | 是否必选 | + | --------- | ------------------------------------------------------------ | -------- | + | -n | 需转换的dump数据文件或dump数据文件目录。 | 是 | + | -f | 开启format转换，指定该参数时需要配置format格式，若未指定该参数，则直接转换为npy格式。 | 否 | + | -out | 结果输出目录。 | 否 | + | -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | [^]: 若传入单个dump文件，则转换单个文件，若传入dump文件目录则转换目录下所有dump文件。 @@ -1546,7 +1554,7 @@ Parse >>> vc -m ./my_dump_path -g ./golden_data_path | -------- | ------------- | -------- | | -n | npy文件路径。 | 是 | - 打印统计信息：shape, dtype, max, min和mean。 + 打印统计信息：shape, dtype, max, min和mean。默认在npy文件路径下将该数据保存为txt文件。 **示例1** @@ -1579,7 +1587,7 @@ Parse >>> pt -n ./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24 # 打印统计信息 [Shape: (1, 16, 56, 56, 16)] [Dtype: float16] [Max: 452.0] [Min: -408.5] [Mean: -3.809] Path: ./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy -TextFile:./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy.txt +TextFile:./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy.txt ``` ### pkl文件中指定API的dump数据信息查看 @@ -1632,9 +1640,9 @@ Statistic Info: | -al | 判定数据存在精度问题的绝对误差阈值，默认0.001。 | 否 | | -rl | 判定数据存在精度问题的相对误差阈值，默认0.001。 | 否 | | -s | 将npy文件保存成txt文件，用于查看，默认开启。 | 否 | - + 输出结果： - + - 统计级比对结果。 - 两个文件的统计信息（shape, dtype, max, min和mean）。 - 错误数据打印表格。 @@ -1660,7 +1668,7 @@ Parse >>> cn -m Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.16194941 │ 2246 │ -0.06376442 │ -0.06121233 │ 0.002552092 │ │ 9 │ -0.73746175 │ -0.73650354 │ 0.00095820427 │ └───────┴───────────────┴──────────────┴──────────────┘ └───────┴─────────────┴─────────────┴───────────────┘ ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ -│ Left: | +│ Left: | │ |- NpyFile: ./dump/temp/decode/Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.1619494134703053.output.0.npy | │ |- TxtFile: ./dump/temp/decode/Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.1619494134703053.output.0.npy.txt | │ |- NpySpec: [Shape: (32, 8, 8, 320)] [Dtype: float32] [Max: 5.846897] [Min: -8.368301] [Mean: -0.72565556] |