mindstudio-probe 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

msprobe/docs/08.accuracy_checker_online_PyTorch.md

@@ -49,8 +49,6 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | 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（关闭），默认关闭。        | 是    |
@@ -58,6 +56,7 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | host             | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。     | 否    |
 | port             | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
 | tls_path         | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥文件 client.key 和公钥文件 client.crt，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。 | 否    |
+| online_run_ut_recompute | 模型训练是否使用重计算机制，bool类型，默认为False，表示模型没有使用重计算。在线预检暂不支持重计算机制下反向算子的预检，当模型训练使用重计算时，跳过反向算子预检，默认模型关闭重计算。 | 否    |
 
 #### 3.1.3 局域网场景配置示例
 
@@ -114,8 +113,6 @@ NPU 侧：
   "rank": [0],
   "step": [0],
   "level": "L1",
-  "seed": 1234,
-  "is_deterministic": true,
   "tensor": {
     "scope": [],
     "list": [],
@@ -158,8 +155,6 @@ NPU 侧：
   "rank": [0],
   "step": [0],
   "level": "L1",
-  "seed": 1234,
-  "is_deterministic": true,
   "tensor": {
     "scope": [],
     "list": [],

msprobe/docs/09.accuracy_checker_MindSpore.md

@@ -6,30 +6,66 @@
 
 a. 支持 Mindspore 版本：2.4；
 
-b. 在预检 dump 时可以选择由工具构造随机数进行输入获得 dump 数据或选择获取真实输入数据进行预检 dump 操作。随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。
+b. 在预检时可以由工具构造随机数据或者获取真实dump数据进行预检操作。随机生成模式执行效率高，可以快速获得结果，但结果准确度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，并且需要较大磁盘空间存放待预检数据，但是结果准确度高，可以准确判断精度问题。
 
 ## 2 离线预检流程
 
 操作流程如下：
 
-1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
+1. 在 NPU 环境下安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。
 2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。详见 [MindSpore 场景下的数据采集](./06.data_dump_MindSpore.md)章节，注意需要配置 level="L1"。
 3. 执行预检操作，查看预检结果文件，分析预检不达标的 API。
 
 ## 3 离线预检操作指导
 
-命令如下：
+### 3.1 使用 run_ut 执行预检
+
+将 API 信息输入到 run_ut 模块进行精度检测并比对，运行如下命令：
+
+
 ```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   | 否      |
+| 参数名称     | 说明                                                                                                                                                                              |参数类型    | 是否必选     |
+| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------- | ---------------------------------- |
+| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。            |  str      | 是      |
+| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
+| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。  |  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-预检结果)。
 
+### 3.2 使用 multi_run_ut 执行多线程预检
+
+multi_run_ut 脚本，可以并行在多个Device执行 run_ut 操作，从而减少预检耗时。示例如下：
+
+```bash
+msprobe -f mindspore multi_run_ut -api_info ./dump.json -d 0 1 2 3
+```
+
+| 参数名称     | 说明                                                                                                                                                                              |参数类型    | 是否必选     |
+| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------- | ---------------------------------- |
+| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。                                   |  str      | 是      |
+| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
+| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 |  str   | 否      |
+| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0 ~ Device数量 - 1 ，例如 0 1 2 3 4。                                 |                                      List[int]  | 否      |
+
+在不同卡数下，使用38B语言大模型的预检耗时基线参考 [multi_run_ut耗时基线](accuracy_checker_MindSpore/accuracy_checker_MindSpore_baseline.md)
+
+
+### 3.3 断点续检
+
+断点续检操作通过如下命令执行：
+
+```bash
+msprobe -f mindspore run_ut -api_info ./dump.json -csv_path xxx/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` 文件内容详情如下：
@@ -46,7 +82,7 @@ msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result
 | MaxAbsErr           | 被检验数据与标杆数据的最大绝对误差。                       |
 | MaxRelativeErr      | 被检验数据与标杆数据的最大相对误差。                     |
 | Status              | API 预检通过状态，pass 表示通过测试，error 表示未通过。 |
-| message             | 提示信息。            |
+| Message             | 提示信息。            |
 
 注意：PyTorch 无法对 dtype 为整数类型的 tensor 进行反向求导，而 MindSpore 支持。反向过程的预检仅比较 dtype 为浮点型的输出。
 

msprobe/docs/10.accuracy_compare_PyTorch.md

@@ -1,5 +1,11 @@
 # PyTorch 场景的精度比对
 
+## 🚨 重要通知
+
+**1. 精度比对操作中2.2比对函数方式（compare 函数、compare_distributed 函数）将于2025.9.30废弃。**
+
+**2. 精度比对已支持自动识别stack.json并呈现NPU_Stack_Info。命令行方式中用户可无需配置compare.json中的"stack_path"字段和命令行中的-s参数。具体使用参见“2.1.4 比对文件”中的参数说明。命令行方式中的-s（--stack_mode）将于2025.9.30废弃，并且不再需要配置compare.json中的"stack_path"字段。比对函数方式同理，详见“2.2.1 compare函数”和“2.2.2 compare_distributed函数”中的参数说明。**
+
 ## 1 简介
 
 - 本节主要介绍通过命令行和比对函数的方式进行 CPU 或 GPU 与 NPU 的精度数据比对，执行精度比对操作前需要先完成 CPU 或 GPU 与 NPU 的精度数据 dump，参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节。
@@ -10,19 +16,19 @@
 
 - 工具性能：比对数据量较小时（单份文件小于 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 计算数值，进行问题定位。
 - 以上两个场景下，当存在无法自动匹配的API和模块时，则通过用户手动指定可以比对的API或模块来自定义映射关系，进行比对。
 
-**注意事项**：
+**注意事项**
 
 - NPU 自研 API，在 CPU 或 GPU 侧若没有对应的 API，该 API 的 dump 数据不比对。
 - NPU 与 CPU 或 GPU 的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个 API 因为输入的数据差异较大而无法比对的情况。
 - CPU 或 GPU 与 NPU 中两个相同的 API 会因为调用次数不同导致无法比对或比对到错误的 API，不影响整体运行，该 API 忽略。
 
-**API 匹配条件**：
+**API 匹配条件**
 
 进行精度比对时，需要判断 CPU 或 GPU 的 API 与 NPU 的 API 是否可以比对，须满足以下匹配条件：
 
@@ -37,22 +43,22 @@
 
 #### 2.1.1 比对命令说明
 
-命令示例如下：
+命令示例：
 
 ```shell
 msprobe -f pytorch compare -i ./compare.json -o ./output -s
 ```
 
-**完整参数说明**：
+完整参数说明：
 
-| 参数名               | 说明     | 是否必选 |
-|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
-| -i 或 --input_path   | 指定[比对文件](#211-比对文件)，str 类型。             | 是       |
-| -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。     | 是       |
-| -s 或 --stack_mode   | 配置 stack_mode 的开关，bool 类型。仅当[比对文件](#214-比对文件)配置 stack_path 需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| 参数名               | 说明                                                                                                                                                                                       | 是否必选 |
+|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| -i 或 --input_path   | 指定[比对文件](#214-比对文件)，str 类型。                                                                                                                                                              | 是       |
+| -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型，默认在当前目录创建output目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。                                                                                               | 否       |
+| -s 或 --stack_mode   | 比对结果展示调用栈信息（NPU_Stack_Info）的开关，bool 类型。单卡场景开启时，根据[比对文件](#214-比对文件)的参数说明配置stack_path；多卡场景开启时，自动识别npu_dump目录下stack.json文件，如存在生成详细调用栈信息，否则不生成，此参数不生效。通过直接配置该参数开启，默认未配置，表示关闭。                | 否       |
 | -c 或 --compare_only | 仅比对开关，bool 类型。该参数默认未配置，会启用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度可能不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。通过配置该参数取消自动精度分析，仅输出比对结果表格。 | 否       |
-| -f 或 --fuzzy_match  | 模糊匹配，bool 类型。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
-| -dm或--data_mapping | 自定义映射关系比对。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件](#215-自定义映射文件)。仅[API和模块无法自动匹配场景](#213-API和模块无法自动匹配场景)需要配置。仅支持逐卡比对，即使用[比对文件](#214-比对文件)的单卡场景示例。 | 否 |
+| -f 或 --fuzzy_match  | 模糊匹配，bool 类型。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                                               | 否       |
+| -dm或--data_mapping | 自定义映射关系比对。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件](#215-自定义映射文件)。仅[API和模块无法自动匹配场景](#213-api和模块无法自动匹配场景)需要配置。仅支持逐卡比对，即使用[比对文件](#214-比对文件)的单卡场景示例。                                         | 否 |
 
 #### 2.1.2 整网比对场景
 
@@ -60,11 +66,11 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。
 
-1. 配置[config.json](https://gitee.com/ascend/mstt/blob/8914fbb31ff6da3898c3bb7b97ba99e23b0f1d38/debug/accuracy_tools/msprobe/config.json)文件。
+1. 配置[config.json](../config.json)文件。
 
 2. 参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
 
-3. 创建[比对文件](#211-比对文件)。
+3. 创建[比对文件](#214-比对文件)。
 
 4. 运行命令：
 
@@ -78,11 +84,11 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 当存在无法自动匹配的API和模块时，则用户可以通过提供自定义映射关系的配置文件来告知工具可匹配的API或模块，进行比对。
 
-1. [config.json](https://gitee.com/ascend/mstt/blob/8914fbb31ff6da3898c3bb7b97ba99e23b0f1d38/debug/accuracy_tools/msprobe/config.json)文件level配置为L0或L1、task配置为tensor或statistics并指定需要dump的API或模块名。
+1. [config.json](../config.json)文件level配置为L0或L1、task配置为tensor或statistics并指定需要dump的API或模块名。
 
 2. 参见[PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
 
-3. 创建[比对文件](#211-比对文件)（单卡场景示例）。
+3. 创建[比对文件](#214-比对文件)（单卡场景示例）。
 
 4. 运行命令：
 
@@ -121,14 +127,14 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
      }
      ```
 
-   **参数说明**：
+**参数说明**：
 
-| 参数名               | 说明                                                         | 是否必选           |
-| -------------------- | ------------------------------------------------------------ | ------------------ |
-| 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，默认为 true。关闭后则只输出常规日志，bool 类型。 | 否                 |
+| 参数名               | 说明                                                                                                                                                                                  | 是否必选 |
+| -------------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| npu_path             | 配置 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景），str 类型。                                                                                                                                 | 是    |
+| bench_path           | 配置 CPU、GPU 或 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景），str 类型。                                                                                                                       | 是    |
+| stack_path           | 配置 NPU dump 目录下的 stack.json 文件，str 类型。如果没有配置stack_path，命令行-s参数不生效，程序自动识别是否存在stack.json文件，如存在，则比对结果中呈现NPU_Stack_Info，如不存在，则不呈现。如果配置了stack_path，比对结果中是否呈现NPU_Stack_Info则通过命令行参数-s来控制。 | 否    |
+| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值 true 或 false，默认为 true。关闭后则只输出常规日志，bool 类型。                                                                                                                      | 否    |
 
 #### 2.1.5 自定义映射文件
 
@@ -145,7 +151,7 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 冒号左侧和右侧分别为PyTorch框架不同版本或不同芯片环境的API的名称和module模块名称。
 
-API和模块名称请从《[PyTorch 场景的精度数据采集](https://gitee.com/ascend/mstt/blob/8914fbb31ff6da3898c3bb7b97ba99e23b0f1d38/debug/accuracy_tools/msprobe/docs/05.data_dump_PyTorch.md)》中的dump.json文件获取。
+API和模块名称请从《[PyTorch 场景的精度数据采集](05.data_dump_PyTorch.md)》中的dump.json文件获取。
 
 文件内容示例：
 
@@ -174,13 +180,13 @@ compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_mat
 
 **参数说明**：
 
-| 参数名       | 说明                                                         | 是否必选 |
-| ------------ | ------------------------------------------------------------ | -------- |
+| 参数名       | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 是否必选 |
+| ------------ |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
 | 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。 | 否       |
+| output_path  | 配置比对结果文件存盘目录，str 类型。<br/>**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。                                                                                                                                                                                                                                                                                                                                                                                      | 是       |
+| stack_mode   | 配置 stack_mode 的开关，bool 类型。仅当配置 stack_json_path 时需要，开启时比对结果呈现NPU_Stack_Info，关闭时不呈现。当不配置stack_json_path 时，自动识别是否存在stack.json，存在时呈现NPU_Stack_Info，否则不呈现。<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。                                                                                                                                                                                                                                                                                                                                                                                           | 否       |
 
 **函数示例**：
 
@@ -209,12 +215,12 @@ 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'。 | 是       |
+| 参数名         | 说明                                                                                                                                                        | 是否必选 |
+| -------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| 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 的所有可选参数。                                  | 否       |
+| **kwargs       | 支持 compare 的所有可选参数。 其中，stack_mode不生效，自动识别是否存在stack.json，如存在，呈现NPU_Stack_Info，否则不呈现。                                                                       | 否       |
 
 **函数示例**：
 
@@ -231,7 +237,7 @@ PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算
 
 - `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)
+  ![compare_result](./img/compare_result.png)
 
 - **提示**：比对结果通过颜色标记、比对结果（Result）、计算精度达标情况（Accuracy Reached no Not）、错误信息提示（Err_Message）定位可疑算子，但鉴于每种指标都有对应的判定标准，还需要结合实际情况进行判断。
 
@@ -251,25 +257,29 @@ PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算
 
 统计量有 4 种：最大值（max）、最小值（min）、平均值（mean）和 L2-范数（L2 norm）。
 
-|dump 数据模式|Cosine (tensor 余弦相似度)|MaxAbsErr (tensor 最大绝对误差)|MaxRelativeErr (tensor 最大相对误差)|One Thousandth Err Ratio (tensor 相对误差小于千分之一的比例)|Five Thousandth Err Ratio (tensor 相对误差小于千分之五的比例)|NPU 和 bench 的统计量绝对误差 (max, min, mean, L2 norm) diff| NPU 和 bench 的统计量相对误差 (max, min, mean, L2 norm) RelativeErr |NPU 和 bench 的统计量 (max, min, mean, L2 norm)|NPU MD5 (NPU 数据 MD5 值)|BENCH MD5 (bench 数据 MD5 值)|Result (比对结果)|Accuracy Reached or Not (计算精度是否达标)|Err_message (错误信息提示)|NPU_Stack_Info (堆栈信息)|Data_Name (NPU 真实数据名)|
+|dump 数据模式|Cosine (tensor 余弦相似度)|MaxAbsErr (tensor 最大绝对误差)|MaxRelativeErr (tensor 最大相对误差)|One Thousandth Err Ratio (tensor 相对误差小于千分之一的比例)|Five Thousandth Err Ratio (tensor 相对误差小于千分之五的比例)|NPU 和 bench 的统计量绝对误差 (max, min, mean, L2 norm) diff| NPU 和 bench 的统计量相对误差 (max, min, mean, L2 norm) RelativeErr |NPU 和 bench 的统计量 (max, min, mean, L2 norm)|NPU MD5 (NPU 数据 CRC-32 值)|BENCH MD5 (bench 数据 CRC-32 值)|Result (比对结果)|Accuracy Reached or Not (计算精度是否达标)|Err_message (错误信息提示)|NPU_Stack_Info (堆栈信息)|Data_Name (NPU 真实数据名)|
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 |真实数据模式|√|√|√|√|√|||√||||√|√|√|√|
 |统计数据模式||||||√|√|√|||√||√|√||
 |MD5 模式|||||||||√|√|√|||√||
 
+上表中NPU_Stack_Info字段需要配置-s参数生成。
+
 ### 3.2 颜色标记——真实数据模式、统计数据模式
 
+在比对结果中的Err_message列呈现比对结果颜色标记的原因，具体含义如下：
+
 红色标记情况：
-1. 一个 API 或模块的 One Thousandth Err Ratio 的 input > 0.9 同时 output < 0.6（真实数据模式）；
-2. 一个 API 或模块的 output 的最大值相对误差 (Max diff 除以 max(0.01, Bench max)) > 0.5（统计数据模式）；
-3. 一个 API 或模块的 NPU 的最大值或最小值中存在 nan/inf/-inf（真实数据模式、统计数据模式）；
-4. 一个 API 或模块的最大值绝对误差大于 1e+10（真实数据模式，统计数据模式）。
+1. 一个 API 或模块的 NPU 的最大值或最小值中存在 nan/inf/-inf（真实数据模式、统计数据模式）；
+2. 一个 API 或模块的最大值绝对误差大于 1e+10（真实数据模式，统计数据模式）；
+3. 一个 API 或模块的 One Thousandth Err Ratio 的 input/parameters > 0.9 同时 output < 0.6（真实数据模式）（仅标记output）；
+4. 一个 API 或模块的 output 的最大值相对误差 (Max diff 除以 max(0.01, Bench max)) > 0.5（统计数据模式）（仅标记output）。
 
-黄色标记情况：
-1. 一个 API 或模块的 One Thousandth Err Ratio 的 input - output > 0.1（真实数据模式）；
-2. 一个 API 或模块的 Cosine 的 input - output > 0.1（真实数据模式）；
-3. 一个 API 或模块的 output 的最大值相对误差 > 0.1 同时 input < 0.01（真实数据模式，统计数据模式）；
-4. 一个 API 或模块的 input 与 output 的最大值绝对误差都大于 1，同时 output 比 input 大一个数量级以上（真实数据模式、统计数据模式）。
+黄色标记情况(仅标记output)：
+1. 一个 API 或模块的 input/parameters 与 output 的最大值绝对误差都大于 1，同时 output 比 input/parameters 大一个数量级以上（真实数据模式、统计数据模式）；
+2. 一个 API 或模块的 One Thousandth Err Ratio 的 input/parameters - output > 0.1（真实数据模式）；
+3. 一个 API 或模块的 output 的最大值相对误差 > 0.1 同时 input/parameters < 0.01（真实数据模式，统计数据模式）；
+4. 一个 API 或模块的 Cosine 的 input/parameters - output > 0.1（真实数据模式）。
 
 ### 3.3 比对结果（Result）——统计数据模式、MD5 模式
 
@@ -279,8 +289,8 @@ PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算
 3. N/A 情况：API 没有匹配上。
 
 MD5 模式：
-1. Pass 情况：NPU 与标杆的 MD5 值一致，即 API 数据完全一致；
-2. Different 情况：NPU 与标杆的 MD5 值不一致，即 API 数据不完全一致；
+1. Pass 情况：NPU 与标杆的 CRC-32 值一致，即 API 数据完全一致；
+2. Different 情况：NPU 与标杆的 CRC-32 值不一致，即 API 数据不完全一致；
 3. N/A 情况：API 没有匹配上。
 
 ### 3.4 判断计算精度达标情况（Accuracy Reached or Not）——真实数据模式
@@ -310,10 +320,12 @@ MD5 模式：
 5. "This is empty data, can not compare."：读取到的数据为空（真实数据模式）；
 6. "Shape of NPU and bench Tensor do not match. Skipped."：NPU 和 Bench 的数据结构不一致（真实数据模式）；
 7. "The Position of inf or nan in NPU and bench Tensor do not match."：NPU 和 Bench 的数据有 nan/inf（真实数据模式）；
-8. "This is type of scalar data, can not compare."：NPU 为标量（真实数据模式）；
+8. "This is type of 0-d tensor, can not calculate 'Cosine', 'One Thousandth Err Ratio' and 'Five Thousandths Err Ratio'."：NPU 为0维张量（真实数据模式）；
 9.  "Dtype of NPU and bench Tensor do not match."：NPU 和 Bench 数据的数据类型不同（真实数据模式）；
 10. ""：除以上情况的其余情况（真实数据模式、统计数据模式）。
 
+除以上错误信息提示外，异常数据颜色高亮标记的原因叠加呈现于此列。
+
 ### 3.6 计算精度评价指标分析
 
 1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于 1 说明计算出的两个张量越相似，实际可接受阈值为大于 0.99。在计算中可能会存在 nan，主要由于可能会出现其中一个向量为 0。
@@ -324,4 +336,56 @@ MD5 模式：
 
    当 dump 数据中存在 0 或 Nan 时，比对结果中最大相对误差则出现 inf 或 Nan 的情况，属于正常现象。
 
-4. One Thousandth Err Ratio（双千分之一）、Five Thousandths Err Ratio（双千分之五）精度指标：是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差大于千分之一、千分之五的比例占总元素个数的比例小于千分之一、千分之五。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。
+4. One Thousandth Err Ratio（相对误差小于千分之一的元素比例）、Five Thousandths Err Ratio（相对误差小于千分之五的元素比例）精度指标：是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一、千分之五的比例占总元素个数的比例。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。
+
+## 4 多卡比对结果提取汇总通信算子数据
+
+本功能是将多卡比对场景的比对结果，进行通信算子数据提取和汇总，输出整理好的通信算子多卡比对精度表。
+
+**约束**
+
+不支持MD5比对结果。
+
+**命令示例**
+
+```bash
+msprobe -f pytorch merge_result -i ./input_dir -o ./output_dir -config ./config.yaml
+```
+
+**完整参数说明**
+
+| 参数名                 | 说明                                                                                 | 是否必选 |
+| ---------------------- |------------------------------------------------------------------------------------| -------- |
+| -i 或 --input_dir      | 多卡比对结果存盘目录，即使用compare比对的结果输出目录，str类型。所有比对结果应全部为真实数据比对结果或统计数据比对结果，否则可能导致汇总数据不完整。    | 是       |
+| -o 或 --output_dir     | 数据提取汇总结果存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`multi_ranks_compare_merge_{timestamp}.xlsx`。 | 是       |
+| -config或--config-path | 指定需要汇总数据的API和比对指标的yaml文件路径，str类型。<br>yaml文件详细介绍见下文“**yaml文件说明**”。                  | 是       |
+
+**yaml文件说明**
+
+以config.yaml文件名为例，配置示例如下：
+
+```
+api:
+- Distributed.all_reduce
+- Distributed.all_gather_into_tensor
+compare_index:
+- Max diff
+- L2norm diff
+- MeanRelativeErr
+```
+
+| 参数名        | 说明                                                         |
+| ------------- | ------------------------------------------------------------ |
+| api           | 表示需要汇总的API或module名称。如果没有配置，工具会提示报错。<br>api名称配置格式为：`{api_type}.{api_name}.{API调用次数}.{前向反向}`<br>须按顺序配置以上四个字段，可按如下组合配置：<br/>        {api_type}<br/>        {api_type}.{api_name}<br/>        {api_type}.{api_name}.{API调用次数}<br/>        {api_type}.{api_name}.{API调用次数}.{前向反向}<br/>这里的api指代API或module。 |
+| compare_index | 表示需要汇总的比对指标。compare_index需为dump_mode对应比对指标的子集。如果没有配置，工具将根据比对结果自动提取dump_mode对应的全部比对指标进行汇总。<br>统计数据模式比对指标：Max diff、Min diff、Mean diff、Norm diff、MaxRelativeErr、MinRelativeErr、MeanRelativeErr、NormRelativeErr<br>真实数据模式比对指标：Cosine、MaxAbsErr、MaxRelativeErr、One Thousandth Err Ratio、Five Thousandths Err Ratio |
+
+**汇总结果件说明**
+
+多卡数据汇总结果如下所示：
+
+![merge_result](img/merge_result.png)
+
+1. NPU Name列表示API或module名称。
+2. rank*列为多卡数据。
+3. 不同比对指标的数据通过不同sheet页呈现。
+4. 如果一个API或module在某张卡上找不到数据，汇总结果中将空白呈现。