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

msprobe/docs/11.accuracy_compare_MindSpore.md

@@ -1,5 +1,10 @@
 # MindSpore 场景的精度比对
 
+## 🚨 重要通知
+
+**1. 精度比对已支持自动识别stack.json并呈现NPU_Stack_Info，用户可无需配置compare.json中的"stack_path"字段和命令行中的-s参数。具体使用参见“4.1 比对文件”中的参数说明。命令行方式中的-s（--stack_mode）将于2025.9.30废弃，并且不再需要配置compare.json中的"stack_path"字段。**
+
+
 ## 1 简介
 
 msprobe精度比对工具主要用于如下场景：
@@ -33,14 +38,16 @@ 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"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| -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比对功能。仅[跨框架的API比对](#25-跨框架的api比对)场景需要配置。 | 否       |
-| -cm或--cell_mapping  | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（cell）](#33-自定义映射文件cell)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景需要配置。 | 否       |
-| -dm或--data_mapping  | 跨框架比对。配置该参数时表示开启跨框架API或模块的比对功能，需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（API和模块）](#34-自定义映射文件api和模块)。仅[跨框架的API或模块比对](#27-跨框架的api或模块比对)场景需要配置。 | 否       |
-| -lm或--layer_mapping | 跨框架比对。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#35-自定义映射文件layer)。仅[跨框架的Layer层比对](#28-跨框架的layer层比对)场景需要配置。 | 否       |
+| -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层比对)场景需要配置。 | 否       |
+
+动态图模式没有填写任何mapping时，按照同框架比对的方式进行比对，比对数据和标杆数据的Cell或Api名称需要完全相同才能匹配得上。
 
 ### 2.2 不同版本下的全量API比对
 
