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

msprobe/docs/11.accuracy_compare_MindSpore.md

@@ -4,19 +4,25 @@
 
 msprobe精度比对工具主要用于如下场景：
 
-- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到API dump数据后，对这两个API dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
-- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到kernel dump数据后，对这两个kernel dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
-- 通过对同一个网络模型，在两个不同版本的MindSpore动态图环境下，输入相同的训练数据，在分别得到cell dump数据后，对这两个cell模块进行全量自动比对，从而快速定位不同版本之间的精度问题。
-- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API dump数据，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
-- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得cell dump数据，由用户指定可以比对的cell list，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+- MindSpore框架内比对
+  - 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到API dump数据后，对这两个API dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+  - 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到kernel dump数据后，对这两个kernel dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+  - 通过对同一个网络模型，在两个不同版本的MindSpore动态图环境下，输入相同的训练数据，在分别得到cell dump数据后，对这两个cell模块进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- MindSpore与PyTorch跨框架比对
+  - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API dump数据，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+  - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得cell dump数据，由用户指定可以比对的cell list，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+  - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API或模块dump数据，由用户指定可以比对的API或模块，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+  - 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API或模块dump数据，由用户指定可以比对的模型代码中的Layer层，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
 
-执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
+执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../README.md)》的“工具安装”章节。
 
-## 2 命令行方式
+## 2 命令行比对
 
 精度比对工具目前使用方式为命令行形式。
 
-### 2.1 命令格式说明
+### 2.1 比对命令说明
+
+命令示例如下：
 
 ```shell
 msprobe -f mindspore compare -i ./compare.json -o ./output -s
@@ -24,15 +30,19 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 **完整参数说明**
 
-| 参数名              | 说明                                                         | 是否必选 |
-| ------------------- | ------------------------------------------------------------ | -------- |
-| -i或--input_path    | 指定比对文件。比对文件内容及示例请参见[比对文件](#31-比对文件)或[比对文件（kernel）](#32-比对文件（kernel）)（比对文件（kernel）仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
-| -o或--output_path   | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：<br>        `compare_result_{timestamp}.xlsx`<br/>        `compare_result_{rank_id}_{step_id}_{timestamp}.xlsx`（仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
-| -s或--stack_mode    | 配置stack_mode的开关。仅当[比对文件](#31-比对文件)配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
-| -c或--compare_only  | 仅比对开关。该参数默认未配置，表示关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否       |
-| -f或--fuzzy_match   | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
-| -am或--api_mapping  | 跨框架比对。配置该参数时表示开启跨框架API比对功能。仅[跨框架的API比对](#25-跨框架的API比对)场景支持。 | 否       |
-| -cm或--cell_mapping | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件](#33-自定义映射文件)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景支持。 | 否       |
+| 参数名               | 说明                                                         | 是否必选 |
+| -------------------- | ------------------------------------------------------------ | -------- |
+| -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）](#33-自定义映射文件api)。仅[跨框架的API比对](#25-跨框架的api比对)场景需要配置。 | 否       |
+| -cm或--cell_mapping  | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件（cell）](#34-自定义映射文件cell)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景需要配置。 | 否       |
+| -dm或--data_mapping  | 跨框架比对。配置该参数时表示开启跨框架API或模块的比对功能，需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（API和模块）](#35-自定义映射文件api和模块)。仅[跨框架的API或模块比对](#27-跨框架的api或模块比对)场景需要配置。 | 否       |
+| -lm或--layer_mapping | 跨框架比对。配置该参数时表示开启跨框架Layer层的比对功能，指定模型代码中的Layer层后，可以识别对应dump数据中的模块或API。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件（Layer）](#36-自定义映射文件layer)。仅[跨框架的Layer层比对](#28-跨框架的layer层比对)场景需要配置。 | 否       |
+
+动态图模式没有填写任何mapping时，按照同框架比对的方式进行比对，比对数据和标杆数据的Cell或Api名称需要完全相同才能匹配得上。
 
 ### 2.2 不同版本下的全量API比对
 
@@ -46,13 +56,13 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s
    ```
 
