mindstudio-probe 1.2.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

msprobe/docs/11.accuracy_compare_MindSpore.md

@@ -19,7 +19,7 @@ msprobe精度比对工具主要用于如下场景：
   - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API或模块dump数据，由用户指定可以比对的API或模块，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
   - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API或模块dump数据，由用户指定可以比对的模型代码中的Layer层，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
 
-执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../README.md)》的“工具安装”章节。
+执行精度比对操作需要安装msprobe工具。详见[《msprobe 工具安装指南》](./01.installation.md)。
 
 ## 2 命令行比对
 
@@ -35,17 +35,17 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 **完整参数说明**
 
-| 参数名               | 说明                                                         | 是否必选 |
-| -------------------- | ------------------------------------------------------------ | -------- |
-| -i或--input_path     | 指定比对文件。比对文件内容及示例请参见[比对文件](#31-比对文件)或[比对文件（kernel）](#32-比对文件kernel)（比对文件（kernel）仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
-| -o或--output_path    | 配置比对结果文件存盘目录，默认会在当前目录创建output目录。文件名称基于时间戳自动生成，格式为：<br>        `compare_result_{timestamp}.xlsx`<br/>        `compare_result_{rank_id}_{step_id}_{timestamp}.xlsx`（仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 否       |
-| -s或--stack_mode     | 比对结果展示调用栈信息（NPU_Stack_Info）的开关，bool 类型。单卡场景开启时，需要使用[比对文件](#31-比对文件)的单卡场景配置stack_path指定stack.json文件，才能生成详细调用栈信息，否则在比对时会报错；暂不支持多卡场景。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
-| -c或--compare_only   | 仅比对开关，bool 类型。该参数默认未配置，会启用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度可能不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。通过配置该参数取消自动精度分析，仅输出比对结果表格。 | 否       |
-| -f或--fuzzy_match    | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
-| -am或--api_mapping   | 跨框架比对。配置该参数时表示开启跨框架API比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（api_mapping）](#33-自定义映射文件api_mapping)。仅[跨框架的API比对](#25-跨框架的api比对)场景需要配置。 | 否       |
-| -cm或--cell_mapping  | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（cell_mapping）](#34-自定义映射文件cell_mapping)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景需要配置。 | 否       |
-| -dm或--data_mapping  | 同框架或跨框架比对。通过映射文件指定两个具体参数的对应关系，可以在L0、L1或mix采集场景下使用。配置该参数的同时需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（data_mapping）](#35-自定义映射文件data_mapping)。 | 否       |
-| -lm或--layer_mapping | 跨框架比对。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer_mapping）](#36-自定义映射文件layer_mapping)。仅[跨框架的Layer层比对](#27-跨框架的layer层比对)场景需要配置。 | 否       |
+| 参数名               | 说明                                                                                                                                                                                                                                               | 是否必选 |
+| -------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| -i或--input_path     | 指定比对文件。比对文件内容及示例请参见[比对文件](#41-比对文件)或[比对文件（kernel）](#42-比对文件kernel)（比对文件（kernel）仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。                                                                                                                   | 是       |
+| -o或--output_path    | 配置比对结果文件存盘目录，默认会在当前目录创建output目录。文件名称基于时间戳自动生成，格式为：<br>        `compare_result_{timestamp}.xlsx`<br/>        `compare_result_{rank_id}_{step_id}_{timestamp}.xlsx`（仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。<br>提示：output目录下与结果件同名文件将被删除覆盖。 | 否       |
+| -s或--stack_mode     | 比对结果展示调用栈信息（NPU_Stack_Info）的开关，bool 类型。单卡场景开启时，需要使用[比对文件](#41-比对文件)的单卡场景配置stack_path指定stack.json文件，才能生成详细调用栈信息，否则在比对时会报错；暂不支持多卡场景。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                        | 否       |
+| -c或--compare_only   | 仅比对开关，bool 类型。该参数默认未配置，会启用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度可能不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。通过配置该参数取消自动精度分析，仅输出比对结果表格。                                                         | 否       |
+| -f或--fuzzy_match    | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                                                                                                                | 否       |
+| -am或--api_mapping   | 跨框架比对。配置该参数时表示开启跨框架API比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（api_mapping）](#43-自定义映射文件api_mapping)。仅[跨框架的API比对](#25-跨框架的api比对)场景需要配置。                                                                       | 否       |
+| -cm或--cell_mapping  | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（cell_mapping）](#44-自定义映射文件cell_mapping)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景需要配置。                                                            | 否       |
+| -dm或--data_mapping  | 同框架或跨框架比对。通过映射文件指定两个具体参数的对应关系，可以在L0、L1或mix采集场景下使用。配置该参数的同时需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（data_mapping）](#45-自定义映射文件data_mapping)。                                                                                                       | 否       |
+| -lm或--layer_mapping | 跨框架比对。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer_mapping）](#46-自定义映射文件layer_mapping)。仅[跨框架的Layer层比对](#27-跨框架的layer层比对)场景需要配置。                                                   | 否       |
 
 动态图模式没有填写任何mapping时，按照同框架比对的方式进行比对，比对数据和标杆数据的Cell或Api名称需要完全相同才能匹配得上。
 
@@ -53,7 +53,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的API dump数据。
 
-2. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+2. 创建比对文件，文件内容及示例请参见[比对文件](#41-比对文件)。
 
 3. 执行如下示例命令进行比对：
 
@@ -67,7 +67,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的kernel dump数据。
 
-2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#32-比对文件kernel)。
+2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#42-比对文件kernel)。
 
 3. 执行如下示例命令进行比对：
 
@@ -85,7 +85,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore动态图精度数据的采集，得到不同框架版本的cell模块dump数据。
 
-3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+3. 创建比对文件，文件内容及示例请参见[比对文件](#41-比对文件)。
 
 4. 执行如下示例命令进行比对：
 
@@ -101,7 +101,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API精度数据的采集，得到两个框架的API dump数据。
 
-3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+3. 创建比对文件，文件内容及示例请参见[比对文件](#41-比对文件)。
 
 4. 执行如下示例命令进行比对：
 
@@ -115,14 +115,14 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -am api_mapping.yaml
    ```
 
-   api_mapping.yaml文件配置请参见[自定义映射文件（api_mapping）](#33-自定义映射文件api_mapping)。
+   api_mapping.yaml文件配置请参见[自定义映射文件（api_mapping）](#43-自定义映射文件api_mapping)。
    不传入api_mapping.yaml的情况下将按照内置的api映射进行匹配；传入api_mapping.yaml的情况下优先按照api_mapping.yaml的内容进行匹配，api_mapping.yaml中没有涉及的按照内置的api映射进行匹配。
 
    此外，也可以通过data_mapping.yaml文件实现具体参数的匹配，例：
    ```shell
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
    ```
-   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#35-自定义映射文件data_mapping)。
+   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#45-自定义映射文件data_mapping)。
 
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
@@ -132,7 +132,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下cell模块精度数据的采集，得到两个框架的cell模块dump数据。
 
-3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+3. 创建比对文件，文件内容及示例请参见[比对文件](#41-比对文件)。
 
 4. 执行如下示例命令进行比对：
 
@@ -146,14 +146,14 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm cell_mapping.yaml
    ```
 
-   cell_mapping.yaml文件配置请参见[自定义映射文件（cell_mapping）](#34-自定义映射文件cell_mapping)。
+   cell_mapping.yaml文件配置请参见[自定义映射文件（cell_mapping）](#44-自定义映射文件cell_mapping)。
    不传入cell_mapping.yaml的情况下仅将Cell改成Module后进行匹配；传入cell_mapping.yaml的情况下将按照cell_mapping.yaml的内容进行匹配。
 
    此外，也可以通过data_mapping.yaml文件实现具体参数的匹配，例：
    ```shell
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
    ```
-   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#35-自定义映射文件data_mapping)。
+   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#45-自定义映射文件data_mapping)。
 
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
@@ -165,7 +165,7 @@ layer_mapping可以从Layer层识别整网的API和Cell，简化配置。
 
 2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API或模块精度数据的采集，得到两个框架的API或模块dump数据。
 
-3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+3. 创建比对文件，文件内容及示例请参见[比对文件](#41-比对文件)。
 
 4. 执行如下示例命令进行比对：
 
@@ -173,20 +173,42 @@ layer_mapping可以从Layer层识别整网的API和Cell，简化配置。
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -lm layer_mapping.yaml
    ```
 
-   layer_mapping.yaml文件配置请参见[自定义映射文件（layer_mapping）](#36-自定义映射文件layer_mapping)。
+   layer_mapping.yaml文件配置请参见[自定义映射文件（layer_mapping）](#46-自定义映射文件layer_mapping)。
 
    此外，也可以通过data_mapping.yaml文件实现具体参数的匹配，例：
    ```shell
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
    ```
-   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#35-自定义映射文件data_mapping)。
+   data_mapping.yaml的写法请参见[自定义映射文件（data_mapping）](#45-自定义映射文件data_mapping)。
 
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
+### 2.8 单点数据比对
+1. 参见 [单点保存工具](./28.debugger_save_instruction.md)章节完成 CPU 或 GPU 与 NPU 的单点数据采集。
+
+2. 创建比对文件，文件内容及示例请参见[比对文件(单点数据)](#47-比对文件单点数据)。
+
+3. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output
+   ```
+
+4. Pytorch & MindSpore 动态图场景查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
+MindSpore静态图场景比对结果：
+- `result.csv` 文件列出了所有执行精度比对的 单点保存数据 详细信息和比对结果，示例如下：
+
+  ![compare_result](./img/save_compare_result_sample.png)
+具体字段含义同PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
+
 ## 3 多卡比对结果提取汇总通信算子数据
 
 本功能是将多卡比对场景的比对结果，进行通信算子数据提取和汇总，输出整理好的通信算子多卡比对精度表。
 
+**使用场景**
+
+已完成精度比对，获得多卡精度比对结果，但是通信算子数据分布在多个结果件中，不利于精度问题的分析。通过此功能，可以汇总多卡通信算子数据，减少问题定位时间。
+
 **约束**
 
 - 不支持MD5比对结果。
@@ -200,11 +222,11 @@ msprobe -f mindspore merge_result -i ./input_dir -o ./output_dir -config ./confi
 
 **完整参数说明**
 
-| 参数名                 | 说明                                                         | 是否必选 |
-| ---------------------- | ------------------------------------------------------------ | -------- |
-| -i 或 --input_dir      | 多卡比对结果存盘目录，即使用compare比对的结果输出目录，str类型。所有比对结果应全部为真实数据比对结果或统计数据比对结果，否则可能导致汇总数据不完整。 | 是       |
-| -o 或 --output_dir     | 数据提取汇总结果存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`multi_ranks_compare_merge_{timestamp}.xlsx`。 | 是       |
-| -config或--config-path | 指定需要汇总数据的API和比对指标的yaml文件路径，str类型。<br>yaml文件详细介绍见下文“**yaml文件说明**”。 | 是       |
+| 参数名                 | 说明                                                                                                                | 是否必选 |
+| ---------------------- |-------------------------------------------------------------------------------------------------------------------| -------- |
+| -i 或 --input_dir      | 多卡比对结果存盘目录，即使用compare比对的结果输出目录，str类型。所有比对结果应全部为真实数据比对结果或统计数据比对结果，否则可能导致汇总数据不完整。                                   | 是       |
+| -o 或 --output_dir     | 数据提取汇总结果存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`multi_ranks_compare_merge_{timestamp}.xlsx`。<br>提示：output目录下与结果件同名文件将被删除覆盖。 | 是       |
+| -config或--config-path | 指定需要汇总数据的API和比对指标的yaml文件路径，str类型。<br>yaml文件详细介绍见下文“**yaml文件说明**”。                                                 | 是       |
 
 **yaml文件说明**
 
@@ -220,10 +242,10 @@ compare_index:
 - 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 |
+| 参数名        | 说明                                                                                                                                                                                                                                                                                                                      |
+| ------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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、L2norm diff、MaxRelativeErr、MinRelativeErr、MeanRelativeErr、NormRelativeErr<br>真实数据模式比对指标：Cosine、EucDist、MaxAbsErr、MaxRelativeErr、One Thousandth Err Ratio、Five Thousandths Err Ratio |
 
 **汇总结果件说明**
 
@@ -235,6 +257,26 @@ compare_index:
 2. rank*列为多卡数据。
 3. 不同比对指标的数据通过不同sheet页呈现。
 4. 如果一个API或module在某张卡上找不到数据，汇总结果中将空白呈现。
+5. 如果比对指标值为N/A，unsupported，Nan，表示无法计算该比对指标值，汇总结果将以”NPU:’NPU max值‘  Bench:’Bench max值‘“呈现。
+6. 针对图示案例，此处NPU:N/A  Bench:N/A表示output为None。
+
+<br>
+如何基于group信息查看分组数据：
+
+以Distributed.all_reduce.0.forward为例。这个API将多卡数据规约操作，输出为一个group内的规约结果，同一个group内的输出保持一致。<br>这个API中，rank0-3为一个group，Distributed.all_reduce.0.forward.input.group展示为tp-0-1-2-3，rank0-3输出一致；rank4-7为一个group，展示为tp-4-5-6-7，rank4-7输出一致。<br>group除了这种形式，还有如[0, 1, 2, 3]的呈现形式。
+
+<br>
+常见通信API预期结果：
+
+1. Distributed.all_gather：多卡数据汇总，每张卡输入可以不一致，同group内输出一致，输出是张量列表。
+2. Distributed.all_gather_into_tensor：多卡数据汇总，每张卡输入可以不一致，同group内输出一致，输出是张量。
+3. Distributed.all_reduce：多卡数据规约操作，每张卡输入可以不一致，同group内输出一致，为规约结果。
+4. Distributed.reduce_scatter：多卡数据规约操作，每张卡输入可以不一致，输出为group内规约结果的不同部分，输入是张量列表。
+5. Distributed.reduce_scatter_tensor：多卡数据规约操作，每张卡输入可以不一致，输出为group内规约结果的不同部分，输入是张量。
+6. Distributed.broadcast：输入为要广播的数据，输出为广播后的数据。
+7. Distributed.isend：点对点通信，输入为要发送的数据，输出为发送的数据。
+8. Distributed.irecv：点对点通信，输入为原数据，输出为接收的新数据。
+9. Distributed.all_to_all_single：输出数据为所有卡上的数据切分后合并的结果。
 
 ## 4 附录
 
@@ -255,20 +297,20 @@ compare_index:
 多卡场景示例如下：
 ```json
 {
-"npu_path": "./npu_dump/step0", # 需填写到step层级（rank的上一层级）
-"bench_path": "./bench_dump/step0", # 需填写到step层级（rank的上一层级）
+"npu_path": "./npu_dump/step0",  # 需填写到step层级（rank的上一层级）
+"bench_path": "./bench_dump/step0",  # 需填写到step层级（rank的上一层级）
 "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。 如果没有配置stack_path，命令行-s参数不生效，程序自动识别是否存在stack.json文件，如存在，则比对结果中呈现NPU_Stack_Info，如不存在，则不呈现。如果配置了stack_path，比对结果中是否呈现NPU_Stack_Info则通过命令行参数-s来控制。         | 否    |
-| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值true或false，默认为true。关闭后则只输出常规日志。数据类型：bool | 否    |
+| 参数名               | 说明                                                                                                                                                                                | 是否必选 |
+| -------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| npu_path             | 配置NPU环境下的dump.json文件（单卡场景）或dump目录（多卡场景）。跨框架场景指定为MindSpore的dump.json文件或dump目录。数据类型：str。                                                                                            | 是    |
+| bench_path           | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）或dump目录（多卡场景）。跨框架场景指定为PyTorch的dump.json文件或dump目录。数据类型：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。                                                                                                                      | 否    |
 
 ### 4.2 比对文件（kernel）
 
@@ -549,7 +591,7 @@ input_args、input_kwargs和output使用统一的命名规则，当值是list类
 "md5": "28f8f74f"
 }
 ]
-} 
+}
 ```
 ,
 初始名称为`Cell.network.module.NetworkWithLoss.forward.0`，`input_args`是`list`，长度为2，按照顺序命名为
@@ -622,4 +664,36 @@ yaml文件中只需配置MindSpore与PyTorch模型代码中功能一致但名称
 
 模型代码示例：
 
-![ms_dump](./img/ms_layer.png)
+![ms_dump](./img/ms_layer.png)
+
+### 4.7 比对文件（单点数据）
+
+MindSpore动态图单卡场景示例如下：
+  ```json
+{
+"npu_path": "./npu_dump/debug.json",
+"bench_path": "./bench_dump/debug.json"
+}
+  ```
+
+MindSpore动态图多卡场景（step0目录下包含debug.json文件）示例如下：
+```json
+{
+"npu_path": "./npu_dump/step0",
+"bench_path": "./bench_dump/step0"
+}
+```
+
+MindSpore静态图场景（不区分单/多卡）示例如下：
+```json
+{
+"npu_path": "./npu_dump/",
+"bench_path": "./bench_dump/",
+"map_dict": {"input": "x"}, 
+"common": true 
+}
+```
+- `npu_path`表示NPU dump文件目录，可指定到./npu_dump/ 或者./npu_dump/step0 或者./npu_dump/step0/rank0 保证对应即可，比对结果保持相同目录结构。
+- `bench_path`表示bench dump文件目录，指定同上。
+- `common`表示开启MindSpore静态图单点保存比对，默认关闭。
+- `map_dict`可用于当单点保存比对的`npy`文件名称不完全对应时，通过手动指定保证比对正确执行，比对指定名称对应，如{"input": "x"}，则`input_float32_1.npy`会对应`x_float32_1.npy`。

msprobe/docs/12.overflow_check_PyTorch.md

@@ -12,13 +12,13 @@ msprobe 工具在 PyTorch 场景下提供溢出数据采集功能和溢出数据
 
 ### 1.2 接口介绍
 
-溢出检测功能提供的接口与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**1 接口介绍**"章节。
+溢出检测功能提供的接口与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**接口介绍**"章节。
 其中 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 示例代码**"章节。
+溢出检测功能使用方式与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**示例代码**"章节。
 
 ### 1.4 结果文件介绍
 
@@ -26,7 +26,9 @@ msprobe 工具在 PyTorch 场景下提供溢出数据采集功能和溢出数据
 
 ### 1.5 其他说明
 
-溢出数据采集功能在昇腾 NPU 上支持饱和模式和 INF/NAN 模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。
+溢出数据采集功能在昇腾 NPU 上支持饱和模式（仅支持 Atlas 训练系列产品）和 INF/NAN 模式。
+
+INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不支持使用 INF/NAN 模式；Atlas A2 训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。
 
 INF/NAN 模式的使能方式如下：
 

msprobe/docs/13.overflow_check_MindSpore.md

@@ -11,21 +11,23 @@ export INF_NAN_MODE_ENABLE=1
 export MS_ASCEND_CHECK_OVERFLOW_MODE="INFNAN_MODE"
 ```
 
-**a**：在处理浮点数计算溢出问题时，NPU 当前支持两种溢出模式：INF/NAN 模式与饱和模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。对于 MindSpore 框架侧配置，仅支持对 Atlas A2 训练系列产品进行设置，默认为 INF/NAN 模式。CANN 侧 与 MindSpore 框架侧配置须一致。
+**a**：在处理浮点数计算溢出问题时，NPU 当前支持两种溢出模式：INF/NAN 模式与饱和模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不支持使用 INF/NAN 模式；Atlas A2训练系列产品，默认为 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 场景的精度数据采集中的["**1 接口介绍**"](./06.data_dump_MindSpore.md#1-接口介绍)章节。
+溢出检测功能提供的接口与数据采集任务一致，详见MindSpore 场景的精度数据采集中的["**接口介绍**"](./06.data_dump_MindSpore.md#6-接口介绍)章节。
 
 需要注意，目前暂不支持动态图 "L1" level 下 primitive op 的溢出检测。
 
 ## 2 示例代码
 
-溢出检测功能使用方式与数据采集任务一致，详见MindSpore 场景的精度数据采集中的["**2 示例代码**"](./06.data_dump_MindSpore.md#2-示例代码)节。
+溢出检测功能使用方式与数据采集任务一致，详见MindSpore 场景的精度数据采集中的["**示例代码**"](./06.data_dump_MindSpore.md#7-示例代码)节。
 
 ## 3 溢出检测结果文件介绍
 
-溢出检测结果文件目录结构与含义与数据采集任务一致，但仅保存溢出 API 或 kernel 的真实数据或统计信息。详见MindSpore 场景的精度数据采集中的["**3 dump 结果文件介绍**"](./06.data_dump_MindSpore.md#3-dump-结果文件介绍)章节。
+溢出检测结果文件目录结构与含义与数据采集任务一致，但仅保存溢出 API 或 kernel 的真实数据或统计信息。详见MindSpore 场景的精度数据采集中的["**8. dump 结果文件介绍**"](./06.data_dump_MindSpore.md#8-dump-结果文件介绍)章节。
+
+**说明**：在静态图 O2 编译等级下，若 MindSpore 版本为 2.4，或者 MindSpore 版本为 2.5，且未使用编包时添加了`--include-mod=adump`选项的 mindstudio-probe whl 包，则会产生 kernel_graph_overflow_check.json 中间文件，一般情况下无需关注。

msprobe/docs/14.data_parse_PyTorch.md

@@ -26,13 +26,7 @@ Parse >>>
 - 支持交互式指定 pkl 文件中 API 对应 dump 数据查看。
 - 支持 API 进行可选层级比对和打印（统计级和像素级）。
 
-Ctrl+C 可以退出 parse 交互式界面。不退出 parse 交互式界面若需要执行非该界面下的内置 Shell 命令，且命令与 parse 交互式界面命令冲突时，非该界面命令需要使用 run 命令，在相关命令前加上 run 前缀，如下示例：
-
-```bash
-msprobe -f pytorch parse
-Parse >>> run vim cli.py
-Parse >>> vim cli.py
-```
+Ctrl+C 可以退出 parse 交互式界面。
 
 ### 2.2 kernel 层级算子数据批量转换
 
@@ -109,7 +103,7 @@ vc -m my_dump_path -g golden_dump_path [-out output_path] [-cmp_path msaccucmp_p
 | --------- | ------------------------------------------------------------ | -------- |
 | -m        | 待比对 kernel dump 数据目录。如果比对单个算子，需要指定到 kernel dump 数据的 model_id 级目录；如果批量比对，则指定到 cad 转换后的 timestamp 级目录。 | 是       |
 | -g        | 标杆 kernel dump 数据目录。如果比对单个算子，需要指定到 kernel dump 数据的 model_id 级目录；如果批量比对，则指定到 cad 转换后的 timestamp 级目录。 | 是       |
-| -out      | 结果输出目录，须指定已存在的目录，默认为 ./parse_data/acl_batch_comapre。未指定时保存在默认路径下，比对结束后会打印 log 提示输出结果存放路径。 | 否       |
+| -out      | 结果输出目录，须指定已存在的目录，默认为 ./parse_data/acl_batch_compare。未指定时保存在默认路径下，比对结束后会打印 log 提示输出结果存放路径。 | 否       |
 | -cmp_path | 指定 msaccucmp 路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否       |
 
 输出结果：`batch_compare_{timestamp}.csv` 文件。
@@ -119,7 +113,7 @@ vc -m my_dump_path -g golden_dump_path [-out output_path] [-cmp_path msaccucmp_p
 ```bash
 # 传入待比对数据目录以及标杆数据目录
 Parse >>> vc -m ./my_dump_path -g ./golden_data_path
-[INFO]Compare result is saved in : parse_data/acl_batch_comapre/batch_compare_1707271118.csv
+[INFO]Compare result is saved in : parse_data/acl_batch_compare/batch_compare_1707271118.csv
 ```
 
 ### 2.3 kernel 算子数据的 npy 转换
@@ -225,7 +219,7 @@ Statistic Info:
 输入以下命令, 进行统计级和像素级比对。
 
 ```bash
-cn -m my_data*.npy -g gloden*.npy [-p num] [-al atol] [-rl rtol]
+cn -m my_data*.npy -g golden*.npy [-p num] [-al atol] [-rl rtol]
 ```
 
 - 统计级比对：对 tensor 整体进行余弦值及相对误差的计算。

msprobe/docs/17.grad_probe.md

@@ -5,7 +5,7 @@
 - 将模型权重的梯度数据导出。这种功能可以将模型权重的梯度值以统计量的形式采集出来，用以分析问题。
 - 将两份梯度数据进行相似度对比。在有标杆问题中，可以确认训练过程中精度问题出现的step，以及抓取反向过程中的问题。
 
-工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。暂不支持deepspeed的zero1、zero2、zero3。
+工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。暂不支持deepspeed的ZeRO-1、ZeRO-2、ZeRO-3。
 
 ## 工具特性
 
@@ -65,6 +65,7 @@
 
    + 值分布：梯度数据落在各个区间的元素个数占总元素个数的比例。
    + bounds：一个列表，用来划分出区间以统计值分布。例如传入bounds = [-10, 0, 10]，此时有一个 grad_value: Tensor = [9.3 , 5.4, -1.0, -12.3]，依据 bounds 划分出 (-inf, -10]、(-10, 0]、(0, 10]、(10, inf) 四个区间，然后统计grad_value里的数据落在每个区间内的个数，得到 1、1、2、0。如下图所示：
+
    ![Alt text](./img/grad_probe_image-1.png)
 
 2. 插入代码。示例代码如下：

msprobe/docs/18.online_dispatch.md

@@ -70,15 +70,15 @@ PyTorch NPU在线精度比对是msprobe工具实现在PyTorch训练过程中直
 | api_list | dump范围，dump_mode="list"时设置，需要Dump Aten Ir API名称，默认为None，Aten Ir API名称可以通过dir(torch.ops.aten)查看。 | 否       |
 | dump_path| dump文件生成的路径。                                                                                    | 是       |
 | tag      | 传入tag字符串，成为dump文件夹名一部分，默认为None。                                                                 | 否       |
-| process_num | 多进程并发数，默认为0。                                                                                    | 否       |
+| process_num | 多进程并发数，默认为0，最大不超过CPU核数的四分之一。                                                                                    | 否       |
 | debug       | debug信息打印，默认为False。                                                                             | 否       |
 ### dump数据存盘说明
-dump数据存盘目录名格式：`atat_tag_rankid_{timestamp}`。
+dump数据存盘目录名格式：`msprobe_rankid_{timestamp}`。
 
 子目录下包含1个比对结果csv文件、cpu和npudump数据目录，npu目录下包含Aten IR在NPU上的输入输出的dump数据，由于CPU的输入是直接使用NPU的输入执行，因此cpu目录下只包含执行输出的dump数据。
 
 ```bash
-atat_rank4_20230911170521
+msprobe_rank4_20230911170521
 ├── compare_result_rank4_20230911170521.csv
 ├── cpu
 │   ├── native_batch_norm_backward_10_output.0.npy