# MindSpore 动态图场景的离线精度预检

## 1 简介

**MindSpore 动态图精度预检**<sup>a</sup>通过扫描昇腾 NPU 上用户训练 MindSpore 模型中的所有 Mint API，输出精度情况的诊断和分析。工具以模型中所有 Mint API 前反向的 dump 结果为输入，构造相应的 API 单元测试，将 NPU 输出与标杆（CPU 高精度）比对，计算对应的精度指标，从而找出 NPU 中存在精度问题的 Mint API。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。

a. 支持 Mindspore 版本：2.4；

b. 在预检 dump 时可以选择由工具构造随机数进行输入获得 dump 数据或选择获取真实输入数据进行预检 dump 操作。随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。

## 2 离线预检流程

操作流程如下：

1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。详见 [MindSpore 场景下的数据采集](./06.data_dump_MindSpore.md)章节，注意需要配置 level="L1"。
3. 执行预检操作，查看预检结果文件，分析预检不达标的 API。

## 3 离线预检操作指导

命令如下：
```bash
msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result
```

| 参数名称     | 说明    |参数类型    | 是否必选     |
| ---------------------------- | --------------------------------------|---------------------- | ---------------------------------- |
| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。   |  str      | 是      |
| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。 |   str   | 否      |

预检执行结果包括 `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` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见 [4 预检结果](#4-预检结果)。

## 4 预检结果

精度预检生成的 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件内容详情如下：

`accuracy_checking_details_{timestamp}.csv`

| 字段      | 含义       |
| ------------------- | ------------------------------------------------------------ |
| API Name            | API 名称。                                        |
| Bench Dtype         | 标杆数据的 API 数据类型。      |
| Tested Dtype        | 被检验数据的 API 数据类型。                                  |
| Shape               | API 的 Shape 信息。       |
| Cosine              | 被检验数据与标杆数据的余弦相似度。                         |
| MaxAbsErr           | 被检验数据与标杆数据的最大绝对误差。                       |
| MaxRelativeErr      | 被检验数据与标杆数据的最大相对误差。                     |
| Status              | API 预检通过状态，pass 表示通过测试，error 表示未通过。 |
| message             | 提示信息。            |

注意：PyTorch 无法对 dtype 为整数类型的 tensor 进行反向求导，而 MindSpore 支持。反向过程的预检仅比较 dtype 为浮点型的输出。

`accuracy_checking_result_{timestamp}.csv`

| 字段                  | 含义      |
| --------------------- | ----------------- |
| API Name              | API 名称。         |
| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，error 为错误。 |
| Backward Test Success | 反向 API 是否通过测试，pass 为通过，error 为错误，如果是空白的话代表该 API 没有反向输出。 |
| Message               | 提示信息。         |

Forward Test Success 和 Backward Test Success 是否通过测试是由 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差判定结果决定的。具体规则详见 [4.1 API 预检指标](#41-api-预检指标)。
需要注意的是 `accuracy_checking_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `accuracy_checking_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error。

### 4.1 API 预检指标

   - API 预检指标是通过对 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差的数值进行判断，得出该 API 是否符合精度标准的参考指标。
   - 余弦相似度大于 0.99，并且最大绝对误差小于 0.0001，标记“pass”，否则标记为“error”。