@@ -102,6 +109,21 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -am
    ```
 
+   或
+
+   ```shell
+   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映射进行匹配；传入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)。
+
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.6 跨框架的cell模块比对
@@ -124,15 +146,22 @@ 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）](#33-自定义映射文件cell)。
+   cell_mapping.yaml文件配置请参见[自定义映射文件（cell_mapping）](#34-自定义映射文件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)。
 
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
-### 2.7 跨框架的API或模块比对
+### 2.7 跨框架的Layer层比对
 
-该场景可用于在“**跨框架的API比对**”和“**跨框架的cell模块比对**”场景均无法完全覆盖模型中的API和模块时，通过手动指定映射关系来补全未被比对的API或模块。
+layer_mapping可以从Layer层识别整网的API和Cell，简化配置。
 
-1. 配置[config.json](../config.json)文件level配置为L0或L1、task配置为tensor或statistics并指定需要dump的API或模块名。
+1. 配置[config.json](../config.json)文件level配置为L0或mix、task配置为tensor或statistics并指定需要dump的API或模块名。
 
 2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API或模块精度数据的采集，得到两个框架的API或模块dump数据。
 
@@ -141,36 +170,75 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 4. 执行如下示例命令进行比对：
 
    ```shell
-   msprobe -f mindspore compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -lm layer_mapping.yaml
    ```
 
-   data_mapping.yaml文件配置请参见[自定义映射文件（all）](#34-自定义映射文件all)。
+   layer_mapping.yaml文件配置请参见[自定义映射文件（layer_mapping）](#36-自定义映射文件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)。
 
 5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
-### 2.8 跨框架的Layer层比对
+## 3 多卡比对结果提取汇总通信算子数据
 
-该场景可简化API或模块场景的配置，从Layer层识别整网的API和模块。
+本功能是将多卡比对场景的比对结果，进行通信算子数据提取和汇总，输出整理好的通信算子多卡比对精度表。
 
-1. 配置[config.json](../config.json)文件level配置为L0或mix、task配置为tensor或statistics并指定需要dump的API或模块名。
+**约束**
 
-2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API或模块精度数据的采集，得到两个框架的API或模块dump数据。
+- 不支持MD5比对结果。
+- 不支持MindSpore静态图比对结果。
 
-3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+**命令示例**
 
-4. 执行如下示例命令进行比对：
+```bash
+msprobe -f mindspore merge_result -i ./input_dir -o ./output_dir -config ./config.yaml
+```
 
-   ```shell
-   msprobe -f mindspore compare -i ./compare.json -o ./output -s -lm layer_mapping.yaml
-   ```
+**完整参数说明**
 
-   layer_mapping.yaml文件配置请参见[自定义映射文件（Layer）](#35-自定义映射文件layer)。
+| 参数名                 | 说明                                                         | 是否必选 |
+| ---------------------- | ------------------------------------------------------------ | -------- |
+| -i 或 --input_dir      | 多卡比对结果存盘目录，即使用compare比对的结果输出目录，str类型。所有比对结果应全部为真实数据比对结果或统计数据比对结果，否则可能导致汇总数据不完整。 | 是       |
+| -o 或 --output_dir     | 数据提取汇总结果存盘目录，str类型。文件名称基于时间戳自动生成，格式为：`multi_ranks_compare_merge_{timestamp}.xlsx`。 | 是       |
+| -config或--config-path | 指定需要汇总数据的API和比对指标的yaml文件路径，str类型。<br>yaml文件详细介绍见下文“**yaml文件说明**”。 | 是       |
 
-5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
+**yaml文件说明**
+
+以config.yaml文件名为例，配置示例如下：
 
-## 3 附录
+```
+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)
 
-### 3.1 比对文件
+1. NPU Name列表示API或module名称。
+2. rank*列为多卡数据。
+3. 不同比对指标的数据通过不同sheet页呈现。
+4. 如果一个API或module在某张卡上找不到数据，汇总结果中将空白呈现。
+
+## 4 附录
+
+### 4.1 比对文件
 
 以在当前目录创建./compare.json为例，单卡场景示例如下：
 
@@ -184,17 +252,25 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 }
   ```
 
+多卡场景示例如下：
+```json
+{
+"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。          | 是       |
-| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值true或false，默认为true。关闭后则只输出常规日志。数据类型：bool | 否       |
+| -------------------- | ------------------------------------------------------------ |------|
+| 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 | 否    |
 
-### 3.2 比对文件（kernel）
+### 4.2 比对文件（kernel）
 
 仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持。
 
@@ -232,19 +308,86 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 | 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的数据。默认为空，表示比对所有Step。可配置一个或多个Step，多个Step ID用逗号隔开，例如："step_id": [1,2,3]。数据类型：list[int]。 | 否       |
 
-### 3.3 自定义映射文件（cell）
+### 4.3 自定义映射文件（api_mapping）
 
 文件名格式：\*.yaml，*为文件名，可自定义。
 
 文件内容格式：
 
 ```yaml
-{cell_name}.{class_name}: {module_name}.{class_name}
+ms_api: {ms_api_name}
+pt_api: {pt_api_name}
+ms_args:
+- {index1}
+- {index2}
+...
+- {indexN}
+pt_args:
+- {index1}
+- {index2}
+...
+- {indexN}
+ms_outputs:
+- {index1}
+- {index2}
+...
+- {indexN}
+pt_outputs:
+- {index1}
+- {index2}
+...
+- {indexN}
 ```
 
-冒号左侧为MindSpore框架cell模块的{cell_name}.{class_name}，冒号右侧为PyTorch框架module模块的{module_name}.{class_name}。
+- ms_api/pt_api：分别为MindSpore和PyTorch框架的API名称，配置格式为{api_type}.{api_name}。API名称请分别从《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》中的dump.json文件获取。
+- ms_args/pt_args：分别为ms_api/pt_api对应的MindSpore和PyTorch框架API的入参的序号。
+- ms_outputs/pt_outputs：分别为ms_api/pt_api对应的MindSpore和PyTorch框架API的输出的序号。
+
+**说明**：
+
+- MindSpore和PyTorch框架的API映射关系可以从《[PyTorch与MindSpore API映射表](https://www.mindspore.cn/docs/zh-CN/r2.3.0rc2/note/api_mapping/pytorch_api_mapping.html)》获取，其中PyTorch与MindSpore API名称前缀的映射关系如下：
+
+  | PyTorch             | PyTorch在dump文件中的名称 | MindSpore        | MindSpore在dump文件中的名称 |
+  | ------------------- | ------------------------- | ---------------- | --------------------------- |
+  | torch.nn.functional | Functional                | mindspore.ops    | Functional                  |
+  | torch.Tensor        | Tensor                    | mindspore.Tensor | Tensor                      |
+  | torch               | Torch                     | mindspore.ops    | Functional                  |
+
+  实际配置自定义映射文件（API）时需要使用dump文件中的名称。
+
+- 自定义映射文件（API）需要满足ms_args/pt_args列表中的元素个数一致，ms_outputs/pt_outputs相同。
+
+- 须确保列表自定义映射文件（API）配置元素的合法性，比如ms_args/pt_args的API用到的参数只有3个参数，那么用户实际指定的参数序号只能包含0、1、2；另外参数序号列表中的值不能重复。
+
+文件内容示例：
+
+```yaml
+ms_api: Functional.abs
+pt_api: Torch.abs
+ms_args:
+- 0
+- 1
+pt_args:
+- 0
+- 1
+ms_outputs:
+- 0
+- 1
+pt_outputs:
+- 0
+- 1
+# ms_args/pt_args和ms_outputs/pt_outputs参数的配置需要根据ms_api/pt_api的API入参和输出的顺序，例如Functional.abs API的入参为（a b c），那对应的ms_args为0 1 2，可根据实际需要选择，而Torch.abs的入参如果是（a b c），那么ms_args和pt_args配置一致即可，但如果Torch.abs的入参如果是（a c）或其他与Functional.abs不完全映射的值，那么ms_args和pt_args配置的序号需要与入参对应，Torch.abs（a c）的序号为0 1，Functional.abs（a b c）为0 1 2，只有a和c参数可以映射，那么ms_args配置为0 2，pt_args配置为0 1。ms_outputs/pt_outputs同理。
+```
+
+### 4.4 自定义映射文件（cell_mapping）
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容格式：
 
-{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}.{cell_name}.{class_name}.{前向反向}.{index}.{input/output}.{参数序号}`
+```yaml
+{cell_name}.{class_name}: {module_name}.{class_name}
+```
 
 文件内容示例：
 
@@ -253,7 +396,21 @@ fc2.Dense: fc2.Linear
 conv1.Conv2d: conv3.Conv2d
 ```
 
-### 3.4 自定义映射文件（API和模块）
+冒号左侧为MindSpore框架cell模块的{cell_name}.{class_name}，冒号右侧为PyTorch框架module模块的{module_name}.{class_name}。
+
+```yaml
+{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：
+{Cell}.{cell_name}.{class_name}.{forward/backward}.{index}.{input/output}.{参数序号/参数名}
+或
+{Cell}.{cell_name}.{class_name}.parameters_grad.{parameter_name}
+
+{module_name}.{class_name}从dump module模块级.npy文件名获取，命名格式为：
+{Module}.{module_name}.{class_name}.{forward/backward}.{index}.{input/output}.{参数序号/参数名}
+或
+{Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}
+```
+
+### 4.5 自定义映射文件（data_mapping）
 
 文件名格式：\*.yaml，*为文件名，可自定义。
 
@@ -261,9 +418,11 @@ conv1.Conv2d: conv3.Conv2d
 
 ```yaml
 # API
-{api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}: {api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}
+{api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号/参数名}: {api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号/参数名}
 # 模块
-{Cell}.{cell_name}.{class_name}.{前向反向}.{index}.{input/output}.{参数序号}: {Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}
+{Cell}.{cell_name}.{class_name}.{forward/backward}.{index}.{input/output}.{参数序号/参数名}: {Module}.{module_name}.{class_name}.{forward/backward}.{index}.{input/output}.{参数序号/参数名}
+或
+{Cell}.{cell_name}.{class_name}.parameters_grad.{parameter_name}: {Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}
 ```
 
 冒号左侧为MindSpore框架API的名称和Cell模块的名称，冒号右侧为PyTorch框架API的名称和module模块名称。
@@ -277,9 +436,11 @@ API和模块名称请分别从《[MindSpore 场景的精度数据采集](./06.da
 Functional.flash_attention_score.4.forward.input.0: NPU.npu_fusion_attention.4.forward.input.0
 # 模块
 Cell.relu.ReLU.forward.0.input.0: Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.forward.0.input.0
+或
+Cell.relu.ReLU.parameters_grad.weight: Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.parameters_grad.weight
 ```
 
-API和模块名称在dump.json文件中的“data_name”字段展示，如下图红框处所示：
+当dump.json文件中存在“data_name”字段时，API和模块名称为data_name字段去掉文件后缀，如下图红框处所示：
 
 - MindSpore dump
 
@@ -289,7 +450,145 @@ API和模块名称在dump.json文件中的“data_name”字段展示，如下
 
   ![pt_dump](./img/pt_dump.png)
 
-### 3.5 自定义映射文件（Layer）
+当dump.json文件中不存在“data_name”字段时，名称的拼写规则如下：
+
+input_args、input_kwargs和output使用统一的命名规则，当值是list类型时，名称后面添加'.{index}'，当值类型是dict类型时，名称后面加'.{key}'，当值类型是具体Tensor或null或空list/dict时，命名结束。
+
+以下面cell的dump文件为例：
+```yaml
+"Cell.network.module.NetworkWithLoss.forward.0": {
+  "input_args": [
+    {
+      "type": "mindspore.Tensor",
+      "dtype": "Float32",
+      "shape": [
+        24,
+        16,
+        1,
+        60,
+        34
+      ],
+      "Max": 3.591925621032715,
+      "Min": -3.6856653690338135,
+      "Mean": -0.017044123262166977,
+      "Norm": 940.671630859375,
+      "md5": "00d69ba8"
+    },
+    {
+      "y": {
+        "type": "mindspore.Tensor",
+        "dtype": "Float32",
+        "shape": [
+          24,
+          1,
+          100,
+          4096
+        ],
+        "Max": 2.433350086212158,
+        "Min": -4.09375,
+        "Mean": -0.00010696164099499583,
+        "Norm": 170.3390655517578,
+        "md5": "a72e1fa4"
+      },
+      "y_mask": {
+        "type": "mindspore.Tensor",
+        "dtype": "Float32",
+        "shape": [
+          24,
+          100
+        ],
+        "Max": 1.0,
+        "Min": 0.0,
+        "Mean": 0.22999998927116394,
+        "Norm": 23.494680404663086,
+        "md5": "bbcbd5ab"
+      },
+      "x_mask": {
+        "type": "mindspore.Tensor",
+        "dtype": "Float32",
+        "shape": [
+          24,
+          510
+        ],
+        "Max": 1.0,
+        "Min": 1.0,
+        "Mean": 1.0,
+        "Norm": 110.63453674316406,
+        "md5": "766d1028"
+      },
+      "loss_mask": {
+        "type": "mindspore.Tensor",
+        "dtype": "Float32",
+        "shape": [
+          24,
+          1,
+          60,
+          34
+        ],
+        "Max": 1.0,
+        "Min": 1.0,
+        "Mean": 1.0,
+        "Norm": 221.26907348632812,
+        "md5": "0cb690ce"
+      },
+      "data_info": {
+        "img_hw": null
+      }
+    }
+  ],
+"input_kwargs": {},
+"output": [
+{
+"type": "mindspore.Tensor",
+"dtype": "Float32",
+"shape": [],
+"Max": 0.3672327995300293,
+"Min": 0.3672327995300293,
+"Mean": 0.3672327995300293,
+"Norm": 0.3672327995300293,
+"md5": "28f8f74f"
+}
+]
+} 
+```
+,
+初始名称为`Cell.network.module.NetworkWithLoss.forward.0`，`input_args`是`list`，长度为2，按照顺序命名为
+```
+Cell.network.module.NetworkWithLoss.forward.0.input.0
+Cell.network.module.NetworkWithLoss.forward.0.input.1
+```
+第0项后面直接是`Tensor`，命名结束
+第1项后面是`dict`，key包括`y`、`y_mask`、`x_mask`和`data_info`，命名为
+```
+Cell.network.module.NetworkWithLoss.forward.0.input.1.y
+Cell.network.module.NetworkWithLoss.forward.0.input.1.y_mask
+Cell.network.module.NetworkWithLoss.forward.0.input.1.x_mask
+Cell.network.module.NetworkWithLoss.forward.0.input.1.data_info
+```
+`y`后面是`Tensor`，命名结束；`y_mask`后面是`Tensor`，命名结束；`x_mask`后面是`Tensor`，命名结束；`data_info`后面是`dict`，key是`img_hw`，命名为
+```
+Cell.network.module.NetworkWithLoss.forward.0.input.1.data_info.img_hw
+```
+`img_hw`后面是`null`，命名结束。
+
+`input_kwargs`是`dict`，长度为0，命名结束。
+`output`是`list`，长度为1，按照顺序命名为
+```
+Cell.network.module.NetworkWithLoss.forward.0.output.0
+```
+第0项后面是`Tensor`，命名结束。
+
+综上，生成的op_name为：
+```
+Cell.network.module.NetworkWithLoss.forward.0.input.0
+Cell.network.module.NetworkWithLoss.forward.0.input.1.y
+Cell.network.module.NetworkWithLoss.forward.0.input.1.y_mask
+Cell.network.module.NetworkWithLoss.forward.0.input.1.x_mask
+Cell.network.module.NetworkWithLoss.forward.0.input.1.data_info.img_hw
+Cell.network.module.NetworkWithLoss.forward.0.output.0
+```
+
+### 4.6 自定义映射文件（Layer_mapping）
 
 文件名格式：\*.yaml，*为文件名，可自定义。
 
@@ -315,13 +614,6 @@ PipelineCell:
 
 Cell:
   network_with_loss: module
-
-layers:                           # 手动映射MindSpore与PyTorch模型代码中的Layer层序号
-  '5': '0'
-  '6': '1'
-  '7': '2'
-  '8': '3'
-  '9': '4'
 ```
 
 Layer层名称需要从模型代码中获取。
@@ -330,4 +622,4 @@ yaml文件中只需配置MindSpore与PyTorch模型代码中功能一致但名称
 
 模型代码示例：
 
-![ms_dump](./img/ms_layer.png)
+![ms_dump](./img/ms_layer.png)

msprobe/docs/12.overflow_check_PyTorch.md

@@ -26,7 +26,7 @@ msprobe 工具在 PyTorch 场景下提供溢出数据采集功能和溢出数据
 
 ### 1.5 其他说明
 
-溢出数据采集功能在昇腾 NPU 上支持饱和模式和 INF/NAN 模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品（如 910A），默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品（如 910B），默认为 INF/NAN 模式，且不建议使用饱和模式。
+溢出数据采集功能在昇腾 NPU 上支持饱和模式和 INF/NAN 模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。
 
 INF/NAN 模式的使能方式如下：
 
@@ -53,7 +53,7 @@ export INF_NAN_MODE_ENABLE=1
 2. 执行溢出 API 解析操作。
 
    ```bash
-   msprobe -f pytorch run_overflow_check -api_info ./dump.json
+   msprobe -f pytorch run_overflow_check -api_info ./dump_path/step{step_number}/rank{rank_number}/dump.json
    ```
    
 | 参数名称                   | 说明                                 | 是否必选 |

msprobe/docs/13.overflow_check_MindSpore.md

@@ -1,8 +1,8 @@
 # MindSpore 场景的溢出检测
 
-msprobe 工具提供静态图O2编译等级下的过程溢出检测与动态图场景下的结果溢出检测。其中前者检测对象为 kernel 级别，对应 config.json 配置中的 "L2" level，后者检测对象为 API 级别(支持的API类型为ops、Tensor、mint和mint.nn.functional，不支持Primitive和Jit类API)，对应 config.json 配置中的 "L1" level。
+msprobe 工具提供静态图O2编译等级下与动态图场景下的溢出检测功能。其中前者检测对象为 **kernel** 级别，对应 config.json 配置中的 **"L2"** level，后者检测对象为 **API** 级别(支持的API类型为ops、Tensor、mint和mint.nn.functional，不支持Primitive和Jit类API)或 **cell** 级别，分别对应 config.json 配置中的 **"L1"** 、**"L0"** level。
 
-需要注意，动态图场景下的溢出检测功能仅支持 INF/NAN 模式<sup>a</sup>。INF/NAN 模式的使能方式如下：
+需要注意，本工具仅支持在 INF/NAN 模式<sup>a</sup>下进行溢出检测。INF/NAN 模式的使能方式如下：
 
 ```Shell
 # 使能 CANN 侧 INF/NAN 模式
@@ -11,21 +11,21 @@ export INF_NAN_MODE_ENABLE=1
 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 框架侧配置须一致。
+**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 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**1 接口介绍**"章节。
+溢出检测功能提供的接口与数据采集任务一致，详见MindSpore 场景的精度数据采集中的["**1 接口介绍**"](./06.data_dump_MindSpore.md#1-接口介绍)章节。
 
 需要注意，目前暂不支持动态图 "L1" level 下 primitive op 的溢出检测。
 
 ## 2 示例代码
 
-溢出检测功能使用方式与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**2 示例代码**"章节。
+溢出检测功能使用方式与数据采集任务一致，详见MindSpore 场景的精度数据采集中的["**2 示例代码**"](./06.data_dump_MindSpore.md#2-示例代码)节。
 
 ## 3 溢出检测结果文件介绍
 
-溢出检测结果文件目录结构与含义与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**3 dump 结果文件介绍**"章节。
+溢出检测结果文件目录结构与含义与数据采集任务一致，但仅保存溢出 API 或 kernel 的真实数据或统计信息。详见MindSpore 场景的精度数据采集中的["**3 dump 结果文件介绍**"](./06.data_dump_MindSpore.md#3-dump-结果文件介绍)章节。

msprobe/docs/15.free_benchmarking_PyTorch.md

@@ -64,8 +64,6 @@ D-->config.json配置
     "rank": [],  
     "step": [],  
     "level": "L1", 
-    "seed": 1234,
-    "is_deterministic": false, 
 
     "free_benchmark": {
         "scope": [], 
@@ -98,14 +96,15 @@ D-->config.json配置
     <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
     <tr><td rowspan="6">pert_mode</td><td rowspan="6">否</td><td>"improve_precision" （默认）</td><td>（常用）(可做验证) 插桩算子可能在<b>低精度</b>下有精度问题，扰动因子会将输入的低精度向量升精度。</td></tr>
     <tr><td>"bit_noise"</td><td>（常用）插桩算子可能在<b>轻微扰动</b>下暴露精度问题，扰动因子会将输入向量最后一个比特位翻转。</td></tr>
-    <tr><td>"add_noise"</td><td>插桩算子可能在<b>轻微扰动</b>下暴露精度问题，扰动因子会为输入向量增加一个极小。</td></tr>
-    <tr><td>"change_value"</td><td>插桩算子可能存在<b>大数吃小数</b>问题，扰动因子会交换输入向量的首尾。</td></tr>
-    <tr><td>"no_change"</td><td>插桩算子可能存在<b>数值稳定性</b>精度问题，扰动因子会复制原始输。</td></tr>
+    <tr><td>"add_noise"</td><td>插桩算子可能在<b>轻微扰动</b>下暴露精度问题，扰动因子会为输入向量增加一个极小值。</td></tr>
+    <tr><td>"change_value"</td><td>插桩算子可能存在<b>大数吃小数</b>问题，扰动因子会交换输入向量的首尾值。</td></tr>
+    <tr><td>"no_change"</td><td>插桩算子可能存在<b>数值稳定性</b>精度问题，扰动因子会复制原始输入。</td></tr>
     <tr><td>"to_cpu"</td><td>(可做验证) 插桩算子可能在<b>同 CPU </b>精度表现不一致，扰动因子会将输入转至 CPU，需要配合 fuzz_device="cpu"使用。</td></tr>
     <tr><td rowspan="2">fuzz_device</td><td rowspan="2">否</td><td>"npu" （默认）</td><td>pert_mode 不需要to cpu操作。</td></tr>
     <tr><td>"cpu"</td><td>pert_mode 须配置为"to_cpu"，目前仅支持"to cpu"扰动因子。</td></tr>
 </table>
 
+
 #### 3.2.3 选择处理方式
 
 <table>