mindstudio-probe 1.0.4__py3-none-any.whl → 1.1.0__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,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   | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：<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    | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：<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   | 仅比对开关，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层比对)场景需要配置。 | 否       |
 
 ### 2.2 不同版本下的全量API比对
 
@@ -46,13 +54,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 +68,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 +86,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 +102,7 @@ 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-精度比对结果分析)]》章节。
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ### 2.6 跨框架的cell模块比对
 
@@ -114,7 +124,49 @@ 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）](#33-自定义映射文件cell)。
+
+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）](#34-自定义映射文件all)。
+
+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）](#35-自定义映射文件layer)。
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)》章节。
 
 ## 3 附录
 
@@ -140,7 +192,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 +227,24 @@ 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 自定义映射文件（cell）
 
 文件名格式：\*.yaml，*为文件名，可自定义。
 
 文件内容格式：
 
 ```yaml
-{cell_name}.{class_name}: {cell_name}.{class_name}
+{cell_name}.{class_name}: {module_name}.{class_name}
 ```
 
-左侧为MindSpore框架cell模块的{cell_name}.{class_name}，右侧为PyTorch框架cell模块的{cell_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}.{参数序号}`
+{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}.{cell_name}.{class_name}.{前向反向}.{index}.{input/output}.{参数序号}`
 
 文件内容示例：
 
