mindstudio-probe 1.0.3__py3-none-any.whl → 1.0.4__py3-none-any.whl

msprobe/docs/07.accuracy_checker_PyTorch.md

@@ -0,0 +1,274 @@
+# PyTorch 场景的离线精度预检
+
+## 1 简介
+
+**PyTorch 离线精度预检**<sup>a</sup>通过扫描昇腾 NPU 上用户训练模型中的所有 API，输出模型精度的诊断和分析结果。具体而言，该工具通过采集模型中所有 API 的前反向信息，构造相应的单元测试，将 NPU 输出与标杆（CPU 高精度）比对，从而计算对应的精度指标，该过程已封装为 run_ut.py 函数；将 NPU 环境下采集的预检数据拷贝至 GPU 环境，同样执行 run_ut.py；最后通过**新精度标准比对法**<sup>b</sup>将 NPU 和 GPU 的预检结果进行比对，从而找出 NPU 中存在精度问题的 API。同时，本工具支持随机生成模式和真实数据模式<sup>c</sup>。
+
+      a. 支持 PyTorch 版本：1.11/2.0/2.1/2.2；
+      b. 依据新精度标准，对不同的API采取不同的比对算法（包括绝对阈值法，标杆比对法、二进制一致法、ULP误差比对法和双千指标法），最终给定预检判定结果；
+      c. 在预检 dump 时可以选择由工具构造随机数获得 dump 数据或选择真实输入的数据进行预检 dump 操作。随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。
+
+## 2 离线预检流程
+
+1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
+2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。注意需要配置 level="L1"。
+3. 将 NPU 环境下 dump 的预检数据拷贝至 GPU 环境。
+4. 在 NPU 和 GPU 环境下分别执行 run_ut.py，生成的结果最终用于 api_precision_compare.py 函数的输入。详见 [3 离线预检操作指导](#3-离线预检操作指导)。
+5. 将 NPU 和 GPU 执行 run_ut.py 生成的 `accuracy_checking_details_{timestamp}.csv` 结果文件拷贝至同一环境下。
+6. 运行 api_precision_compare.py，输出结果为预检操作的最终结果。详见 [5 预检结果比对](#5-预检结果比对)章节。
+
+## 3 离线预检操作指导
+
+完成预检数据采集后，仅仅获取了 API 的输入数据，为了得到 NPU vs. CPU 高精度（标杆）的预检比对结果和 GPU vs. CPU 高精度（标杆）的预检比对结果，还需要进行 run_ut 操作。
+
+run_ut 预检操作包括以下两种方式：
+
+- 使用 run_ut.py 执行预检：适用于数据量较小的单卡场景。
+- 使用 multi_run_ut.py 执行多线程预检：适用于数据量较大的大模型场景。
+
+### 3.1 使用 run_ut.py 执行预检
+
+将 API 信息输入到 run_ut 模块进行精度检测并比对，运行如下命令： 
+
+```bash
+msprobe -f pytorch run_ut -api_info ./dump.json
+```
+
+   | 参数名称                     | 解释                                                         | 是否必选                           |
+   | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- |
+   | -api_info 或 --api_info_file   | 指定 API 信息文件 dump.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 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | run_ut 操作中断后继续执行场景下必须配置 |
+   | -f 或 --filter_api             | 过滤模型中除最大值和最小值以外其他参数和结构相同的 API。适用于模型较大且重复 API 较多的场景。 | 否                                 |
+   | -config 或 --config_path       | 指定离线预检操作过程中额外配置（包括黑名单、白名单等）的 [config.json](../config.json) 文件，默认未配置。config.json 文件的配置可参考[配置文件介绍](./02.config_introduction.md)。 | 否                                 |
+
+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` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见[ 4 预检结果](#4-预检结果)。
+   
+如果需要保存比对不达标的输入和输出数据，可以在 run_ut 执行命令结尾添加 `-save_error_data`，例如：
+
+```bash
+msprobe -f pytorch run_ut -api_info ./dump.json -save_error_data
+```
+
+数据默认会存盘到 './ut_error_data{timestamp}' 路径下（相对于启动 run_ut 的路径），如有需要，用户可以通过 error_data_path 参数来配置保存路径，error_data_path 参数在 [config.json](../config.json) 文件或 [config.yaml](../pytorch/api_accuracy_checker/config.yaml) 文件配置，config.json 文件需要在 run_ut 操作时通过 -config 参数指定，config.yaml 。
+
+#### 3.1.1 config.yaml 文件说明
+
+   config.yaml 文件可以通过配置参数来控制 dump 和 run_ut 操作的白名单、黑名单等功能。操作步骤如下：
+   
+   - config.yaml 文件通常位于类似 /home/xxx/miniconda3/envs/xxx/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml 的路径中。
+
+   - 进入 config.yaml 文件
+
+      ```bash
+      vim /home/xxx/miniconda3/envs/xxx/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml
+      ```
+
+   - 修改 config.yaml 文件参数。
+
+      ```yaml
+      white_list: []
+      black_list: []
+      error_data_path: './'
+      precision: 14
+      ```
+
+      | 参数名称        | 解释     | 是否必选 |
+      | ----------- | -----------| -------- |
+      | white_list      | API dump 白名单，仅对指定的 API 进行 dump。</br>**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置白名单，即 dump 全量 API 数据。 | 否       |
+      | black_list      | API dump 黑名单，被指定的 API 不进行 dump。</br>**配置示例**：black_list=["conv1d", "conv2d"]。默认未配置黑名单，即 dump 全量 API 数据。 | 否       |
+      | error_data_path | 配置保存精度未达标的 API 输入输出数据路径。</br>**配置示例**："error_data_path": "./"。默认为当前路径。 | 否       |
+      | precision       | 浮点数表示位数，默认取小数点后14位。                         | 否       |
+
+      说明：white_list 和 black_list 同时配置时，二者配置的 API 名单若无交集，则白名单生效，若 API 名单存在交集，则白名单排除的部分以及交集的 API 不进行 dump。
+
+#### 3.1.2 API 预检黑名单和白名单
+
+   run_ut 过程支持 API 预检黑名单和白名单，通过如下文件配置 black_list（黑名单）或white_list（白名单）参数来指定不需要或需要预检的API名称：
+
+   - 配置 [config.json](../config.json) 文件，该文件需要在 run_ut 操作时通过 -config 参数指定。
+
+   - config.json 文件的优先级高于 config.yaml 文件，即执行 config.json 文件时，config.yaml 文件的配置不生效。
+
+### 3.2 使用 multi_run_ut.py 执行多线程预检
+
+multi_run_ut.py 脚本，可以并行执行多个 run_ut 操作，从而减少预检耗时。示例如下：
+
+```bash
+msprobe -f pytorch multi_run_ut -api_info ./dump.json -n 32 -d 0 1 2 3
+```
+
+| 参数名称                     | 解释                                                         | 是否必选                           |
+| ---------------------------- | ------------------------------------------------------------ | ---------------------------------- |
+| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。                                   | 是                                 |
+| -save_error_data             | 保存精度未达标的 API 输入输出数据。                            | 否                                 |
+| -o 或 --out_path               | 指定 run_ut 执行结果存盘路径，默认“./”（相对于 run_ut 的路径）。 | 否                                 |
+| -j 或 --jit_compile            | 开启 jit 编译。                                                | 否                                 |
+| -n                           | 同时执行 run_ut 线程的数量，默认为 8，最大支持 64，但每个 Device 最大支持 8 个线程。当指定多个线程和多个 Device 时，线程数在每张卡上均分。 | 否                                 |
+| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0~7，共 8 个 Device。 | 否                                 |
+| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | run_ut 操作中断后继续执行场景下必须配置 |
+| -f 或 --filter_api             | 过滤模型中除最大值和最小值以外其他参数和结构相同的 API。适用于模型较大且重复 API 较多的场景。 | 否                                 |
+
+### 3.3 断点续检
+
+断点续检操作通过如下命令执行：
+
+```bash
+msprobe -f pytorch run_ut -api_info ./dump.json -csv_path /home/xxx/ut/accuracy_checking_result_{timestamp}.csv
+```
+
+精度预检 run_ut 过程中，若因环境、数据量过大等原因导致预检进程中断，那么当用户解决这些问题后，重新执行 run_ut 操作，可以通过断点续检操作继续前面未完成的预检，会在 -csv_path 指定的 `accuracy_checking_result_{timestamp}.csv` 文件以及对应的 `accuracy_checking_details_{timestamp}.csv` 文件中继续写入后续的结果，不会重新创建结果文件。
+
+须指定为上次预检中断的 `accuracy_checking_result_{timestamp}.csv` 文件。请勿修改 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件名，包括时间戳，否则断点续检会因无法识别到文件名而失败。
+
+## 4 预检结果
+
+精度预检生成的 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件示例如下：
+
+可以通过先查看 `accuracy_checking_result_{timestamp}.csv` 文件的 Forward Test Success 和 Backward Test Success，判断是否存在未通过测试的 API，再查看 `accuracy_checking_details_{timestamp}.csv` 文件的 API 详细达标情况，详细介绍请参见 [4.1 API 预检指标](#41-api-预检指标)。
+
+`accuracy_checking_result_{timestamp}.csv`
+
+![accuracy_checking_result](img/accuracy_checking_result.png)
+
+| 字段                  | 含义     |
+| --------------------- | ------------------------- |
+| API name              | API 名称。                    |
+| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。SKIP 表示跳过该 API 的计算，跳过原因在 Message 中说明。 |
+| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。如果是空白的话代表该 API 没有反向输出，SKIP 表示该 API 的某个参数的反向不计算梯度。 |
+| Message               | 提示信息。             |
+
+该结果为中间结果，仅作为参考，建议完成 [5 预检结果比对](#5-预检结果比对)后查看比对结果。该结果后续将会删除。
+
+Forward Test Success 和 Backward Test Success 是否通过测试是由 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差、双百双千双万指标判定结果决定的。
+
+需要注意的是 `accuracy_checking_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `accuracy_checking_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error，仅存在 waring 和 pass 且不存在 error 则标记 waring。
+
+`accuracy_checking_details_{timestamp}.csv`
+
+![accuracy_checking_details](img/accuracy_checking_details.png)
+
+| 字段                | 含义                                                         |
+| ------------------- | ------------------------------------------------------------ |
+| API name            | NPU 或 GPU下的 API 名称。       |
+| Bench Dtype         | 标杆数据的 API 数据类型。                                      |
+| DEVICE Dtype        | NPU 或 GPU 数据的 API 数据类型。      |
+| Shape               | API 的 Shape信息。           |
+| 余弦相似度          | NPU 或 GPU 数据与标杆数据的余弦相似度。       |
+| 最大绝对误差        | NPU 或 GPU 数据与标杆数据的最大绝对误差。   |
+| 双百指标            | 双百精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于百分之一的个数占总元素个数的比例。测试通过标准为相对误差大于百分之一的个数占总元素个数的比例小于百分之一。 |
+| 双千指标            | 双千精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。 |
+| 双万指标            | 双万精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于万分之一的个数占总元素个数的比例。测试通过标准为相对误差大于万分之一的个数占总元素个数的比例小于万分之一。 |
+| 二进制一致错误率    | NPU 或 GPU 数据中每个 Tensor 精度不一致的数值的数量与 Tensor 中数值数量的比值。只有数据是 builtin 类型（bool、int、float、str）、torch.bool 和 torch 的 int 类型或者在新精度标准中使用二进制一致算法进行比对的 API 才会展示。 |
+| 误差均衡性          | NPU 或 GPU 数据与标杆数据精度差的上下浮动情况。                 |
+| 均方根误差          | NPU 或 GPU 数据与标杆数据的均方根误差。                         |
+| 小值域错误占比      | NPU 或 GPU Tensor 中与标杆的绝对误差大于错误阈值的小值在小值域（小值的总数量）中的占比。判断为小值以及绝对误差的错误阈值参见 [4.2 小值域阈值](#42-小值域阈值)。 |
+| 相对误差最大值      | NPU 或 GPU 数据与标杆数据相对误差的最大值。         |
+| 相对误差平均值      | NPU 或 GPU 数据与标杆数据相对误差的平均值。            |
+| inf/nan 错误率       | NPU 与标杆 inf/nan 计算不一致的元素个数占总元素的个数比例。  |
+| 相对误差错误率      | NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。 |
+| 绝对误差错误率      | NPU 与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。 |
+| ULP 误差最大值       | NPU 或 GPU 数据与标杆数据 ULP 误差的最大值（取绝对值后）。        |
+| ULP 误差平均值       | NPU 或 GPU 数据与标杆数据ULP误差的平均值（取绝对值后）。  |
+| ULP 误差大于阈值占比 | NPU 或 GPU 数据与标杆数据的 ULP 误差（取绝对值后）大于阈值（当 NPU 或 GPU 数据类型为 float16 或 bfloat16 时，阈值为 1；当 NPU 或 GPU 数据类型为 float32 时，阈值为 32）的元素个数占总元素的个数比例。 |
+| Status              | API 预检通过状态，pass 表示通过测试，error 表示未通过，warning 表示测试未通过双千或双万精度指标，SKIP 表示该 API 的某个参数的反向不要计算梯度，所以没有任何计算过程，其他信息均为空。 |
+| message             | 提示信息。                     |
+
+**\***：
+
+### 4.1 API 预检指标
+   
+   API 预检指标是通过对 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差双百、双千、双万精度指标的数值进行判断，得出该 API 是否符合精度标准的参考指标。
+
+   API预检通过测试，则在`accuracy_checking_details_{timestamp}.csv`文件中的 Status 列标记 pass，否则标记 error 或 warning，详细规则如下：
+
+   - 余弦相似度 > 0.99：≤ 0.99 为不达标，标记 error，> 0.99 达标，进行下一步；
+   - 最大绝对误差 ＜ 0.001：＜ 0.001 达标，标记 pass，≥ 0.001 为不达标，进行下一步；
+   - 双百、双千、双万精度指标：
+     + 对于 float16 和 bfloat16 数据：双百指标不通过，标记 error；双百指标通过，双千指标不通过，标记 warning；双百、双千指标均通过，标记 pass。
+     + 对于 float32 和 float64 数据：双千指标不通过，标记 error；双千指标通过，双万指标不通过，标记 warning；双千、双万指标均通过，标记 pass。
+   - 在 `accuracy_checking_result_{timestamp}.csv` 中以 Forward Test Success 和 Backward Test Success 字段统计该算子前向反向输出的测试结果，对于标记 pass 的算子，则在 `accuracy_checking_result_{timestamp}.csv` 中标记 TRUE 表示测试通过，对于标记 error 或 warning 的算子，则在 `accuracy_checking_result_{timestamp}.csv` 中标记 FALSE 表示测试不通过。由于一个算子可能有多个前向或反向的输入或输出，那么该类算子的输入或输出中必须全为 pass，才能在 `accuracy_checking_result_{timestamp}.csv` 中标记 TRUE，只要有一个输入或输出标记 error 或 warning，那么在`accuracy_checking_result_{timestamp}.csv`中标记 FALSE。
+
+### 4.2 小值域阈值
+
+   判定为小值的阈值：
+
+   - torch.float32：e-6
+   - torch.float16：e-3
+   - torch.bfloat16：e-3
+
+   小值域的绝对误差阈值：
+
+   - torch.float32：e-9
+   - torch.float16：e-5
+   - torch.bfloat16：e-5
+
+## 5 预检结果比对
+
+需要同时获取 NPU 和 GPU 环境下 run_ut 操作的预检结果 `accuracy_checking_details_{timestamp}.csv` 文件。执行如下命令进行 NPU 和 GPU 预检结果的比对：
+
+```bash
+msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_details_{timestamp}.csv -gpu /home/xxx/gpu/accuracy_checking_details_{timestamp}.csv -o /home/xxx/
+```
+
+| 参数名称   | 说明               | 是否必选 |
+| -------------------- | ------------- | -------- |
+| -npu 或 --npu_csv_path | NPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否       |
+| -gpu 或 --gpu_csv_path | GPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否       |
+| -o 或 --out_path       | 指定 api_precision_compare.py 执行结果存盘路径，默认为当前目录。 | 否       |
+
+执行完成后输出 `api_precision_compare_result_{timestamp}.csv` 和 `api_precision_compare_details_{timestamp}.csv` 文件。文件示例如下：
+
+可以通过先查看 `api_precision_compare_result_{timestamp}.csv` 文件的 Forward Test Success 和 Backward Test Success，判断是否存在未通过测试的 API，再查看 `api_precision_compare_details_{timestamp}.csv` 文件的 API 详细达标情况。
+
+`api_precision_compare_result_{timestamp}.csv`
+
+![api_precision_compare_result](img/api_precision_compare_result.png)
+
+| 字段                  | 含义                                                         |
+| --------------------- | ------------------------------------------------------------ |
+| API name              | API 名称。                                                    |
+| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
+| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，如果是空白的话代表该 API 没有反向输出，SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
+| Message               | 提示信息。                   |
+
+Forward Test Success 和 Backward Test Success 是否通过测试是由 `api_precision_compare_details_{timestamp}.csv` 中的各个指标判定结果决定的。需要注意的是 `api_precision_compare_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `api_precision_compare_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error，仅存在 warning 和 pass 且不存在 error 标记 warning。
+
+`api_precision_compare_details_{timestamp}.csv`
+
+![api_precision_compare_details](img/api_precision_compare_details.png)
+
+| 字段                     | 含义                                                         |
+| ------------------------ | ------------------------------------------------------------ |
+| API name                 | NPU 或 GPU 下的 API 名称。        |
+| 小值域错误比值           | NPU 与 CPU 的小值域的错误比率 / GPU 与 CPU 的小值域的错误比率。标杆比对法指标。 |
+| 小值域错误判定结果       | 小值域错误比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。 |
+| 均方根误差比值           | NPU 与 CPU 的均方根误差 / GPU 与 CPU 的均方根误差。标杆比对法指标。  |
+| 均方根误差判定结果       | 均方根误差比值小于等于 1 标记为 pass，1~2 之间标记为 waring，大于 2 标记为 error。 |
+| 相对误差最大值比值       | NPU 与 CPU 的相对误差最大值 / GPU 与 CPU 的相对误差最大值。标杆比对法指标。 |
+| 相对误差最大值判定结果   | 相对误差最大值比值小于等于 1 标记为 pass，1 ~ 10 之间标记为 waring，大于 10 标记为 error。 |
+| 相对误差平均值比值       | NPU 与 CPU 的相对误差的平均值 / GPU 与 CPU 的相对误差的平均值。标杆比对法指标。 |
+| 相对误差平均值判定结果   | 相对误差平均值比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。 |
+| 误差均衡性比值           | NPU 与 CPU 的误差均衡性 / GPU 与 CPU 的误差均衡性。标杆比对法指标。  |
+| 误差均衡性判定结果       | 误差均衡性比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。该字段暂不参与 api_precision_compare_result 的结果判定。 |
+| inf / nan 错误率            | NPU 与标杆 inf / nan 计算不一致的元素个数占总元素的个数比例。绝对阈值法指标。 |
+| inf / nan 判定结果          | inf / nan 错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| 相对误差错误率           | NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。绝对阈值法指标。 |
+| 相对误差判定结果         | 相对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| 绝对误差错误率           | NPU 与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。绝对阈值法指标。 |
+| 绝对误差判定结果         | 绝对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| 二进制一致错误率         | NPU 或 GPU 数据中每个 Tensor 精度不一致的数值的数量与 Tensor 中数值数量的比值。只有数据是 builtin 类型（bool、int、float、str）、torch.bool 和 torch 的 int 类型或者在新精度标准中使用二进制一致算法进行比对的 API 才会展示。二进制一致法指标。 |
+| 二进制一致错误率判定结果 | 二进制一致错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
+| ULP 误差平均值            | NPU 数据与标杆数据 ULP 误差的平均值（取绝对值后）。ULP 误差比对法指标。 |
+| ULP 误差大于阈值占比      | NPU 数据与标杆数据的 ULP 误差（取绝对值后）大于阈值（当 NPU 数据类型为 float16 或 bfloat16 时，阈值为 1；当 NPU 数据类型为 float32 时，阈值为 32）的元素个数占总元素的个数比例。ULP 误差比对法指标。 |
+| ULP 误差大于阈值占比比值  | NPU 与 CPU 的 ULP 误差大于阈值占比 / GPU 与 CPU 的 ULP 误差大于阈值占比。ULP 误差比对法指标。 |
+| ULP 误差判定结果          | ULP 误差判定结果。<br/>     当 NPU 或 GPU 数据类型是 float16 或 bfloat16 时，以下两条标准满足其一标记为 pass，否则标记为 error：<br>          NPU ULP 误差大于阈值占比小于 0.001；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。<br/>     当 NPU 或 GPU 数据类型是 float32 时，以下三条标准满足其一标记为 pass，否则标记为 error：<br/>          NPU ULP 误差平均值小于 64；<br/>          NPU ULP 误差大于阈值占比小于 0.05；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。 |
+| 双千指标                 | 双千精度指标。是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。仅 conv1d 和 conv2d 使用该指标。双千指标法指标。 |
+| 双千指标判定结果         | 双千指标判定结果。双千指标大于 0.999 标记为 pass，否则标记为 error。 |
+| 比对结果                 | 综合所有指标的最终结果。如果比对指标中有 error，则标记为 error；有 warning，则标记为 warning；否则标记为 pass；SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
+| 比对算法                 | API 使用的比对算法，为标杆比对法、二进制一致法、绝对阈值法和 ULP 误差比对法中的一种。 |
+| Message                  | 提示信息。当前提示该 API 比对结果为 error 或 warning 时对应不符合标准的指标。 |

msprobe/docs/08.accuracy_checker_online_PyTorch.md

@@ -0,0 +1,198 @@
+# PyTorch 场景的在线精度预检
+
+## 1 简介
+
+为了应对大模型场景下，通过离线预检方式 dump API 输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行 NPU 训练操作的过程中，通过 TCP/IP 协议在 NPU
+Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择比对两方比对和三方比对。
+
+## 2 在线精度预检流程
+
+在线精度预检当前支持**局域网场景**和**共享存储场景**，请根据不同的场景选择对应的配置。
+
+在线精度预检操作流程如下：
+
+1. 准备 GPU 和 NPU 可正常运行的训练环境，PyTorch 版本大于等于2.0，并保证两台 Host 在同一局域网内可正常通信或能通过共享存储进行通信。
+2. GPU 和 NPU Host 设备上同时安装msprobe工具，详见[ msprobe 安装](./01.installation.md)章节，其中在线预检要安装 twisted、pyOpenSSL，这些包为 Python 模块。
+3. 分别配置 GPU 侧、NPU 侧的 config.json 文件。
+4. 在 GPU 侧运行 `msprobe -f pytorch run_ut -config ./config.json`。
+5. 在 NPU 侧配置训练脚本。
+6. 在 NPU 侧执行训练。
+
+## 3 在线精度预检操作指导
+
+### 3.1 配置 config.json 文件
+
+预检工具安装完成后，需要在 GPU 和 NPU 环境下分别配置 config.json。其中需要重点关注文件中的 is_online、is_benchmark_device、host 和 port 参数的配置，保障在线预检时 GPU 和 NPU 两台设备间的通信正常。
+
+#### 3.1.1 GPU 侧在线预检配置说明
+
+| 参数名称            | 说明           | 是否必选 |
+|-----------------|--------------|------|
+| task            | 任务名称，str 类型，配置为 run_ut 表示预检任务。通过其他字段 is_online 判断离线预检、在线预检任务。          | 是    |
+| white_list      | 预检的 API 白名单，list[str] 类型。<br/>**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置白名单，即预检全量 API 数据。       | 否    |
+| black_list      | 预检的 API 黑名单，list[str] 类型。<br/>**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置黑名单，即预检全量 API 数据。         | 否    |
+| error_data_path | 配置保存精度未达标的 API 输入输出数据路径，str 类型。在线预检模式下该参数不生效。         | 否    |
+| is_online       | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。              | 是    |
+| nfs_path        | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host、port 和 tls_path 不生效。   | 否    |
+| host            | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。            | 否    |
+| port            | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
+| rank_list       | 指定在线预检的 Rank ID，默认值为 [0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。 | 是    |
+| tls_path        | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥文件 server.key 和公钥文件 server.crt，str 类型，默认值为空，表示明文传输 api 数据，否则采用 TLS1.2 加密传输，加密传输时安全性较高，传输速率较低。      | 否    |
+
+
+#### 3.1.2 NPU 侧在线预检配置说明
+
+| 参数名称             | 说明           | 是否必选 |
+|------------------|-------------|------|
+| task             | 任务名称，str 类型，配置为 tensor 表示 dump API 统计信息和完全复刻整网的 API 运行情况的真实数据。通过字段 online_run_ut 判断是否使用在线预检功能。      | 是    |
+| dump_path        | dump 路径，str 类型，配置为合法路径即可，兼容 tensor 任务静态检查。       | 是    |
+| level            | dump 级别，str 类型，在线预检时配置为 L1，表示 dump API 级精度数据。在线预检可不配置，默认取值 L1。                                               | 是    |
+| rank             | 指定对某张卡上的数据进行 dump，list[int] 类型，默认未配置(表示 dump所有卡的数据)，需要与 GPU 侧配置项 rank_list 保持一致。   | 否    |
+| step             | 指定 dump 某个 step 的数据，list[int] 类型，默认未配置，表示 dump 所有 step 的数据。dump 特定 step 时，须指定为训练脚本中存在的 step。   | 否    |
+| seed             | 随机种子数，int 类型，默认值为 1234。通过固定随机数保证模型的输入或输出一致。      | 否    |
+| is_deterministic | 确定性计算模式，bool 类型，可取值 true（开启）或 false（关闭），默认关闭。     | 否    |
+| scope            | dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。    | 否    |
+| list             | dump 范围，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。 | 否    |
+| online_run_ut    | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。        | 是    |
+| nfs_path         | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效。     | 否    |
+| host             | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。     | 否    |
+| port             | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
+
+#### 3.1.3 局域网场景配置示例
+
+若采用TLS1.2协议加密传输api数据，需配置SSL证书，可参考如下生成自签名证书方法，仅供调试使用，生产环境请申请正式证书。
+```shell
+# 创建私钥文件server.key
+openssl genrsa -out server.key 2048
+
+# 创建签名请求文件server.csr
+openssl req -new -key server.key -out server.csr
+
+# 自签名, 生成1年期公钥文件server.crt
+openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
+```
+
+GPU 侧：
+
+```json
+{
+  "task": "run_ut",
+  "run_ut": {
+    "white_list": [],
+    "black_list": [],
+    "error_data_path": "./",
+    "is_online": true,
+    "nfs_path": "",
+    "host": "127.0.0.1",
+    "port": 59208,
+    "rank_list": [0]
+  }
+}
+```
+
+NPU 侧：
+
+```json
+{
+  "task": "tensor",
+  "dump_path": "./dump_path",
+  "rank": [0],
+  "step": [0],
+  "level": "L1",
+  "seed": 1234,
+  "is_deterministic": true,
+  "tensor": {
+    "scope": [],
+    "list": [],
+    "online_run_ut": true,
+    "nfs_path": "",
+    "host": "xx.xx.xx.x",
+    "port": 59208
+  }
+}
+```
+
+#### 3.1.4 共享存储场景配置示例
+
+GPU 侧：
+
+```json
+{
+  "task": "run_ut",
+  "run_ut": {
+    "white_list": [],
+    "black_list": [],
+    "error_data_path": "./",
+    "is_online": true,
+    "nfs_path": "/nfs/xxx/data",
+    "host": "",
+    "port": -1,
+    "rank_list": [0]
+  }
+}
+```
+
+NPU 侧：
+
+```json
+{
+  "task": "tensor",
+  "dump_path": "./dump_path",
+  "rank": [0],
+  "step": [0],
+  "level": "L1",
+  "seed": 1234,
+  "is_deterministic": true,
+  "tensor": {
+    "scope": [],
+    "list": [],
+    "online_run_ut": true,
+    "nfs_path": "/nfs/xxx/data",
+    "host": "",
+    "port": -1
+  }
+}
+```
+
+### 3.2 在 GPU 侧运行 run_ut
+
+由于 GPU 侧为通信接收端，需先于 NPU 侧执行 run_ut 操作，命令如下：
+
+```bash
+msprobe -f pytorch run_ut -config ./config.json
+```
+
+GPU 侧配置好 config.json 文件后执行 run_ut 命令，此时 GPU 处于预检等待状态：
+
+- 局域网场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到 GPU 侧时，GPU 启动预检操作。
+- 共享存储场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到共享存储时，GPU 启动预检操作。
+
+### 3.2 在 NPU 侧配置训练脚本
+
+在 NPU 训练脚本中添加如下代码以获取 run_ut 操作的预检 API 输入和输出数据：
+
+```python
+from msprobe.pytorch import PrecisionDebugger
+
+debugger = PrecisionDebugger("config.json")
+...
+
+debugger.start()
+
+...
+
+debugger.stop()
+debugger.step()
+```
+
+### 3.3 在 NPU 侧执行训练脚本
+
+配置完 NPU 侧训练脚本后即可执行训练脚本，命令示例如下：
+
+```bash
+bash train.sh
+```
+
+训练脚本执行完毕后，在GPU侧dump_path目录下生成比对结果文件，
+`accuracy_checking_result_{timestamp}_rank{rank_id}.csv`和`accuracy_checking_details_{timestamp}_rank{rank_id}.csv`记录两方比对结果
+`api_precision_compare_result_{timestamp}_rank{rank_id}.csv`和`api_precision_compare_details_{timestamp}_rank{rank_id}.csv`记录三方比对结果。详细介绍请参见[离线精度预检中的 **4 预检结果**](./07.accuracy_checker_PyTorch.md#4-预检结果)。

msprobe/docs/09.accuracy_checker_MindSpore.md

@@ -0,0 +1,68 @@
+# 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             | 提示信息。            |
+
+注意点：torch无法对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”。