昇腾训练工具链 针对训练、大模型场景，提供端到端命令行、可视化调试调优工具，帮助用户快速提高模型开发效率

# Ascend模型精度预检工具 Ascend模型精度预检工具能在昇腾NPU上扫描用户训练模型中所有API，输出精度情况的诊断和分析。工具会提取模型中所有的API前反向信息，构造相应的API单元测试，将NPU输出与标杆比对，从而检测出精度有问题的API。 工具支持PyTorch版本：1.8.1/1.11.0/2.0/2.1。 ## 工具特性 1. 落盘数据小 2. 不依赖标杆侧GPU训练资源，本地即可完成预检 3. 支持随机生成模式和真实数据模式 4. 单API测试，排除整网中的累计误差问题 ## 工具安装 1. 将att仓代码下载到本地，并配置环境变量。假设下载后att仓路径为 $ATT_HOME，环境变量应配置为： ```bash export PYTHONPATH=$PYTHONPATH:$ATT_HOME/debug/accuracy_tools/ ``` 2. 安装依赖tqdm、rich、pyyaml ```bash pip3 install tqdm rich pyyaml ``` ## 使用方式 1. 在训练脚本（如main.py）中加入以下代码导入工具dump模块，启动训练即可自动抓取网络所有API信息 - 如果训练脚本是通过torch.utils.data.dataloader方式加载数据，就可以在训练脚本中加入以下代码导入工具dump模块，启动训练即可自动抓取网络所有API信息 ```python import api_accuracy_checker.dump ``` 工具默认抓取训练的**第二个迭代**并且在第二个迭代后会报错退出训练进程，可通过target_iter参数配置。 **报错信息如下，这个报错仅用于停止训练，属于正常现象**： ```bash Exception: Model pretest: exit after iteration 1. ``` 若报错信息不一致，可能是由于服务器的其他错误信息覆盖导致，可以尝试查找报错信息中的Exception。 - 若训练脚本中的代码不是通过torch.utils.data.dataloader来加载数据或在部分流水并行、张量并行场景下，工具的开关无法在每张卡上自动打开，导致多卡训练dump结果只有一组json，那么需要在训练代码中添加打开工具开关的调用。 首先，需要关闭torch.utils.data.dataloader加载数据，操作如下： ```bash cd att/debug/accuracy_tools/api_accuracy_checker vi config.yaml # 修改enable_dataloader参数值为False ``` 其次，在训练代码中添加数据dump操作如下： ```Python import api_accuracy_checker.dump as DP # 需要先修改enable_dataloader参数值为False # 关闭torch.utils.data.dataloader加载数据时，下列代码须在训练step代码内添加 DP.dump.start() # 开启工具dump模块 ... DP.dump.stop() # 控制dump结束 DP.dump.step() # 在DP.dump.stop()后加入DP.dump.step()即可指定需要dump的step ``` 上述代码要添加在迭代前向的代码段中，或者说是遍历数据集循环的代码段中。如对于GPT-3可以添加在pretrain_gpt.py 的forward_step函数中。之后工具会适配这个场景开关的自动打开。 dump信息默认会存盘到“./step1”路径下（相对于启动训练的路径），包括： - forward_info_{pid}.json：前向API信息文件。 - backward_info_{pid}.json：反向API信息文件。 - stack_info_{pid}.json：调用栈信息文件。 forward_info与stack_info中的key值一一对应，用户可根据forward_info中API的key在stack_info中查询到其调用栈及代码行位置。 若有需要，用户可以通过msCheckerConfig.update_config来配置dump路径以及开启真实数据模式、指定dump某个step或配置API dump白名单，详细请参见“**msCheckerConfig.update_config**”。 2. 将API信息输入给run_ut模块运行精度检测并比对，运行如下命令： ```bash cd $ATT_HOME/debug/accuracy_tools/api_accuracy_checker/run_ut python run_ut.py -forward ./forward_info_0.json -backward ./backward_info_0.json ``` 某些场景下（如推理），可以不指定backward_info_0.json，不影响预检功能。 | 参数名称 | 说明 | 是否必选 | | -------------------------------- | ------------------------------------------------------------ | -------- | | -forward或--forward_input_file | 指定前向API信息文件forward_info_{pid}.json。 | 是 | | -backward或--backward_input_file | 指定反向API信息文件backward_info_{pid}.json。 | 否 | | -save_error_data | 保存精度未达标的API输入输出数据。 | 否 | | -o或--out_path | 指指定run_ut执行结果存盘路径，默认“./”（相对于run_ut的路径）。 | 否 | | -j或--jit_compile | 开启jit编译。 | 否 | | -d或--device | 指定Device ID，选择UT代码运行所在的卡，默认值为0。 | 否 | | -csv_path或--result_csv_path | 指定本次运行中断时生成的`accuracy_checking_result_{timestamp}.csv`文件路径，执行run_ut中断时，若想从中断处继续执行，配置此参数即可。 | 否 | run_ut执行结果包括`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`两个文件。`accuracy_checking_result_{timestamp}.csv`是API粒度的，标明每个API是否通过测试。建议用户先查看`accuracy_checking_result_{timestamp}.csv`文件，对于其中没有通过测试的或者特定感兴趣的API，根据其API name字段在`accuracy_checking_details_{timestamp}.csv`中查询其各个输出的达标情况以及比较指标。详细介绍请参见“**预检结果**”。 3. 如果需要保存比对不达标的输入和输出数据，可以在run_ut执行命令结尾添加-save_error_data，例如： ```bash python run_ut.py -forward ./forward_info_0.json -backward ./backward_info_0.json -save_error_data ``` 数据默认会存盘到'./ut_error_data'路径下（相对于启动run_ut的路径），有需要的话，用户可以通过msCheckerConfig.update_config来配置保存路径，参数为error_data_path。 ## msCheckerConfig.update_config **功能说明** 配置精度预检dump时的属性。 可选配置。 **函数原型** ```python msCheckerConfig.update_config(dump_path="./", real_data=False, target_iter=[1], white_list=[]) ``` **参数说明** | 参数名称 | 说明 | 是否必选 | | ----------- | ------------------------------------------------------------ | -------- | | dump_path | 设置dump路径，须为已存在目录，默认为当前目录。 | 否 | | real_data | 真实数据模式，可取值True或False，默认为False，表示随机数据模式，配置为True后开启真实数据模式，dump信息增加forward_real_data和backward_real_data目录，目录下保存每个API输入的具体数值。 | 否 | | target_iter | 指定dump某个step的数据，默认为[1]，须指定为训练脚本中存在的step。target_iter为list格式，可配置逐个step，例如：target_iter=[0,1,2]；也可以配置step范围，例如：target_iter=list(range(0,9))，表示dump第0到第8个step。 | 否 | | white_list | API dump白名单，指定dump具体API数据，也可以直接配置预检的API白名单，详细请参见“**API预检白名单**”。参数示例：white_list=["conv1d", "conv2d"]。默认未配置白名单，即dump全量API数据。 | 否 | **函数示例** - 示例1：配置dump路径以及开启真实数据模式 ```python from api_accuracy_checker.dump import msCheckerConfig msCheckerConfig.update_config(dump_path="my/dump/path", real_data=True) ``` - 示