@@ -200,3 +252,82 @@ msprobe -f mindspore compare -i ./compare.json -o ./output -s
 fc2.Dense: fc2.Linear
 conv1.Conv2d: conv3.Conv2d
 ```
+
+### 3.4 自定义映射文件（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.5 自定义映射文件（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/13.overflow_check_MindSpore.md

@@ -1,6 +1,6 @@
 # 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)，对应 config.json 配置中的 "L1" level。
 
 需要注意，动态图场景下的溢出检测功能仅支持 INF/NAN 模式<sup>a</sup>。INF/NAN 模式的使能方式如下：
 

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
@@ -81,34 +81,38 @@ 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 +130,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 查看精度风险算子

msprobe/docs/16.free_benchmarking_MindSpore.md

@@ -0,0 +1,140 @@
+# MindSpore 场景的无标杆比对
+
+## 1 简介
+* 本工具的目标是在没有标杆数据的情况下，检测模型训练中可能存在精度问题的 API 级别算子，并提供升精度接口进行快速验证。
+* 工具基于**数值病态分析理论**：对算子的输入增加很小的扰动、从而放大输出值异常现象；检测算子原始输出和扰动后输出间误差是否符合精度标准。
+
+* 该工具的**特点**有：
+    * 不依赖标杆模型，在线对比。
+    * 提供升精度接口，对可疑算子进行快速验证。
+* 推荐使用场景（针对**API 精度问题**）：
+    * **暂无标杆数据**，模型 Loss 异常，要做精度问题 API 排查。
+    * 低精度模型效果不如高精度，要做精度问题 API 排查。
+    * **验证低精度可疑 API**，确认升精度后是否对模型 Loss 有影响。
+* 该工具的约束
+    * 仅支持 MindSpore 动态图场景。支持的 API 类型为 ops、Tensor、mint 和 mint.nn.functional 类的非 inplace 计算 API，不支持 Primitive 和 Jit 类 API。
+    * 建议配置白名单（设置 list），控制对少量 API 进行无标杆比对。比对 API 越多，性能和显存损耗越大。
+
+## 2 工具实现原理
+1. **扰动算子白名单**：根据 API 名，控制需要进行无标杆比对的 API。
+
+2. **扰动因子**：基于 mindspore.nn.Cell 的 hook 机制，在注册的 hook 函数中对算子输入进行特定类型扰动。
+
+3. **误差分析**：
+    * **check**: 在 hook 函数中二次执行算子得到扰动后的算子输出、计算扰动后输出与原始输出的相对误差，查看是否符合精度标准。
+    * **fix**: 需要做验证时，可以将升精度的输出替换原始输出，观察对模型 Loss 是否有影响。
+
+4. **精度风险算子**：不达标精度标准的，最终会在输出件中展示。
+
+## 3 操作指导
+
+```mermaid
+flowchart LR
+A0[安装msprobe工具]
+subgraph config.json配置
+A1[确定比对范围]
+A2[选择扰动因子]
+A3[选择处理方式]
+A1-->A2
+A2-->A3
+end
+B(在模型脚本中开启工具)
+C(启动模型训练)
+D(查看精度风险API\n观察模型Loss曲线)
+
+A0-->
+config.json配置-->B
+B-->C
+C-->D
+D-->config.json配置
+```
+工具的推荐使用思路是：
+
+1. 配置 config.json，选择无标杆比对任务，进行精度风险 API 的排查。
+
+2. 根据精度风险 API 输出件，修改 config.json 开启验证功能，观察模型loss曲线是否改善。
+
+### 3.1 安装msprobe工具
+参照 [msprobe安装](./01.installation.md)
+### 3.2 config.json配置
+修改 [config.json](../config.json) 的 task 类型为"**free_benchmark**"开启无标杆功能。支持的配置项详见[配置文件介绍](./02.config_introduction.md)，默认配置如下：
+```json
+{
+    "task": "free_benchmark",
+    "dump_path": "./dump_path", 
+    "rank": [],  
+    "step": [],  
+    "level": "L1", 
+
+    "free_benchmark": {
+        "list": [],
+        "fuzz_device": "npu",
+        "pert_mode": "improve_precision",
+        "handler_type": "check",
+        "fuzz_level": "L1",
+        "fuzz_stage": "forward"
+    }
+}
+```
+用户需根据自己的使用场景，对照[工具实现原理](#2-工具实现原理)中几个关键步骤进行配置
+####  3.2.1 确定比对范围
+
+| 相关参数名 | 是否必选 | 可配置项          | 适用场景                                                                                    |
+| ---------- | -------- | ----------------- | ------------------------------------------------------------------------------------------- |
+| list       | 可选     |                   | 需要通过指定 API 名来限制比对API个数 如：\["mindspore.ops.bmm"\] 会只对mindspore.ops.bmm API进行比对|
+| fuzz_stage | 可选     | "forward"（默认） | 需要进行 API **前向**计算的精度问题排查或验证|
+
+####  3.2.2. 选择扰动因子
+
+| 相关参数    | 是否必选 | 可配置项                     | 适用场景                                                                                                 |
+| ----------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| pert_mode   | 可选     | "improve_precision" （默认） | （常用）(可做验证) API 可能在**低精度**下有精度问题，扰动因子会将输入的低精度向量升精度 |
+|             |          | "add_noise"                  | API 可能在**轻微扰动**下暴露精度问题，扰动因子会为输入向量增加一个极小值 |
+|             |          | "bit_noise"                  | API 可能在**轻微扰动**下暴露精度问题，扰动因子会翻转输入向量的最后一个比特位。不支持BF16类型向量 |
+|             |          | "no_change"                  | API 可能存在**数值稳定性**精度问题，扰动因子会复制原始输入|
+|             |          | "change_value"               | API 可能存在**大数吃小数**问题，扰动因子会交换输入向量的首尾值 |
+
+####  3.2.3. 选择处理方式
+| 相关参数名   | 是否必选 | 可配置项          | 适用场景                                                                                  |
+| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| handler_type | 可选     | "check"  （默认） | 要做精度问题 API 排查，输出扰动前后不符合精度标准的 API，支持所有扰动因子                  |
+|              |          | "fix"             | 要做可疑 API 验证，用扰动后输出替换原始输出，仅支持 "improve_precision" 扰动因子 |
+
+### 3.3 在模型脚本中开启工具
+
+通过 PrecisionDebugger 统一接口开启工具，示例如下：
+
+```python
+from msprobe.mindspore import PrecisionDebugger  
+
+debugger = PrecisionDebugger(config_path='./config.json')
+...
+debugger.start() # 一般在训练循环开头启动工具
+... # 循环体
+debugger.stop() # 一般在训练循环末尾结束工具
+debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要
+```
+
+### 3.4 查看精度风险算子
+
+check 模式下，若存在不符合精度标准的 API，则工具会在 dump_path 目录下将相应 API 信息输出在文件 free_benchmark.csv 中。csv 文件字段含义如下所示：
+
+| 字段         | 说明                                                                                     |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| rank         | Rank ID，int 类型                                                                      |
+| pert_mode    | 扰动因子的类型，string 类型                                                            |
+| stage        | 前/反向，string 类型                                                                |
+| step         | 迭代数，int 类型                                                                       |
+| api_name     | API 名称，string 类型                                                                  |
+| max_rel      | 输出对比最大相对误差，float 类型                                                       |
+| dtype        | 输入的 dtype，string 类型                                                              |
+| shape        | 输入的 shape，tuple 类型                                                               |
+| output_index | 如果输出为列表或元组，其中一个元素检测不一致，则会有该元素的 index，否则为空，int 类型 |
+
+无标杆比对使用的精度标准如下：
+
+| 输出dtype         | 相对误差阈值 |
+| ----------------- | ------------ |
+| mindspore.float16 | 0.002        |
+| mindspore.float32 | 0.0002       |
+| 其他              | 0.0002       |