-4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.3 不同版本下的全量kernel比对
 
 1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的kernel dump数据。
 
-2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#32-比对文件（kernel）)。
+2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#32-比对文件kernel)。
 
 3. 执行如下示例命令进行比对：
 
@@ -60,7 +70,9 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output
    ```
 
-4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+   该场景仅支持compare的-i和-o参数。
+
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.4 不同版本下的cell模块比对
 
@@ -76,7 +88,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s
    ```
 
-5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.5 跨框架的API比对
 
@@ -92,7 +104,16 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -am
    ```
 
-5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+   或
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -am api_mapping.yaml
+   ```
+
+   api_mapping.yaml文件配置请参见[自定义映射文件（API）](#33-自定义映射文件api)。
+   不传入api_mapping.yaml的情况下将按照内置的api映射进行匹配；传入api_mapping.yaml的情况下优先按照api_mapping.yaml的内容进行匹配，api_mapping.yaml中没有涉及的按照内置的api映射进行匹配。
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.6 跨框架的cell模块比对
 
@@ -114,7 +135,50 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
    msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm cell_mapping.yaml
    ```
 
-5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+   cell_mapping.yaml文件配置请参见[自定义映射文件（cell）](#34-自定义映射文件cell)。
+   不传入cell_mapping.yaml的情况下仅将Cell改成Module后进行匹配；传入cell_mapping.yaml的情况下将按照cell_mapping.yaml的内容进行匹配。
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
+
+### 2.7 跨框架的API或模块比对
+
+该场景可用于在“**跨框架的API比对**”和“**跨框架的cell模块比对**”场景均无法完全覆盖模型中的API和模块时，通过手动指定映射关系来补全未被比对的API或模块。
+
+1. 配置[config.json](../config.json)文件level配置为L0或L1、task配置为tensor或statistics并指定需要dump的API或模块名。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API或模块精度数据的采集，得到两个框架的API或模块dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
+   ```
+
+   data_mapping.yaml文件配置请参见[自定义映射文件（all）](#35-自定义映射文件api和模块)。
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
+
+### 2.8 跨框架的Layer层比对
+
+该场景可简化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数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -lm layer_mapping.yaml
+   ```
+
+   layer_mapping.yaml文件配置请参见[自定义映射文件（Layer）](#36-自定义映射文件layer)。
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ## 3 附录
 
@@ -132,6 +196,14 @@ 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
+}
+```
 
 **参数说明**
 
@@ -140,7 +212,7 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 | 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 | 否       |
+| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值true或false，默认为true。关闭后则只输出常规日志。数据类型：bool | 否       |
 
 ### 3.2 比对文件（kernel）
 
@@ -175,24 +247,95 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 
 | 参数名     | 说明                                                         | 是否必选 |
 | ---------- | ------------------------------------------------------------ | -------- |
-| npu_path   | 配置NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
-| bench_path | 配置CPU、GPU或NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
+| npu_path   | 配置NPU环境下的真实数据目录。数据类型：str。                 | 是       |
+| bench_path | 配置NPU环境下的真实数据目录。数据类型：str。                 | 是       |
 | rank_id    | 配置比对的Rank ID。npu_path和bench_path目录下的dump文件需要存在对应Rank的数据。默认为空，表示比对所有Rank。可配置一个或多个Rank，多个Rank ID用逗号隔开，例如："rank_id": [1,2,3]。数据类型：list[int]。 | 否       |
-| step_id    | 配置比对的Step ID。npu_path和bench_path目录下的dump文件需要存在对应Step的数据。默认为空，表示比对所有Sank。可配置一个或多个Sank，多个Sank ID用逗号隔开，例如："step_id": [1,2,3]。数据类型：list[int]。 | 否       |
+| step_id    | 配置比对的Step ID。npu_path和bench_path目录下的dump文件需要存在对应Step的数据。默认为空，表示比对所有Step。可配置一个或多个Step，多个Step ID用逗号隔开，例如："step_id": [1,2,3]。数据类型：list[int]。 | 否       |
 
-### 3.3 自定义映射文件
+### 3.3 自定义映射文件（API）
 
 文件名格式：\*.yaml，*为文件名，可自定义。
 
 文件内容格式：
 
 ```yaml
-{cell_name}.{class_name}: {cell_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框架cell模块的{cell_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                  |
 
-{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}_{cell_name}_{class_name}_{前向反向}.{index}.{input/output}.{参数序号}`
+  实际配置自定义映射文件（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同理。
+```
+
+### 3.4 自定义映射文件（cell）
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容格式：
+
+```yaml
+{cell_name}.{class_name}: {module_name}.{class_name}
+```
+
+冒号左侧为MindSpore框架cell模块的{cell_name}.{class_name}，冒号右侧为PyTorch框架module模块的{module_name}.{class_name}。
+
+{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}.{cell_name}.{class_name}.{前向反向}.{index}.{input/output}.{参数序号}`
 
 文件内容示例：
 
@@ -200,3 +343,82 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 fc2.Dense: fc2.Linear
 conv1.Conv2d: conv3.Conv2d
 ```
+
+### 3.5 自定义映射文件（API和模块）
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容格式：
+
+```yaml
+# API
+{api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}: {api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}
+# 模块
+{Cell}.{cell_name}.{class_name}.{前向反向}.{index}.{input/output}.{参数序号}: {Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}
+```
+
+冒号左侧为MindSpore框架API的名称和Cell模块的名称，冒号右侧为PyTorch框架API的名称和module模块名称。
+
+API和模块名称请分别从《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》中的dump.json文件获取。
+
+文件内容示例：
+
+```yaml
+# API
+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
+```
+
+API和模块名称在dump.json文件中的“data_name”字段展示，如下图红框处所示：
+
+- MindSpore dump
+
+  ![ms_dump](./img/ms_dump.png)
+
+- PyTorch dump
+
+  ![pt_dump](./img/pt_dump.png)
+
+### 3.6 自定义映射文件（Layer）
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容示例：
+
+```yaml
+ParallelAttention:                 # Layer层名称
+  qkv_proj: query_key_value        # 冒号左侧为MindSpore框架模型代码中嵌套的Layer层名称，冒号右侧为PyTorch框架模型代码中嵌套的Layer层名称
+  out_proj: dense
+
+ParallelTransformerLayer:
+  attention: self_attention
+
+Embedding:
+  dropout: embedding_dropout
+
+ParallelMLP:
+  mapping: dense_h_to_4h
+  projection: dense_4h_to_h
+
+PipelineCell:
+  model: module
+
+Cell:
+  network_with_loss: module
+
+layers:                           # 手动映射MindSpore与PyTorch模型代码中的Layer层序号
+  '5': '0'
+  '6': '1'
+  '7': '2'
+  '8': '3'
+  '9': '4'
+```
+
+Layer层名称需要从模型代码中获取。
+
+yaml文件中只需配置MindSpore与PyTorch模型代码中功能一致但名称不同的Layer层，名称相同的Layer层会被自动识别并映射。
+
+模型代码示例：
+
+![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 模式的使能方式如下：
 

msprobe/docs/13.overflow_check_MindSpore.md

@@ -1,8 +1,8 @@
 # MindSpore 场景的溢出检测
 
-msprobe 工具提供静态图O2编译等级下的过程溢出检测与动态图场景下的结果溢出检测。其中前者检测对象为 kernel 级别，对应 config.json 配置中的 "L2" level，后者检测对象为 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

@@ -1,26 +1,26 @@
 # PyTorch 场景的无标杆比对
 
 ## 1 简介
-* 本工具的目标是在不依赖标杆数据的情况下、检测模型训练中可能存在的精度问题API级别算子，并提供升精度和tocpu接口快速验证；
-* 工具基于**数值病态分析理论**：对算子的输入增加很小的扰动、从而放大输出值异常现象；检测算子原始输出和扰动后输出间误差是否符合精度标准；
+* 本工具的目标是在不依赖标杆数据的情况下，检测模型训练中可能存在的精度问题API级别算子，并提供升精度和tocpu接口快速验证。
+* 工具基于**数值病态分析理论**：对算子的输入增加很小的扰动，从而放大输出值异常现象；检测算子原始输出和扰动后输出间误差是否符合精度标准。
 
 * 该工具的**特点**有：
-    * 不依赖标杆模型、不需要离线对比
-    * 提供接口，对可疑算子升精度、tocpu进行快速验证
+    * 不依赖标杆模型，不需要离线对比；
+    * 提供接口，对可疑算子升精度，tocpu进行快速验证。
 * 推荐使用场景（针对**算子精度问题**）：
-    * **暂无标杆数据**，模型Loss异常，要做精度问题算子排查
-    * **验证可疑算子**，要做进一步确认、验证是否对模型Loss有影响
-    * 低精度模型效果不如高精度，要做精度问题算子排查
+    * **暂无标杆数据**，模型Loss异常，要做精度问题算子排查；
+    * **验证可疑算子**，要做进一步确认，验证是否对模型Loss有影响；
+    * 低精度模型效果不如高精度，要做精度问题算子排查。
 * 该工具的约束
-    * 仅支持Pytorch2.x场景
-    * 推荐限定算子范围使用（白名单、或脚本中工具启用范围）、算子范围越大、性能和显存损耗越大；详情见[无标杆工具场景验证和性能基线报告(待补充)](./S02.report_free_benchmarking_validation_performance_baseline.md)
+    * 仅支持Pytorch2.x场景；
+    * 推荐限定算子范围使用（白名单，或脚本中工具启用范围），算子范围越大，性能和显存损耗越大；详情见[无标杆比对功能在 PyTorch 场景的性能基线报告](./S02.report_free_benchmarking_validation_performance_baseline.md)
 
 ## 2 工具实现原理
-1. **扰动算子白名单**：根据算子名识别需要插桩算子范围
-2. **扰动因子**：基于torch.nn.Module的hook机制、在注册的hook函数中对算子输入进行特定类型扰动
+1. **扰动算子白名单**：根据算子名识别需要插桩算子范围。
+2. **扰动因子**：基于torch.nn.Module的hook机制，在注册的hook函数中对算子输入进行特定类型扰动。
 3. **误差分析**：
-    * **check**: 在hook函数中二次执行算子得到扰动后的算子输出、计算扰动后输出与原始输出的相对误差，查看是否符合精度标准
-    * **fix**: 需要做验证时、可以选择将特定扰动类型（升精度、to cpu）的输出替换原始输出、观察对模型Loss是否有影响
+    * **check**: 在hook函数中二次执行算子得到扰动后的算子输出，计算扰动后输出与原始输出的相对误差，查看是否符合精度标准；
+    * **fix**: 需要做验证时，可以选择将特定扰动类型（升精度，to cpu）的输出替换原始输出，观察对模型Loss是否有影响。
 4. **精度风险算子**：不达标精度标准的，最终会在输出件中展示
 
 ![alt text](./img/free_benchmark_framework.png)
@@ -50,11 +50,11 @@ D-->config.json配置
 ```
 工具的推荐使用思路是：
 
-1. 配置config.json开启精度风险算子的排查
-2. 根据精度风险算子输出件、修改config.json开启验证功能、观察模型loss曲线是否改善 
+1. 配置config.json开启精度风险算子的排查；
+2. 根据精度风险算子输出件，修改config.json开启验证功能，观察模型loss曲线是否改善。
 
 ### 3.1 安装msprobe工具
-参照[msprobe安装](./docs/01.installation.md)
+参照[msprobe安装](./01.installation.md)
 ### 3.2 config.json配置
 修改[config.json](../config.json) 的task类型为"**free_benchmark**"开启无标杆功能。支持的配置项详见[配置文件介绍](./02.config_introduction.md)，默认配置如下：
 ```json
@@ -64,8 +64,6 @@ D-->config.json配置
     "rank": [],  
     "step": [],  
     "level": "L1", 
-    "seed": 1234,
-    "is_deterministic": false, 
 
     "free_benchmark": {
         "scope": [], 
@@ -81,34 +79,39 @@ D-->config.json配置
     }
 }
 ```
-用户需根据自己的使用场景、对<a herf="2 工具实现原理">工具实现原理</a>中几个关键步骤进行配置
-####  3.2.1 扰动算子白名单（确定插桩范围）：
-
-| 相关参数名 | 是否必选 | 可配置项          | 适用场景                                                                                    |
-| ---------- | -------- | ----------------- | ------------------------------------------------------------------------------------------- |
-| scope      | 可选     |                   | 需要通过指定算子名来限制算子插桩范围 如：["Torch.matmul.0.forward", "Tensor.pow.4.forward"] |
-| list       | 可选     |                   | 需要通过指定算子类型来限制算子插桩范围 如：\["relu"\] 会匹配所有算子名中包含relu的算子      |
-| fuzz_stage | 可选     | "forward"（默认） | 需要进行算子**前向**计算的精度问题排查或**验证可疑算子**                                    |
-|            |          | "backward"        | 需要进行算子**反向**计算的精度问题排查，不支持仅反向验证，前向验证包括反向                  |
-
-####  3.2.2. 选择扰动因子：
-
-| 相关参数    | 是否必选 | 可配置项                     | 适用场景                                                                                                 |
-| ----------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
-| pert_mode   | 可选     | "improve_precision" （默认） | （常用）(可做验证) 插桩算子可能在**低精度**下有精度问题，扰动因子会将输入的低精度向量升精度              |
-|             |          | "bit_noise"                  | （常用）插桩算子可能在**轻微扰动**下暴露精度问题，扰动因子会将输入向量最后一个比特位翻转                 |
-|             |          | "add_noise"                  | 插桩算子可能在**轻微扰动**下暴露精度问题，扰动因子会为输入向量增加一个极小值                             |
-|             |          | "change_value"               | 插桩算子可能存在**大数吃小数**问题，扰动因子会交换输入向量的首尾值                                       |
-|             |          | "no_change"                  | 插桩算子可能存在**数值稳定性**精度问题，扰动因子会复制原始输入                                           |
-|             |          | "to_cpu"                     | (可做验证) 插桩算子可能在**同cpu**精度表现不一致，扰动因子会将输入转至cpu，需要配合fuzz_device="cpu"使用 |
-| fuzz_device | 可选     | "npu" （默认）                 | 扰动因子不需要to cpu操作                                                                                 |
-|             |          | "cpu"                        | 扰动因子需要to cpu操作，目前仅"to cpu"扰动因子                                                           |
-
-####  3.2.3. 选择处理方式:
-| 相关参数名   | 是否必选 | 可配置项          | 适用场景                                                                                  |
-| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------------------- |
-| handler_type | 可选     | "check"  （默认） | 要做精度问题算子排查，输出扰动前后不符合精度标准的算子，支持所有扰动因子                  |
-|              |          | "fix"             | 要做可疑算子验证，用扰动后输出替换原始输出，支持"improve_precision"、"to_cpu"两种扰动因子 |
+用户需根据自己的使用场景，对[工具实现原理](#2-工具实现原理)中几个关键步骤进行配置。
+#### 3.2.1 扰动算子白名单（确定插桩范围）
+
+<table>
+    <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
+    <tr><td>scope</td><td>否</td><td>自定义</td><td>需要通过指定算子名来限制算子插桩范围 如：["Torch.matmul.0.forward", "Tensor.pow.4.forward"]。</td></tr>
+    <tr><td>list</td><td>否</td><td>自定义</td><td>需要通过指定算子类型来限制算子插桩范围 如：["relu"] 会匹配所有算子名中包含relu的算子。</td></tr>
+    <tr><td rowspan="2">fuzz_stage</td><td rowspan="2">否</td><td>"forward"（默认）</td><td>需要进行算子<b>前向</b>计算的精度问题排查或<b>验证可疑算子。</b></td></tr>
+    <tr><td>"backward"</td><td>需要进行算子<b>反向</b>计算的精度问题排查，不支持仅反向验证，前向验证包括反向。</td><td></td></tr>
+</table>
+
+#### 3.2.2 选择扰动因子
+
+<table>
+    <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>"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>
+    <tr><th>参数</th><th>是否必选</th><th>可配置项</th><th>适用场景</th></tr>
+    <tr><td rowspan="2">handler_type</td><td rowspan="2">否</td><td>"check"（默认）</td><td>要做精度问题算子排查，输出扰动前后不符合精度标准的算子，支持所有扰动因子。</td></tr>
+    <tr><td>"fix"</td><td>要做可疑算子验证，用扰动后输出替换原始输出，支持"improve_precision"，"to_cpu"两种扰动因子。</td></tr>
+</table>
 
 ### 3.3 在模型脚本中开启工具
 
@@ -126,15 +129,17 @@ debugger.step() # 在训练循环的最后需要重置工具，非循环场景
 ```
 
 ### 3.4 启动模型训练
-训练过程中出现可以通过一下日志检查工具是否正常使用
-| 日志级别 | 日志内容                                                                                                              | 检查说明                                                                   |
-| -------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| INFO     | \[msprobe\] Free Benchmark: Perturbation is {扰动因子} of {算子名}.                                                   | 扰动因子与配置相符、算子名在插桩范围内                                     |
-| INFO     | \[msprobe\] Free Benchmark: For {算子名},{原因}. Cancel perturbation.                                                 | 算子名在插桩范围内，但当前算子由于{原因}不支持添加扰动                     |
-| INFO     | \[msprobe\] Free benchmark: preheat sample in step {step} api_name {算子名} curr_called_seq: {当前采样数}/{总采样数}" | 仅开启预热、算子名在插桩范围内，在当前step的采样情况                       |
-| WARNING  | \[msprobe\] Free benchmark: 无标杆工具不支持当前算子的输入类型 {算子名}.                                              | 算子名在插桩范围内，但当前算子没有可操作的输入（不存在Tensor、list类型等） |
-
-其余日志均说明当前算子未能正常添加扰动、请检查日志信息判断是否更换扰动因子或不考虑当前算子结果。
+训练过程中出现以下日志，可以检查工具是否正常使用。
+
+<table>
+    <tr><th>日志级别</th><th>日志内容</th><th>检查说明</th></tr>
+    <tr><td rowspan="3">INFO</td><td>[msprobe] Free Benchmark: Perturbation is {扰动因子} of {算子名}.</td><td>扰动因子与配置相符，算子名在插桩范围内。</td></tr>
+    <tr><td>[msprobe] Free Benchmark: For {算子名},{原因}. Cancel perturbation.</td><td>算子名在插桩范围内，但当前算子由于{原因}不支持添加扰动。</td></tr>
+    <tr><td>[msprobe] Free benchmark: preheat sample in step {step} api_name {算子名} curr_called_seq: {当前采样数}/{总采样数}"</td><td>仅开启预热，算子名在插桩范围内，在当前step的采样情况。</td></tr>
+    <tr><td>WARNING</td><td>[msprobe] Free benchmark: 无标杆工具不支持当前算子的输入类型 {算子名}.</td><td>算子名在插桩范围内，但当前算子没有可操作的输入（不存在Tensor，list类型等）。</td></tr>
+</table>
+
+其余日志均说明当前算子未能正常添加扰动，请检查日志信息判断是否更换扰动因子或不考虑当前算子结果。
 
 
 ### 3.5 查看精度风险算子