# **PyTorch NPU在线精度比对工具使用指南**

PyTorch NPU在线精度比对是msprobe工具实现在PyTorch训练过程中直接完成精度比对并输出比对结果的功能。

在线精度比对实现的是NPU与CPU之间的精度比对。

## PyTorch NPU在线精度比对总体流程

1. 准备NPU训练工程。

2. 在NPU环境下安装msprobe工具。

3. 在训练脚本内插入msprobe工具在线精度比对接口。

4. 执行训练并获取在线精度比对NPU和CPU分别执行后的精度比对结果。

5. 比对结果分析。

##  PyTorch NPU在线精度比对
### 总体说明
- 本节主要介绍NPU精度比对所需要的函数以及示例。
- 在线精度比对工具通过截获PyTorch框架中部分Aten Ir及其输入输出，并将输入数据转到CPU执行，最后将NPU和CPU的执行结果进行精度比对得到比对结果。

### 约束

- Pytorch 只支持2.0及其以上版本。
- 只支持Aten Ir级在线精度比对，所有Aten Ir可以通过dir(torch.ops.aten)查看，其中部分IR不支持在线比对：Aten Ir无对应CPU实现、NPU和CPU同AtenIR实现逻辑不一致，导致同输入不同输出。
- 正反向不支持同时在线精度比对，不支持跨step在线精度比对。


### 场景示例
1. 在NPU训练脚本中添加在线精度比对接口，示例如下：

   ```python
   from msprobe.pytorch.common import seed_all
   from msprobe.pytorch.online_dispatch import PtdbgDispatch
      
      # 在main函数开始前固定随机数
      seed_all()
      
     
      ...
      
      # 在需要调试精度的正向或反向代码前设置
      # 正向示例
      with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"):
           output = model_cpu(inputs)
      # 反向示例
      with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"):
       	loss.backward() 
   ```

2. 执行训练。

3. 找出精度不达标的Aten IR。

   执行过程中会打屏Failed，Failed在比对结果csv中的Accuracy Reached or Not列标记为No，并在Dump目录下存盘精度不达标Aten IR的输入输出。

### 计算精度评价指标

1. Cosine < 0.99 且 MaxAbsError > 0.001时，精度不达标；
2. Cosine < 0.9，精度不达标；
3. MaxAbsError > 1，精度不达标。

### 在线精度比对参数设置说明

| 参数名称 | 说明                                                                                              | 是否必选 |
| -------- |-------------------------------------------------------------------------------------------------| -------- |
| dump_mode| dump模式，可取值"all"、"list"、"auto"、"OFF"，默认值为OFF（表示不Dump数据）。                                         | 否       |
| api_list | dump范围，dump_mode="list"时设置，需要Dump Aten Ir API名称，默认为None，Aten Ir API名称可以通过dir(torch.ops.aten)查看。 | 否       |
| dump_path| dump文件生成的路径。                                                                                    | 是       |
| tag      | 传入tag字符串，成为dump文件夹名一部分，默认为None。                                                                 | 否       |
| process_num | 多进程并发数，默认为0。                                                                                    | 否       |
| debug       | debug信息打印，默认为False。                                                                             | 否       |
### dump数据存盘说明
dump数据存盘目录名格式：`atat_tag_rankid_{timestamp}`。

子目录下包含1个比对结果csv文件、cpu和npudump数据目录，npu目录下包含Aten IR在NPU上的输入输出的dump数据，由于CPU的输入是直接使用NPU的输入执行，因此cpu目录下只包含执行输出的dump数据。

```bash
atat_rank4_20230911170521
├── compare_result_rank4_20230911170521.csv
├── cpu
│   ├── native_batch_norm_backward_10_output.0.npy
│   ............
└── npu
    ├── native_batch_norm_backward_10_input.0.npy
    ............
```