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

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”。

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 同理。