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

msprobe/docs/10.accuracy_compare_PyTorch.md

@@ -0,0 +1,245 @@
+# PyTorch 场景的精度比对
+
+## 1 简介
+
+- 本节主要介绍通过命令行和比对函数的方式进行 CPU 或 GPU 与 NPU 的精度数据比对，执行精度比对操作前需要先完成 CPU 或 GPU 与 NPU 的精度数据 dump，参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节。
+
+- msprobe 使用子命令 compare 进行比对，可支持单卡和多卡场景的精度数据比对。
+
+- 比对函数均通过单独创建精度比对脚本执行，可支持单卡和多卡场景的精度数据比对。
+
+- 工具性能：比对数据量较小时（单份文件小于 10 GB），比对速度 0.1 GB/s；比对数据量较大时，比对速度 0.3 GB/s。 推荐环境配置：独占环境，CPU 核心数 192，固态硬盘（IO 速度参考：固态硬盘 > 500 MB/s，机械硬盘 60 ~ 170 MB/s）。用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。比对速度的计算方式：两份比对文件大小/比对耗时。
+
+**使用场景**：
+
+- 同一模型，从 CPU 或 GPU 移植到 NPU 中存在精度下降问题，对比 NPU 芯片中的 API 计算数值与 CPU 或 GPU 芯片中的 API 计算数值，进行问题定位。
+- 同一模型，进行迭代（模型、框架版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的 API 计算数值，进行问题定位。
+
+**注意事项**：
+
+- NPU 自研 API，在 CPU 或 GPU 侧若没有对应的 API，该 API 的 dump 数据不比对。
+- NPU 与 CPU 或 GPU 的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个 API 因为输入的数据差异较大而无法比对的情况。
+- CPU 或 GPU 与 NPU 中两个相同的 API 会因为调用次数不同导致无法比对或比对到错误的 API，不影响整体运行，该 API 忽略。
+
+**API匹配条件**：
+
+进行精度比对时，需要判断CPU或GPU的API与NPU的API是否相同可比对，须满足以下匹配条件：
+
+- 两个API的名称相同，API命名规则：`{api_type}.{api_name}.{api调用次数}.{正反向}.{输入输出}.index`，如：Functional.conv2d.1.backward.input.0。
+- 两个API的输入输出Tensor数量和各个Tensor的Shape相同。
+
+通常满足以上两个条件，工具就认为是同一个API，成功进行API的匹配，后续进行相应的计算精度比对。
+
+## 2 精度比对操作指导
+
+### 2.1 命令行方式
+
+将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。
+
+请先参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
+
+**操作步骤**：
+
+1. 创建[比对文件](#211-比对文件)。
+
+2. 运行命令：
+
+   ```shell
+   msprobe -f pytorch compare -i ./compare.json -o ./output -s
+   ```
+
+   **参数说明**：
+
+   | 参数名               | 说明     | 是否必选 |
+   |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+   | -i 或 --input_path   | 指定[比对文件](#211-比对文件)。             | 是       |
+   | -o 或 --output_path  | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。     | 是       |
+   | -s 或 --stack_mode   | 配置 stack_mode 的开关。仅当[比对文件](#211-比对文件)配置 stack_path 需要开启。通过直接配置该参数开启，默认未配置，表示关闭。   | 否       |
+   | -c 或 --compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否       |
+   | -f 或 --fuzzy_match  | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。   | 否       |
+
+3. 查看比对结果，请参见 [3 精度比对结果分析](#3-精度比对结果分析)。
+
+#### 2.1.1 比对文件
+
+   以在当前目录创建 ./compare.json 为例。
+
+   - 单卡场景示例：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/dump.json",
+     "bench_path": "./bench_dump/dump.json",
+     "stack_path": "./npu_dump/stack.json",
+     "is_print_compare_log": true
+     }
+     ```
+
+   - 多卡场景示例：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/step0",
+     "bench_path": "./bench_dump/step0",
+     "is_print_compare_log": true
+     }
+     ```
+
+   **参数说明**：
+
+   | 参数名               | 说明                                                         | 是否必选           |
+   | -------------------- | ------------------------------------------------------------ | ------------------ |
+   | npu_path             | 配置 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是                 |
+   | bench_path           | 配置 CPU、GPU 或 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是                 |
+   | stack_path           | 配置 NPU dump 目录下的 stack.json 文件。数据类型：str。          | 单卡必选，多卡不选 |
+   | is_print_compare_log | 配置是否开启日志打屏。可取值 True 或 False。数据类型：bool      | 否                 |
+
+### 2.2 比对函数方式
+
+#### 2.2.1 compare_distributed 函数
+
+此函数将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。可自动检索和匹配对应卡和进程所 dump 的数据文件，再调用 compare 进行比对。单机单卡时与 compare 函数二选一。
+
+**函数原型**：
+
+```Python
+compare_distributed(npu_dump_dir, bench_dump_dir, output_path, **kwargs)
+```
+
+**参数说明**：
+
+| 参数名         | 说明                                                         | 是否必选 |
+| -------------- | ------------------------------------------------------------ | -------- |
+| npu_dump_dir   | 配置 NPU 环境下的 dump 目录。str 类型。dump 数据目录须指定到 step 级。<br/>**配置示例**：'./npu_dump/step0'。 | 是       |
+| bench_dump_dir | 配置 CPU、GPU 或 NPU 环境下的 dump 目录。str 类型。<br/>**配置示例**：'./gpu_dump/step0'。 | 是       |
+| output_path    | 配置比对结果文件存盘目录。需要预先创建 output_path 目录。str 类型。<br/>**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}-rank{cpu/gpu/npu_ID}_{timestamp}.xlsx`。 | 是       |
+| **kwargs       | 支持 compare 的所有可选参数。                                  | 否       |
+
+**函数示例**：
+
+```Python
+from msprobe.pytorch import *
+compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output')
+```
+
+#### 2.2.2 compare 函数
+
+此函数将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，仅支持单机单卡。
+
+**函数原型**：
+
+```Python
+compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_match=False)
+```
+
+**参数说明**：
+
+| 参数名       | 说明                                                         | 是否必选 |
+| ------------ | ------------------------------------------------------------ | -------- |
+| input_param  | 配置 dump 数据文件及目录，dict 类型。配置参数包括：<br>        "npu_json_path"：指定 NPU dump 目录下的 dump.json 文件。<br/>**配置示例**："npu_json_path": "./npu_dump/dump.json"。<br/>        "bench_json_path"：指定 CPU、GPU 或 NPU dump 目录下的 dump.json 文件。<br/>**配置示例**："bench_json_path": "./bench_dump/dump.json"。<br/>        "stack_json_path"：指定 NPU dump 目录下的 stack.json 文件。<br/>**配置示例**："stack_json_path": "./npu_dump/stack.json"。<br/>        "is_print_compare_log"：配置是否开启日志打屏。<br/>**配置示例**：True 或 False。 | 是       |
+| output_path  | 配置比对结果文件存盘目录，str 类型。<br/>**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是       |
+| stack_mode   | 配置 stack_mode 的开关，bool 类型。仅当配置 stack_json_path 时需要开启。<br/>**配置示例**：stack_mode=True，默认为 False。 | 否       |
+| auto_analyze | 自动精度分析，bool 类型。开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 advisor_{timestamp}.txt 文件）。<br/>**配置示例**：auto_analyze=False，默认为 True。 | 否       |
+| fuzzy_match  | 模糊匹配，bool 类型。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。<br/>**配置示例**：fuzzy_match=True，默认为 False。 | 否       |
+
+**函数示例**：
+
+单机单卡场景下创建比对脚本，例如 compare.py，拷贝如下代码，具体参数请根据实际环境修改。
+
+```Python
+from msprobe.pytorch import compare
+input_param={
+"npu_json_path": "./npu_dump/dump.json",
+"bench_json_path": "./bench_dump/dump.json",
+"stack_json_path": "./npu_dump/stack.json",
+"is_print_compare_log": True
+}
+compare(input_param, output_path="./output", stack_mode=True)
+```
+
+#### 2.2.3 统计量比对
+
+在使用 **compare** 或 **compare_distributed** 函数创建的比对脚本且在 [config.json](../config.json) 文件中配置 `"task": "statistics"` 时，可以进行统计量比对，此时比对 dump.json 文件中的统计信息，开启后的比对结果生成 Max diff、Min diff、Mean diff 和 L2norm diff，表示 NPU dump 数据中 API 的输入或输出与标杆数据输入或输出的最大值、最小值、平均值以及 L2 范数的差。可以通过该值判断 API 是否存在精度问题：当某个 API 的输入和输出的 Max diff、Min diff、Mean diff 和 L2norm diff 均为 0 或无限趋于 0，那么可以判断该 API 无精度问题，反之则可能存在精度问题。
+
+**比对脚本示例**：
+
+以 compare.py 为例：
+
+```Python
+from msprobe.pytorch import compare
+input_param={
+"npu_json_path": "./npu_dump/dump.json",
+"bench_json_path": "./bench_dump/dump.json",
+"stack_json_path": "./npu_dump/stack.json",
+"is_print_compare_log": True
+}
+compare(input_param, output_path="./output", stack_mode=True)
+```
+
+**统计量比对结果说明**：
+
+数据量比对同样生成 `compare_result_{timestamp}.xlsx` 和 `advisor_{timestamp}.txt` 文件。其中 `advisor_{timestamp}.txt` 主要对 `compare_result_{timestamp}.xlsx` 中可能存在精度问题（Result 为 Waring）的 API 提出定位建议；`compare_result_{timestamp}.xlsx` 主要有如下两种情况：
+
+- "summary_mode": "statistics" 时比对 dump.json 文件：
+
+  ![compare_result_pkl](img/compare_result_pkl.png)
+
+  上图是对 dump.json 文件中 NPU 及标杆 API 的统计信息进行比对，判断可能存在精度问题的 API，文件中记录 NPU 及标杆 API 的基本信息和统计信息，其中需要关注 Result 列，包含结果：Waring（NPU 与标杆统计信息的比对中存在相对误差大于 0.5，则需要重点检查该 API）；为空（相对误差小于等于 0.5，可以不需要重点关注，但不代表不存在精度问题）；Nan（表示统计信息数据没有匹配上）。
+
+- "summary_mode": "md5" 时比对 dump.json 文件：
+
+  ![compare_result_pkl_md5.png](img/compare_result_pkl_md5.png.png)
+
+  上图是对 dump.json 文件中 NPU 及标杆 API 的 MD5 信息进行比对，判断 API 数据的完整性，文件中记录 NPU 及标杆 API 的基本信息和 MD5 信息，其中需要关注 Result 列，包含结果：Pass（表示 NPU 与标杆的 MD5 值一致，即 API 数据完整）；Different（表示 NPU 与标杆的 MD5 值不一致，即 API 数据不完全一致，可以通过 NPU_Stack_Info 列 API 调用栈查询该 API 的详细信息）；Nan（表示 MD5 信息数据没有匹配上）。
+
+## 3 精度比对结果分析
+
+PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算精度评价指标判断 API 在运行时是否存在精度问题。
+
+- `advisor_{timestamp}.txt` 文件中给出了可能存在精度问题的 API 的专家建议，可直接打开查看。
+
+- `compare_result_{timestamp}.xlsx` 文件列出了所有执行精度比对的 API 详细信息和比对结果，示例如下：
+
+  ![compare_result](https://gitee.com/cai-weiwei1989/att_ptdbg/raw/master/debug/accuracy_tools/ptdbg_ascend/doc/img/compare_result.png)
+
+  可以从该结果文件中进行[判断计算精度达标情况](#31-判断计算精度达标情况)、[计算精度评价指标分析](#32-计算精度评价指标分析)以及[异常信息识别](#33-异常信息识别)等分析动作。
+
+### 3.1 判断计算精度达标情况
+
+精度比对结果 `compare_result_{timestamp}.xlsx` 文件中只需要通过 Accuracy Reached or Not 来判断计算精度是否达标，判断标准如下：
+
+1. Cosine < 0.99 且 MaxAbsError > 0.001 时，精度不达标，标记为 No。
+2. Cosine < 0.9，精度不达标，标记为 No。
+3. MaxAbsError > 1，精度不达标，标记为 No。
+4. 其余情况下记为精度达标，标记为 Yes。
+
+### 3.2 计算精度评价指标分析
+
+1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于 1 说明计算出的两个张量越相似，实际可接受阈值为大于 0.99。在计算中可能会存在 nan，主要由于可能会出现其中一个向量为 0。
+
+2. MaxAbsErr：当最大绝对误差越接近 0 表示其计算的误差越小，实际可接受阈值为小于 0.001。
+
+3. MaxRelativeErr：当最大相对误差越接近 0 表示其计算的误差越小。
+
+   当 dump 数据中存在 0 或 Nan 时，比对结果中最大相对误差则出现 inf 或 Nan 的情况，属于正常现象。
+
+4. One Thousandth Err Ratio（双千分之一）、Five Thousandths Err Ratio（双千分之五）精度指标：是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差大于千分之一、千分之五的比例占总元素个数的比例小于千分之一、千分之五。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。
+
+### 3.3 异常信息识别
+
+精度比对结果 `compare_result_{timestamp}.xlsx` 文件中对于存在异常信息的API会进行高亮处理：
+
+- 红色可能出现的情况有：
+  - NPU max 或 NPU min 信息中存在 nan/inf；
+  - Max diff存在大于1e+10的值；
+  - 统计数据中output的Max diff除以max(0.01, Bench max) > 0.5；
+  - 真实数据中One Thousandth Err Ratio的input > 0.9同时output < 0.6。
+- 黄色可能出现的情况有：
+  - Max diff的input与output都大于1，同时output比input大一个数量级以上；
+  - 统计数据Max diff除以max(0.01, Bench max)的output > 0.1同时input < 0.01；
+  - 真实数据One Thousandth Err Ratio的input - output > 0.1；
+  - 真实数据Cosine的input - output > 0.1。
+
+Shape为 [ ] 时，统计量列说明：
+
+当 NPU Tensor Shape 列为 [ ] 时，表示标量或 0 维张量，统计量列（NPU max、NPU min、NPU mean、NPU l2norm）展示相同的唯一元素。Bench 同理。

msprobe/docs/11.accuracy_compare_MindSpore.md

@@ -0,0 +1,202 @@
+# MindSpore 场景的精度比对
+
+## 1 简介
+
+msprobe精度比对工具主要用于如下场景：
+
+- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到API dump数据后，对这两个API dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到kernel dump数据后，对这两个kernel dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在两个不同版本的MindSpore动态图环境下，输入相同的训练数据，在分别得到cell dump数据后，对这两个cell模块进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API dump数据，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得cell dump数据，由用户指定可以比对的cell list，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+
+执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
+
+## 2 命令行方式
+
+精度比对工具目前使用方式为命令行形式。
+
+### 2.1 命令格式说明
+
+```shell
+msprobe -f mindspore compare -i ./compare.json -o ./output -s
+```
+
+**完整参数说明**
+
+| 参数名              | 说明                                                         | 是否必选 |
+| ------------------- | ------------------------------------------------------------ | -------- |
+| -i或--input_path    | 指定比对文件。比对文件内容及示例请参见[比对文件](#31-比对文件)或[比对文件（kernel）](#32-比对文件（kernel）)（比对文件（kernel）仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
+| -o或--output_path   | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：<br>        `compare_result_{timestamp}.xlsx`<br/>        `compare_result_{rank_id}_{step_id}_{timestamp}.xlsx`（仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
+| -s或--stack_mode    | 配置stack_mode的开关。仅当[比对文件](#31-比对文件)配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| -c或--compare_only  | 仅比对开关。该参数默认未配置，表示关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否       |
+| -f或--fuzzy_match   | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| -am或--api_mapping  | 跨框架比对。配置该参数时表示开启跨框架API比对功能。仅[跨框架的API比对](#25-跨框架的API比对)场景支持。 | 否       |
+| -cm或--cell_mapping | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件](#33-自定义映射文件)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景支持。 | 否       |
+
+### 2.2 不同版本下的全量API比对
+
+1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的API dump数据。
+
+2. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+3. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s
+   ```
+
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.3 不同版本下的全量kernel比对
+
+1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的kernel dump数据。
+
+2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#32-比对文件（kernel）)。
+
+3. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output
+   ```
+
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.4 不同版本下的cell模块比对
+
+1. 配置[config.json](../config.json)文件level配置为L0、task配置为tensor或statistics并指定需要dump的cell模块名。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore动态图精度数据的采集，得到不同框架版本的cell模块dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.5 跨框架的API比对
+
+1. 配置[config.json](../config.json)文件level配置为L1、task配置为tensor或statistics。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API精度数据的采集，得到两个框架的API dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -am
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.6 跨框架的cell模块比对
+
+1. 配置[config.json](../config.json)文件level配置为L0、task配置为tensor或statistics并指定需要dump的cell模块名。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下cell模块精度数据的采集，得到两个框架的cell模块dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm
+   ```
+
+   或
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm cell_mapping.yaml
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+## 3 附录
+
+### 3.1 比对文件
+
+以在当前目录创建./compare.json为例，单卡场景示例如下：
+
+
+  ```json
+{
+"npu_path": "./npu_dump/dump.json",
+"bench_path": "./bench_dump/dump.json",
+"stack_path": "./npu_dump/stack.json",
+"is_print_compare_log": true
+}
+  ```
+
+
+**参数说明**
+
+| 参数名               | 说明                                                         | 是否必选 |
+| -------------------- | ------------------------------------------------------------ | -------- |
+| npu_path             | 配置NPU环境下的dump.json文件（单卡场景）。跨框架场景指定为MindSpore的json文件。数据类型：str。 | 是       |
+| bench_path           | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）。 跨框架场景指定为PyTorch的json文件。数据类型：str。 | 是       |
+| stack_path           | 配置NPU dump目录下的stack.json文件。数据类型：str。          | 是       |
+| is_print_compare_log | 配置是否开启日志打屏。可取值true或false，默认为true。数据类型：bool | 否       |
+
+### 3.2 比对文件（kernel）
+
+仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持。
+
+以在当前目录创建./compare.json为例，示例如下：
+
+- 单卡场景：
+
+  ```json
+  {
+  "npu_path": "./npu_dump",
+  "bench_path": "./bench_dump",
+  "rank_id": [1],
+  "step_id": []
+  }
+  ```
+
+- 多卡场景：
+
+  ```json
+  {
+  "npu_path": "./npu_dump",
+  "bench_path": "./bench_dump",
+  "rank_id": [],
+  "step_id": []
+  }
+  ```
+
+
+**参数说明**
+
+| 参数名     | 说明                                                         | 是否必选 |
+| ---------- | ------------------------------------------------------------ | -------- |
+| npu_path   | 配置NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
+| bench_path | 配置CPU、GPU或NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
+| rank_id    | 配置比对的Rank ID。npu_path和bench_path目录下的dump文件需要存在对应Rank的数据。默认为空，表示比对所有Rank。可配置一个或多个Rank，多个Rank ID用逗号隔开，例如："rank_id": [1,2,3]。数据类型：list[int]。 | 否       |
+| step_id    | 配置比对的Step ID。npu_path和bench_path目录下的dump文件需要存在对应Step的数据。默认为空，表示比对所有Sank。可配置一个或多个Sank，多个Sank ID用逗号隔开，例如："step_id": [1,2,3]。数据类型：list[int]。 | 否       |
+
+### 3.3 自定义映射文件
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容格式：
+
+```yaml
+{cell_name}.{class_name}: {cell_name}.{class_name}
+```
+
+左侧为MindSpore框架cell模块的{cell_name}.{class_name}，右侧为PyTorch框架cell模块的{cell_name}.{class_name}。
+
+{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}_{cell_name}_{class_name}_{前向反向}.{index}.{input/output}.{参数序号}`
+
+文件内容示例：
+
+```yaml
+fc2.Dense: fc2.Linear
+conv1.Conv2d: conv3.Conv2d
+```

msprobe/docs/12.overflow_check_PyTorch.md

@@ -0,0 +1,79 @@
+# **PyTorch场景下的溢出检测**
+
+msprobe 工具在 PyTorch 场景下提供溢出数据采集功能和溢出数据解析功能，详细介绍见下方章节。
+
+## 1、溢出数据采集
+
+溢出数据采集能 dump 所有溢出的 API 或者 Module 的信息，包括前反向输入输出的统计值和实际运行数据信息。
+
+### 1.1 工具安装
+
+工具安装详见《[msprobe 使用手册](../README.md)》的“安装”章节
+
+### 1.2 接口介绍
+
+溢出检测功能提供的接口与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**1 接口介绍**"章节。
+其中 PrecisionDebugger 中的 task 或是 config.json 中的 task 需要指定为 **overflow_check**，详见[配置文件介绍](./02.config_introduction.md)中的
+"**1.1 通用配置介绍**"和"**1.5 task 配置为 overflow_check**"章节。
+
+### 1.3 示例代码
+
+溢出检测功能使用方式与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**2 示例代码**"章节。
+
+### 1.4 结果文件介绍
+
+溢出检测结果文件目录结构与含义与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**3 dump 结果文件介绍**"章节。
+
+### 1.5 其他说明
+
+溢出数据采集功能在昇腾 NPU 上支持饱和模式和 INF/NAN 模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品（如 910A），默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品（如 910B），默认为 INF/NAN 模式，且不建议使用饱和模式。
+
+INF/NAN 模式的使能方式如下：
+
+```Shell
+# 使能 CANN 侧 INF/NAN 模式
+export INF_NAN_MODE_ENABLE=1
+```
+
+## 2、溢出数据解析
+
+注：溢出数据解析目前只支持分析前向 API 输入未溢出，但输出溢出的场景。
+
+在第一步中采集到溢出数据后，可以使用溢出解析功能快速判断输入未溢出而输出溢出的 API 是正常溢出还是非正常溢出，从而帮您快速分析是否由 API 执行异常导致的溢出问题。
+同一个 API 用相同的输入数据在 CPU 设备和昇腾 NPU 设备上执行，若 CPU 和 NPU 均出现溢出，则认为该溢出是**正常溢出**；若 NPU 有溢出, 而 CPU 没有溢出则认为该溢出是**非正常溢出**。
+
+工具支持的 PyTorch 版本：1.11/2.0/2.1/2.2。
+
+操作步骤如下：
+
+1. 安装工具。
+
+   详见《[msprobe 使用手册](../README.md)》的“安装”章节。
+
+2. 执行溢出 API 解析操作。
+
+   ```bash
+   msprobe -f pytorch run_overflow_check -api_info ./dump.json
+   ```
+   
+| 参数名称                   | 说明                                 | 是否必选 |
+| -------------------------- |------------------------------------| -------- |
+| -api_info或--api_info_file | 指定采集下来的 API 信息文件 dump.json。        | 是       |
+| -j或--jit_compile          | 开启 jit 编译。                         | 否       |
+| -d或--device               | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为0。 | 否       |
+
+3. 结果说明。
+
+   如果 API 是**正常溢出**，会打印以下信息：
+
+    ```bash
+   The {api_name} overflow is a normal overflow.
+   ```
+
+    **非正常溢出**则会打印以下信息：
+
+    ```bash
+   The {api_name} overflow is an abnormal overflow.
+   ```
+
+   其中 {api_name} 是对应溢出的 API 名称。

msprobe/docs/13.overflow_check_MindSpore.md

@@ -0,0 +1,31 @@
+# MindSpore 场景的溢出检测
+
+msprobe 工具提供静态图O2编译等级下的过程溢出检测与动态图场景下的结果溢出检测。其中前者检测对象为 kernel 级别，对应 config.json 配置中的 "L2" level，后者检测对象为 API 级别，对应 config.json 配置中的 "L1" level。
+
+需要注意，动态图场景下的溢出检测功能仅支持 INF/NAN 模式<sup>a</sup>。INF/NAN 模式的使能方式如下：
+
+```Shell
+# 使能 CANN 侧 INF/NAN 模式
+export INF_NAN_MODE_ENABLE=1
+# 使能 MindSpore 框架侧 INF/NAN 模式
+export MS_ASCEND_CHECK_OVERFLOW_MODE="INFNAN_MODE"
+```
+
+**a**：INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品（如 910A），默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2训练系列产品（如 910B），默认为 INF/NAN 模式，且不建议使用饱和模式。对于 MindSpore 框架侧配置，仅支持对 Atlas A2 训练系列产品进行设置，默认为 INF/NAN 模式。CANN 侧 与 MindSpore 框架侧配置须一致。
+
+溢出检测任务的配置示例见[MindSpore 静态图场景下 task 配置为 overflow_check](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#23-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-overflow_check)、[MindSpore 动态图场景下 task 配置为 overflow_check](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#33-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-overflow_check)。
+
+
+## 1 接口介绍
+
+溢出检测功能提供的接口与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**1 接口介绍**"章节。
+
+需要注意，目前暂不支持动态图 "L1" level 下 primitive op 的溢出检测。
+
+## 2 示例代码
+
+溢出检测功能使用方式与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**2 示例代码**"章节。
+
+## 3 溢出检测结果文件介绍
+
+溢出检测结果文件目录结构与含义与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**3 dump 结果文件介绍**"章节。