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

msprobe/docs/06.data_dump_MindSpore.md

@@ -1,37 +1,82 @@
-# MindSpore 场景的精度数据采集
 
-msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。目前，静态图场景仅支持 kernel 级数据采集，对应 config.json 配置中的 "L2" level；动态图场景支持cell、API、kernel级数据采集，对应 config.json 配置中的 "L0"、"L1" 、"L2"、"mix" level。
+# msprobe 工具 MindSpore场景精度数据采集指南
 
-需要注意，**动态图 kernel 级**（"L2" level）精度数据采集对象为被 PSJit 或 PIJit 装饰的 Cell 或 function 内的算子，其被装饰部分实际以**静态图**模式执行，所以此场景下的工具使用方式与静态图场景完全相同。下文无特殊说明时，介绍的动态图场景不包括 kernel 级（"L2" level）dump 情形。
 
-精度数据采集功能的配置示例见[MindSpore 静态图场景下 task 配置为 statistics](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#21-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-statistics)、[MindSpore 静态图场景下 task 配置为 tensor](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#22-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-tensor)、[MindSpore 动态图场景下 task 配置为 statistics](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#31-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-statistics)、[MindSpore 动态图场景下 task 配置为 tensor](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#32-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-tensor)。
+## 1. 专业名词解释
 
-动态图 API 级 dump 时，本工具提供固定的 API 支持列表，仅支持对列表中的 API 进行精度数据采集。一般情况下，无需修改该列表，而是通过config.json中的scope/list字段进行 dump API 指定。若需要改变 API 支持列表，可以在 `msprobe/mindspore/dump/hook_cell/support_wrap_ops.yaml` 文件内手动修改，如下示例：
+* **静态图**：在编译时就确定网络结构，静态图模式拥有较高的训练性能，但难以调试。
+* **动态图**：运行时动态构建网络，相较于静态图模式虽然易于调试，但难以高效执行。
+* **高阶 API**：如 `mindspore.train.Model`，封装了训练过程的高级接口。
+* **JIT（Just-In-Time 编译）**：MindSpore提供JIT（just-in-time）技术进一步进行性能优化。JIT模式会通过AST树解析的方式或者Python字节码解析的方式，将代码解析为一张中间表示图（IR，intermediate representation）。IR图作为该代码的唯一表示，编译器通过对该IR图的优化，来达到对代码的优化，提高运行性能。与动态图模式相对应，这种JIT的编译模式被称为静态图模式。
+* **Primitive op**：MindSpore 中的基本算子，通常由 `mindspore.ops.Primitive` 定义，提供底层的算子操作接口。
 
-```yaml
-ops:  # ops为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API
-  - adaptive_avg_pool1d
-  - adaptive_avg_pool2d
-  - adaptive_avg_pool3d
-```
 
-## 1 接口介绍
+## 2. 工具安装
+
+请参见[《msprobe 工具安装指南》](./01.installation.md)。
+
+
+## 3. 快速入门
+
+以下通过一个简单的示例，展示如何在 MindSpore 中使用 msprobe 工具进行精度数据采集。
+
+您可以参考 [动态图快速入门示例](data_dump_MindSpore/dynamic_graph_quick_start_example.md)  了解详细步骤。
+
+## 4. 概述
+
+msprobe 工具通过在训练脚本中添加 `PrecisionDebugger` 接口并启动训练的方式，采集模型在运行过程中的精度数据。该工具支持对MindSpore的静态图和动态图场景进行不同Level等级的精度数据采集。
+
+dump 的"tensor"模式采集数据量大小，可以参考[数据量基线](data_dump_MindSpore/data_dump_MindSpore_baseline.md)。
+
+## 5. 场景介绍 
+
+### 5.1 静态图场景 
+在静态图场景下，msprobe 仅支持 **L2 Level**  的数据采集。 
+- **L2 Level（Kernel 级）** ：采集底层算子的输入输出数据，适用于深入分析算子级别的精度问题。
+
+采集方式请参见[示例代码 > 静态图场景](#71-静态图场景)。详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”和[《config.json 配置示例》](./03.config_examples.md#2-mindspore-静态图场景) 中的“MindSpore 静态图场景”。
+
+### 5.2 动态图场景 
+在动态图场景下，msprobe 支持 **L0** 、**L1** 、**mix** 、**L2 Level**  的数据采集，具体分为以下几种情况： 
+- **使用高阶 API（如 `Model 高阶API`）** ： 
+  - 需要使用 `MsprobeStep` 回调类来控制数据采集的启停，适用于 **L0** 、**L1** 、**mix** 、**L2** 数据采集。
+ 
+- **未使用高阶 API** ： 
+  - 手动在训练循环中调用 `start`、`stop`、`step` 等接口，适用于 **L0** 、**L1** 、**mix** 、**L2** 数据采集。
+
+采集方式请参见[示例代码 > 动态图场景](#72-动态图场景)。
+
+> **注意** ：动态图模式下，使用 `PSJit` 或 `PIJit` 装饰的部分实际以静态图模式执行，此时的 **Kernel 级（L2 Level）**  数据采集方式与静态图场景相同。 
+- **L0 Level（Cell 级）** ：采集 `Cell` 对象的数据，适用于需要分析特定网络模块的情况。
+ 
+- **L1 Level（API 级）** ：采集 MindSpore API 的输入输出数据，适用于定位 API 层面的精度问题。
+
+- **mix（模块级 + API 级）** ：在 `L0` 和 `L1` 级别的基础上同时采集模块级和 API 级数据，适用于需要分析模块和 API 层面精度问题的场景。
+
+
+详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”和[《config.json 配置示例》](./03.config_examples.md#3-mindspore-动态图场景) 中的“MindSpore 动态图场景”。
+
 
-### 1.1 msprobe.mindspore.PrecisionDebugger
+## 6 接口介绍
+
+### 6.1 msprobe.mindspore.PrecisionDebugger
 
 **功能说明**：通过加载 dump 配置文件的方式来确定 dump 操作的详细配置。
 
 **原型**：
 
 ```Python
-PrecisionDebugger(config_path=None)
+PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, step=None)
 ```
 
 **参数说明**:
 
 1. config_path：指定 dump 配置文件路径，string 类型。参数示例："./config.json"。未配置该路径时，默认使用 [config.json](../config.json) 文件的默认配置，配置选项含义可见 [config.json 介绍](./02.config_introduction.md)。
+2. 其他参数均在 [config.json](../config.json) 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。
+
+此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。
 
-#### 1.1.1 start
+#### 6.1.1 start
 
 **功能说明**：启动精度数据采集。需在模型执行模式（静态图/动态图、O0/O1/O2编译等级）设置后调用。静态图场景下，必须在模型初始化及 mindspore.communication.init 调用前添加；动态图场景下，如果没有使用 [Model](https://gitee.com/link?target=https%3A%2F%2Fwww.mindspore.cn%2Ftutorials%2Fzh-CN%2Fr2.3.1%2Fadvanced%2Fmodel.html) 高阶 API 进行训练，则需要与 stop 函数一起添加在 for 循环内，否则只有需要传入model参数时，才使用该接口。
 
@@ -43,11 +88,13 @@ start(model=None)
 
 **参数说明**:
 
-1. model：指具体的 mindspore.nn.Cell，默认不配置。Cell级别（"L0" level）dump 时，传入 model 可以采集 model 内的所有Cell 对象数据。API级别（"L1" level）dump 时，传入 model 可以采集 model 内包含 primitive op 对象在内的所有 API 数据，若不传入 model 参数，则只采集非 primitive op 的 API 数据。
+1. model：指具体的 mindspore.nn.Cell对象，默认不配置。Cell级别（"L0" level）dump 与 "mix" level dump 时，必须传入 model 才可以采集 model 内的所有Cell 对象数据。API级别（"L1" level）dump 时，传入 model 可以采集 model 内包含 primitive op 对象在内的所有 API 数据，若不传入 model 参数，则只采集非 primitive op 的 API 数据。
 
-#### 1.1.2 stop
+#### 6.1.2 stop
 
-**功能说明**：停止数据采集。在 **start** 函数之后的任意位置添加。需要与 start 函数一起添加在 for 循环内。若需要 dump 反向数据，则需要添加在反向计算代码之后。**仅未使用 Model 高阶 API 的动态图场景支持。**
+**功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。若 **stop** 函数添加在反向计算代码之后，则会采集 **start** 和该函数之间的前反向数据。
+若 **stop** 函数添加在反向计算代码之前，则需要将 **step** 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
+**step** 函数详细介绍见6.1.3章节。**仅未使用 Model 高阶 API 的动态图场景支持。**
 
 **原型**：
 
@@ -55,9 +102,11 @@ start(model=None)
 stop()
 ```
 
-#### 1.1.3 step
+#### 6.1.3 step
 
-**功能说明**：在最后一个 **stop** 函数后或一个 step 训练结束的位置添加。**仅未使用 Model 高阶 API 的动态图场景支持。**
+**功能说明**：结束一个 step 的数据采集，完成所有数据落盘并更新 dump 参数。在一个 step 结束的位置添加，且必须在 **stop** 函数之后的位置调用。
+该函数需要配合 **start** 和 **stop** 函数使用，尽量添加在反向计算代码之后，否则可能会导致反向数据丢失。
+**仅未使用 Model 高阶 API 的动态图场景支持。**
 
 **原型**：
 
@@ -65,13 +114,11 @@ stop()
 step()
 ```
 
-#### 1.1.4 forward_backward_dump_end
+#### 6.1.4 forward_backward_dump_end
 
-**功能说明**：在 **start** 函数和在 **stop** 函数之间调用，表示采集 **start** 到 **forward_backward_dump_end**之间的L1级别的正反向数据。
+**功能说明**：停止精度数据采集。与 **stop** 函数功能相同，该函数在将来会被移除，建议使用 **stop** 函数。
 
-**仅支持L1级别数据采集场景。**
-
-**L1级别数据中的jit数据采集行为不受此接口影响**
+**L1级别数据中的jit数据采集行为不受此接口影响。**
 
 **仅未使用 Model 高阶 API 的动态图场景支持。**
 
@@ -81,9 +128,9 @@ step()
 forward_backward_dump_end()
 ```
 
-### 1.2 msprobe.mindspore.common.utils.MsprobeStep
+### 6.2 msprobe.mindspore.common.utils.MsprobeStep
 
-**功能说明**：MindSpore Callback类，自动在每个step开始时调用start()接口，在每个step结束时调用stop()、step()接口。实现使用 Model 高阶 API 的动态图场景下 L0、L1 级别的精度数据采集控制，控制粒度为单个 **Step** ，而 PrecisionDebugger.start, PrecisionDebugger.stop 接口的控制粒度任意训练代码段。
+**功能说明**：MindSpore Callback类，自动在每个step开始时调用start()接口，在每个step结束时调用stop()、step()接口。实现使用 Model 高阶 API 的动态图场景下 L0、L1、mix 级别的精度数据采集控制，控制粒度为单个 **Step** ，而 PrecisionDebugger.start, PrecisionDebugger.stop 接口的控制粒度任意训练代码段。
 
 **原型**：
 
@@ -95,13 +142,13 @@ MsprobeStep(debugger)
 
 1. debugger：PrecisionDebugger对象。
 
-### 1.3 msprobe.mindspore.seed_all
+### 6.3 msprobe.mindspore.seed_all
 
 **功能说明**：用于固定网络中的随机性和开启确定性计算。
 
 **原型**：
 ```python
-seed_all(seed=1234, mode=False)
+seed_all(seed=1234, mode=False, rm_dropout=True)
 ```
 
 **参数说明**:
@@ -110,26 +157,36 @@ seed_all(seed=1234, mode=False)
 
 2. mode：确定性计算使能，可配置 True 或 False，默认值：False，非必选。参数示例：mode=True。该参数设置为 True 后，将会开启算子确定性运行模式与归约类通信算子（AllReduce、ReduceScatter、Reduce）的确定性计算。注意：确定性计算会导致API执行性能降低，建议在发现模型多次执行结果不同的情况下开启。
 
-## 2 示例代码
+3. rm_dropout：控制dropout失效的开关。可配置 True 或 False，默认值：True，非必选。参数示例：rm_dropout=True。该参数设置为 True 后，将会使mindspore.ops.Dropout，mindspore.ops.Dropout2D，mindspore.ops.Dropout3D，mindspore.mint.nn.Dropout和mindspore.mint.nn.functional.dropout失效，以避免因随机dropout造成的网络随机性。建议在采集mindspore数据前开启。注意：通过rm_dropout控制dropout失效或生效需要在初始化Dropout实例前调用才能生效。
 
-### 2.1 MindSpore 静态图场景
 
-```Python
+
+
+## 7. 示例代码
+
+### 7.1 静态图场景
+
+```python
 import mindspore as ms
 ms.set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
 
 from msprobe.mindspore import PrecisionDebugger
 debugger = PrecisionDebugger(config_path="./config.json")
 debugger.start()
-# 请勿将以上初始化流程置于模型实例化或mindspore.communication.init调用后
+# 请勿将以上初始化流程置于模型实例化或 mindspore.communication.init 调用后
+# 模型定义和训练代码
 # ...
+
 ```
 
-### 2.2 MindSpore 动态图场景
+### 7.2 动态图场景
 
-#### 2.2.1 未使用 Model 高阶 API(非 L2 级别)
+#### 7.2.1 L0 ,L1, mix 级别
 
-```Python
+##### 7.2.1.1 未使用 Model 高阶 API 
+
+
+```python
 import mindspore as ms
 ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
 
@@ -141,60 +198,66 @@ debugger = PrecisionDebugger(config_path="./config.json")
 model = Network()
 # 数据集迭代的地方往往是模型开始训练的地方
 for data, label in data_loader:
-    debugger.start()        # 进行L1级别下非primitive op采集时调用
-    # debugger.start(model) # 进行L0级别或L1级别下primitive op的数据采集时调用
-    # 如下是模型每个step执行的逻辑
+    debugger.start()        # 进行 L1 级别下非 primitive op 采集时调用
+    # debugger.start(model) # 进行 L0, mix 级别或 L1 级别下 primitive op 的数据采集时调用
+    # 如下是模型每个 step 执行的逻辑
     grad_net = ms.grad(model)(data)
     # ...
-    debugger.stop()         # 关闭数据dump
-    debugger.step()         # 结束一个step的dump
+    debugger.stop()         # 关闭数据 dump
+    debugger.step()         # 更新迭代数
 ```
 
-#### 2.2.2 未使用 Model 高阶 API(L2 级别)
+##### 7.2.1.2 使用 Model 高阶 API 
 
-```Python
+
+```python
 import mindspore as ms
+from mindspore.train import Model
 ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
 
 from msprobe.mindspore import PrecisionDebugger
+from msprobe.mindspore.common.utils import MsprobeStep
 debugger = PrecisionDebugger(config_path="./config.json")
-debugger.start()
-# 请勿将以上初始化流程置于模型实例化或mindspore.communication.init调用后
 
 # 模型、损失函数的定义以及初始化等操作
 # ...
+
 model = Network()
-# 数据集迭代的地方往往是模型开始训练的地方
-for data, label in data_loader:
-    # 如下是模型每个step执行的逻辑
-    grad_net = ms.grad(model)(data)
-    # ...
+# 只有进行 L0 级别下 Cell 对象，mix 级别，L1 级别下 primitive op 的数据采集时才需要调用
+# debugger.start(model)
+trainer = Model(model, loss_fn=loss_fn, optimizer=optimizer, metrics={'accuracy'})
+trainer.train(1, train_dataset, callbacks=[MsprobeStep(debugger)])
 ```
 
-#### 2.2.3 使用 Model 高阶 API(非 L2 级别)
+#### 7.2.2 L2 级别
 
-```Python
+##### 7.2.2.1 未使用 Model 高阶 API 
+
+
+```python
 import mindspore as ms
-from mindspore.train import Model
 ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
 
 from msprobe.mindspore import PrecisionDebugger
-from msprobe.mindspore.common.utils import MsprobeStep
 debugger = PrecisionDebugger(config_path="./config.json")
+debugger.start()
+# 请勿将以上初始化流程置于模型实例化或 mindspore.communication.init 调用后
 
 # 模型、损失函数的定义以及初始化等操作
 # ...
-
 model = Network()
-# 只有进行L0级别下Cell对象或L1级别下primitive op的数据采集时才需要调用
-# debugger.start(model)
-trainer = Model(model, loss_fn=loss_fn, optimizer=optimizer, metrics={'accuracy'})
-trainer.train(1, train_dataset, callbacks=[MsprobeStep(debugger)])
+# 数据集迭代的地方往往是模型开始训练的地方
+for data, label in data_loader:
+    # 如下是模型每个 step 执行的逻辑
+    grad_net = ms.grad(model)(data)
+    # ...
 ```
 
-#### 2.2.4 使用 Model 高阶 API(L2 级别)
 
-```Python
+##### 7.2.2.2 使用 Model 高阶 API 
+
+
+```python
 import mindspore as ms
 from mindspore.train import Model
 ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
@@ -202,7 +265,7 @@ ms.set_context(mode=ms.PYNATIVE_MODE, device_target="Ascend")
 from msprobe.mindspore import PrecisionDebugger
 debugger = PrecisionDebugger(config_path="./config.json")
 debugger.start()
-# 请勿将以上初始化流程置于模型实例化或mindspore.communication.init调用后
+# 请勿将以上初始化流程置于模型实例化或 mindspore.communication.init 调用后
 
 # 模型、损失函数的定义以及初始化等操作
 # ...
@@ -212,43 +275,64 @@ trainer = Model(model, loss_fn=loss_fn, optimizer=optimizer, metrics={'accuracy'
 trainer.train(1, train_dataset)
 ```
 
-## 3 dump 结果文件介绍
+## 8. dump 结果文件介绍
 
-### 3.1 MindSpore 静态图场景
+### 8.1 静态图场景
 
-训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。
+训练结束后，数据将保存在 `dump_path` 指定的目录下。
 
-- jit_level 为O0/O1时：
-
-  dump 结果目录请参见 MindSpore 官网中的[同步 Dump 数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.1/debug/dump.html#%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95%E5%92%8C%E6%95%B0%E6%8D%AE%E6%96%87%E4%BB%B6%E4%BB%8B%E7%BB%8D)。
-
-- jit_level 为O2时：
-
-  dump 结果目录请参见 MindSpore 官网中的[异步 Dump 数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.1/debug/dump.html#%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95%E5%92%8C%E6%95%B0%E6%8D%AE%E6%96%87%E4%BB%B6%E4%BB%8B%E7%BB%8D-1)。
+若jit_level=O2，且使用mindstudio-probe发布包或源码编包时添加了`--include-mod=adump`选项，目录结构示例如下：
+```
+├── dump_path
+│   ├── rank_0
+│   |   ├── {timestamp}
+│   |   │   ├── step_0
+|   |   |   |    ├── AssignAdd.Default_network-TrainOneStepCell_optimzer-Gsd_AssignAdd-op0.0.10.1735011096403740.input.0.ND.INT32.npy
+|   |   |   |    ├── Cast.Default_network-TrainOneStepCell_network-WithLossCell__backbone-Net_Cast-op0.9.10.1735011096426349.input.0.ND.FLOAT.npy
+|   |   |   |    ├── GetNext.Default_GetNext-op0.0.11.17350110964032987.output.0.ND.FLOAT.npy
+|   |   |   |    ...
+|   |   |   |    ├── RefDAata.accum_bias1.6.10.1735011096424907.output.0.ND.FLOAT.npy
+|   |   |   |    ├── Sub.Default_network-TrainOneStepCell_network-WithLossCell__backbone-Net_Sub-op0.10.10.1735011096427368.input.0.ND.BF16
+|   |   |   |    └── mapping.csv
+│   |   │   ├── step_1
+|   |   |   |    ├── ...
+|   |   |   ├── ...
+|   |   ├── ...
+|   |
+│   ├── ...
+|   |
+│   └── rank_7
+│       ├── ...
+```
+**说明**
+1. 若配置文件中指定落盘npy格式，但是实际数据格式不在npy支持范围内(如bf16、int4等)，则该tensor会以原始码流落盘，并不会转换为npy格式。
+2. 若原始文件全名长度超过255个字符，则文件基础名会被转换为长度为32位的随机数字字符串，原始文件名与转换后文件名的对应关系会保存在同目录下的`mapping.csv`文件中。
 
-jit_level 请参见 [mindspore.set_context](https://www.mindspore.cn/docs/zh-CN/r2.3.1/api_python/mindspore/mindspore.set_context.html) 中的 jit_config 参数。
 
-### 3.2 MindSpore 动态图场景
+其他场景请参见 MindSpore 官方文档中的[数据对象目录](https://www.mindspore.cn/docs/zh-CN/r2.4.0/model_train/debug/dump.html)。
 
-训练结束后，工具将 dump 的数据保存在dump_path参数指定的目录下。
+### 8.2 动态图场景
 
-dump结果目录结构示例如下：
+dump 结果目录结构示例如下：
 
-```bash
+```lua
 ├── dump_path
 │   ├── step0
 │   |   ├── rank0
 │   |   │   ├── dump_tensor_data
 |   |   |   |    ├── MintFunctional.relu.0.backward.input.0.npy
 |   |   |   |    ├── Mint.abs.0.forward.input.0.npy
-|   |   |   |    ├── Functional.split.0.forward.input.0.npy
+|   |   |   |    ├── Functional.split.0.forward.input.0.npy       # 命名格式为{api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号}, 其中，“参数序号”表示该API的第n个输入或输出，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个元素。   
 |   |   |   |    ├── Tensor.__add__.0.forward.output.0.npy
 |   |   |   |    ...
 |   |   |   |    ├── Jit.AlexNet.0.forward.input.0.npy
-|   |   |   |    └── Cell.relu.ReLU.forward.0.input.0.npy        # config.json文件配置level为L0时dump的cell模块级数据，命名格式为{Cell}_{cell_name}_{class_name}_{前向反向}.{index}.{input/output}.{参数序号}
-│   |   |   ├── dump.json        # 保存前反向算子、算子的统计量信息或溢出算子信息。包含dump数据的API名称（命名格式为：{api_type}_{api_name}_{API调用次数}_{前向反向}_{input/output}.{参数序号}）、dtype、 shape、各数据的max、min、mean、L2norm统计信息以及当配置summary_mode="md5"时的md5数据。其中，“参数序号”表示该API下的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个子参数；L2norm表示L2范数（平方根）
-│   |   |   ├── stack.json        # 算子调用栈信息
-│   |   |   └── construct.json        # 分层分级结构，level为L1时，construct.json内容为空
+|   |   |   |    ├── Primitive.conv2d.Conv2D.0.forward.input.0.npy
+|   |   |   |    ├── Cell.conv1.Conv2D.forward.0.parameters.weight.npy    # 模块参数数据：命名格式为{Cell}.{cell_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
+|   |   |   |    ├── Cell.conv1.Conv2D.parameters_grad.weight.npy   # 模块参数梯度数据：命名格式为{Cell}.{cell_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
+|   |   |   |    └── Cell.relu.ReLU.forward.0.input.0.npy        # 命名格式为{Cell}.{cell_name}.{class_name}.{forward/backward}.{调用次数}.{input/output}.{参数序号}, 其中，“参数序号”表示该Cell的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该Cell的第1个参数的第1个元素。   
+│   |   |   ├── dump.json
+│   |   |   ├── stack.json
+│   |   |   └── construct.json
 │   |   ├── rank1
 |   |   |   ├── dump_tensor_data
 |   |   |   |   └── ...
@@ -263,23 +347,44 @@ dump结果目录结构示例如下：
 │   ├── step2
 ```
 
-dump 过程中，npy 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。
+* `rank`：设备 ID，每张卡的数据保存在对应的 `rank{ID}` 目录下。非分布式场景下没有 rank ID，目录名称为 rank。
+* `dump_tensor_data`：保存采集到的张量数据。
+* `dump.json`： 保存API或Cell前反向数据的统计量信息。包含dump数据的API名称或Cell名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#2-dumpjson文件示例mindspore)。
+* `stack.json`：API/Cell的调用栈信息。
+* `construct.json`：分层分级结构，level为L1时，construct.json内容为空。  
 
-其中 rank 为设备上各卡的 ID，每张卡上 dump 的数据会生成对应 dump 目录。非分布式场景下没有 rank ID，目录名称为 rank。
+dump 过程中，npy 文件在对应API或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，因此，程序异常终止时，被执行API对应的 npy 文件已被保存，但 json 文件中的数据可能丢失。
 
 动态图场景下使能 PSJit 或 PIJit，装饰特定 Cell 或 function，被装饰的部分会全部/部分使能**静态图**流程。
 
 - PSJit 场景下 config.json 文件配置 level 为 L1 时，被 PSJit 装饰的部分也作为 API 被 dump 到对应目录；配置 level 为 L2 时，则只会 dump 用户网络中静态图流程下的相关 kernel，其结果目录同jit_level 为 O0/O1 时的静态图 dump 相同。
 - PIJit 场景下 config.json 文件配置 level 为 L1 时，会被还原为动态图，按 API 粒度进行 dump；配置 level 为 L2 时，则只会 dump 用户网络中静态图流程下的相关 kernel。
 
-npy 文件保存的前缀和 MindSpore 对应关系如下：
-
-| 前缀           | MindSpore 模块                |
-| -------------- | ---------------------------- |
-| Tensor         | mindspore.Tensor             |
-| Functional     | mindspore.ops                |
-| Primitive      | mindspore.ops.Primitive      |
-| Mint           | mindspore.mint               |
-| MintFunctional | mindspore.mint.nn.functional |
-| Jit            | mindspore.jit                |
-| Cell           | mindspore.nn.Cell            |
+
+npy文件名的前缀含义如下：
+
+| 前缀           | 含义                           |
+| -------------- |------------------------------|
+| Tensor         | mindspore.Tensor API数据             |
+| Functional     | mindspore.ops API数据                |
+| Primitive      | mindspore.ops.Primitive API数据      |
+| Mint           | mindspore.mint API数据              |
+| MintFunctional | mindspore.mint.nn.functional API数据 |
+| Distributed    | mindspore.communication.comm_func API数据     |
+| Jit            | 被"jit"装饰的模块或函数数据                |
+| Cell           | mindspore.nn.Cell 类（模块）数据           |
+
+
+
+## 9.补充说明
+
+### 9.1 修改 API 支持列表
+
+动态图 API 级 dump 时，本工具提供固定的 API 支持列表，仅支持对列表中的 API 进行精度数据采集。一般情况下，无需修改该列表，而是通过config.json中的scope/list字段进行 dump API 指定。若需要改变 API 支持列表，可以在 `msprobe/mindspore/dump/hook_cell/support_wrap_ops.yaml` 文件内手动修改，如下示例：
+
+```yaml
+ops:
+  - adaptive_avg_pool1d
+  - adaptive_avg_pool2d
+  - adaptive_avg_pool3d
+```

msprobe/docs/07.accuracy_checker_PyTorch.md

@@ -31,7 +31,7 @@ run_ut 预检操作包括以下两种方式：
 将 API 信息输入到 run_ut 模块进行精度检测并比对，运行如下命令： 
 
 ```bash
-msprobe -f pytorch run_ut -api_info ./dump.json
+msprobe -f pytorch run_ut -api_info ./dump_path/step{step_number}/rank{rank_number}/dump.json
 ```
 
    | 参数名称                     | 解释                                                         | 是否必选                           |
@@ -50,7 +50,7 @@ run_ut 执行结果包括 `accuracy_checking_result_{timestamp}.csv` 和 `accura
 如果需要保存比对不达标的输入和输出数据，可以在 run_ut 执行命令结尾添加 `-save_error_data`，例如：
 
 ```bash
-msprobe -f pytorch run_ut -api_info ./dump.json -save_error_data
+msprobe -f pytorch run_ut -api_info ./dump_path/step{step_number}/rank{rank_number}/dump.json -save_error_data
 ```
 
 数据默认会存盘到 './ut_error_data{timestamp}' 路径下，如有需要，用户可以通过 error_data_path 参数来配置保存路径，error_data_path 参数在 [config.json](../config.json) 文件或 [config.yaml](../pytorch/api_accuracy_checker/config.yaml) 文件配置，config.json 文件需要在 run_ut 操作时通过 -config 参数指定。
@@ -98,7 +98,7 @@ msprobe -f pytorch run_ut -api_info ./dump.json -save_error_data
 multi_run_ut 脚本，可以并行执行多个 run_ut 操作，从而减少预检耗时。示例如下：
 
 ```bash
-msprobe -f pytorch multi_run_ut -api_info ./dump.json -n 32 -d 0 1 2 3
+msprobe -f pytorch multi_run_ut -api_info ./dump_path/step{step_number}/rank{rank_number}/dump.json -n 32 -d 0 1 2 3
 ```
 
 | 参数名称                     | 解释                                                         | 是否必选                           |
@@ -117,7 +117,7 @@ msprobe -f pytorch multi_run_ut -api_info ./dump.json -n 32 -d 0 1 2 3
 断点续检操作通过如下命令执行：
 
 ```bash
-msprobe -f pytorch run_ut -api_info ./dump.json -csv_path /home/xxx/ut/accuracy_checking_result_{timestamp}.csv
+msprobe -f pytorch run_ut -api_info ./dump_path/step{step_number}/rank{rank_number}/dump.json -csv_path /home/xxx/ut/accuracy_checking_result_{timestamp}.csv
 ```
 
 精度预检 run_ut 过程中，若因环境、数据量过大等原因导致预检进程中断，那么当用户解决这些问题后，重新执行 run_ut 操作，可以通过断点续检操作继续前面未完成的预检，会在 -csv_path 指定的 `accuracy_checking_result_{timestamp}.csv` 文件以及对应的 `accuracy_checking_details_{timestamp}.csv` 文件中继续写入后续的结果，不会重新创建结果文件。
@@ -137,8 +137,8 @@ msprobe -f pytorch run_ut -api_info ./dump.json -csv_path /home/xxx/ut/accuracy_
 | 字段                  | 含义     |
 | --------------------- | ------------------------- |
 | API name              | API 名称。                    |
-| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。SKIP 表示跳过该 API 的计算，跳过原因在 Message 中说明。 |
-| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。如果是空白的话代表该 API 没有反向输出，SKIP 表示该 API 的某个参数的反向不计算梯度。 |
+| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。SKIP 表示跳过该 API 的计算，跳过原因在 Message 字段中提示，包括：该 API 不支持精度预检，或该 API 被黑名单过滤或不在白名单上，或运行错误等。 |
+| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。如果是空白的话代表该 API 没有反向输出。SKIP 表示跳过该 API 的计算，跳过原因在 Message 字段中提示，包括：该 API 不支持精度预检，或该 API 被黑名单过滤或不在白名单上，或运行错误等。 |
 | Message               | 提示信息。             |
 
 该结果为中间结果，仅作为参考，建议完成 [5 预检结果比对](#5-预检结果比对)后查看比对结果。该结果后续将会删除。
@@ -174,8 +174,8 @@ Forward Test Success 和 Backward Test Success 是否通过测试是由 `accurac
 | ULP 误差最大值       | NPU 或 GPU 数据与标杆数据 ULP 误差的最大值（取绝对值后）。        |
 | ULP 误差平均值       | NPU 或 GPU 数据与标杆数据 ULP 误差的平均值（取绝对值后）。  |
 | ULP 误差大于阈值占比 | NPU 或 GPU 数据与标杆数据的 ULP 误差（取绝对值后）大于阈值（当 NPU 或 GPU 数据类型为 float16 或 bfloat16 时，阈值为 1；当 NPU 或 GPU 数据类型为 float32 时，阈值为 32）的元素个数占总元素的个数比例。 |
-| Status              | API 预检通过状态，pass 表示通过测试，error 表示未通过，warning 表示测试未通过双千或双万精度指标，SKIP 表示该 API 的某个参数的反向不要计算梯度，所以没有任何计算过程，其他信息均为空。 |
-| message             | 提示信息。                     |
+| Status              | API 预检通过状态。pass 表示通过测试；error 表示未通过；warning 表示测试未通过双千或双万精度指标；SKIP 表示跳过该 API 的计算，跳过原因在 Message 字段中提示，包括：该 API 的某个参数的反向不计算梯度，没有任何计算过程，其他信息均为空，或该 API 的数据类型不支持使用新精度标准进行比对（如 float64），或该 API 不支持精度预检，或该 API 被黑名单过滤或不在白名单上，或运行错误等。 |
+| Message             | 提示信息。                     |
 
 ### 4.1 API 预检指标
 
@@ -194,15 +194,15 @@ Forward Test Success 和 Backward Test Success 是否通过测试是由 `accurac
 
    判定为小值的阈值：
 
-   - torch.float32：e-6
-   - torch.float16：e-3
-   - torch.bfloat16：e-3
+   - torch.float32：2**-20
+   - torch.float16：2**-10
+   - torch.bfloat16：2**-10
 
    小值域的绝对误差阈值：
 
-   - torch.float32：e-9
-   - torch.float16：e-5
-   - torch.bfloat16：e-5
+   - torch.float32：2**-30
+   - torch.float16：2**-16
+   - torch.bfloat16：2**-16
 
 ## 5 预检结果比对
 
@@ -214,8 +214,8 @@ msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_de
 
 | 参数名称   | 说明               | 是否必选 |
 | -------------------- | ------------- | -------- |
-| -npu 或 --npu_csv_path | NPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否       |
-| -gpu 或 --gpu_csv_path | GPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否       |
+| -npu 或 --npu_csv_path | NPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 是       |
+| -gpu 或 --gpu_csv_path | GPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 是       |
 | -o 或 --out_path       | 指定 api_precision_compare.py 执行结果存盘路径，默认为当前目录。 | 否       |
 
 执行完成后输出 `api_precision_compare_result_{timestamp}.csv` 和 `api_precision_compare_details_{timestamp}.csv` 文件。文件示例如下：
@@ -228,10 +228,10 @@ msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_de
 
 | 字段                  | 含义                                                         |
 | --------------------- | ------------------------------------------------------------ |
-| API name              | API 名称。                                                    |
-| Forward Test Success  | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
-| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，如果是空白的话代表该 API 没有反向输出，SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
-| Message               | 提示信息。                   |
+| API name              | API 名称。                                                   |
+| Forward Test Success  | 前向 API 是否通过测试。pass 为通过；error 为错误；SKIP 表示跳过该 API 的计算，跳过原因在 Message 字段中提示，包括：该 API 的数据类型不支持使用新精度标准进行比对（如 float64），或该 API 不支持精度预检，或该 API 被黑名单过滤或不在白名单上，或运行错误等。 |
+| Backward Test Success | 反向 API 是否通过测试。pass 为通过；error 为错误；如果是空白的话代表该 API 没有反向输出；SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对（如 float64）。 |
+| Message               | 提示信息。                                                   |
 
 Forward Test Success 和 Backward Test Success 是否通过测试是由 `api_precision_compare_details_{timestamp}.csv` 中的各个指标判定结果决定的。需要注意的是 `api_precision_compare_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `api_precision_compare_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error，仅存在 warning 和 pass 且不存在 error 标记 warning。
 
@@ -243,15 +243,15 @@ Forward Test Success 和 Backward Test Success 是否通过测试是由 `api_pre
 | ------------------------ | ------------------------------------------------------------ |
 | API name                 | NPU 或 GPU 下的 API 名称。        |
 | 小值域错误比值           | NPU 与 CPU 的小值域的错误比率 / GPU 与 CPU 的小值域的错误比率。标杆比对法指标。 |
-| 小值域错误判定结果       | 小值域错误比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。 |
+| 小值域错误判定结果       | 小值域错误比值小于等于 2 标记为 pass，大于 2 标记为 error。 |
 | 均方根误差比值           | NPU 与 CPU 的均方根误差 / GPU 与 CPU 的均方根误差。标杆比对法指标。  |
-| 均方根误差判定结果       | 均方根误差比值小于等于 1 标记为 pass，1~2 之间标记为 warning，大于 2 标记为 error。 |
+| 均方根误差判定结果       | 均方根误差比值小于等于 2 标记为 pass，大于 2 标记为 error。 |
 | 相对误差最大值比值       | NPU 与 CPU 的相对误差最大值 / GPU 与 CPU 的相对误差最大值。标杆比对法指标。 |
-| 相对误差最大值判定结果   | 相对误差最大值比值小于等于 1 标记为 pass，1 ~ 10 之间标记为 warning，大于 10 标记为 error。 |
+| 相对误差最大值判定结果   | 相对误差最大值比值小于等于 10 标记为 pass，大于 10 标记为 error。 |
 | 相对误差平均值比值       | NPU 与 CPU 的相对误差的平均值 / GPU 与 CPU 的相对误差的平均值。标杆比对法指标。 |
-| 相对误差平均值判定结果   | 相对误差平均值比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。 |
+| 相对误差平均值判定结果   | 相对误差平均值比值小于等于 2 标记为 pass，大于 2 标记为 error。 |
 | 误差均衡性比值           | NPU 与 CPU 的误差均衡性 / GPU 与 CPU 的误差均衡性。标杆比对法指标。  |
-| 误差均衡性判定结果       | 误差均衡性比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 warning，大于 2 标记为 error。该字段暂不参与 api_precision_compare_result 的结果判定。 |
+| 误差均衡性判定结果       | 误差均衡性比值小于等于 2 标记为 pass，大于 2 标记为 error。该字段暂不参与 api_precision_compare_result 的结果判定。 |
 | inf / nan 错误率            | NPU 与标杆 inf / nan 计算不一致的元素个数占总元素的个数比例。绝对阈值法指标。 |
 | inf / nan 判定结果          | inf / nan 错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 |
 | 相对误差错误率           | NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。绝对阈值法指标。 |
@@ -266,9 +266,9 @@ Forward Test Success 和 Backward Test Success 是否通过测试是由 `api_pre
 | ULP 误差判定结果          | ULP 误差判定结果。<br/>     当 NPU 或 GPU 数据类型是 float16 或 bfloat16 时，以下两条标准满足其一标记为 pass，否则标记为 error：<br>          NPU ULP 误差大于阈值占比小于 0.001；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。<br/>     当 NPU 或 GPU 数据类型是 float32 时，以下三条标准满足其一标记为 pass，否则标记为 error：<br/>          NPU ULP 误差平均值小于 64；<br/>          NPU ULP 误差大于阈值占比小于 0.05；<br/>          NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。 |
 | 双千指标                 | 双千精度指标。是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。仅 conv1d 和 conv2d 使用该指标。双千指标法指标。 |
 | 双千指标判定结果         | 双千指标判定结果。双千指标大于 0.999 标记为 pass，否则标记为 error。 |
-| 比对结果                 | 综合所有指标的最终结果。如果比对指标中有 error，则标记为 error；有 warning，则标记为 warning；否则标记为 pass；SKIP 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 |
+| 比对结果                 | 综合所有指标的最终结果。如果比对指标中有 error，则标记为 error，在 Message 字段中提示该 API 比对结果不符合标准的指标；有 warning，则标记为 warning，在 Message 字段中提示该 API 比对结果不符合标准的指标；否则标记为 pass；SKIP 表示跳过该 API 的计算，跳过原因在 Message 字段中提示，包括：该 API 的某个参数的反向不计算梯度，没有任何计算过程，其他信息均为空，或该 API 的数据类型不支持使用新精度标准进行比对（如 float64），或该 API 不支持精度预检，或该 API 被黑名单过滤或不在白名单上，或运行错误等。 |
 | 比对算法                 | API 使用的比对算法，为标杆比对法、二进制一致法、绝对阈值法和 ULP 误差比对法中的一种。 |
-| Message                  | 提示信息。当前提示该 API 比对结果为 error 或 warning 时对应不符合标准的指标。 |
+| Message                  | 提示信息。 |
 
 a：误差比对法指标。
 
@@ -286,7 +286,7 @@ a：误差比对法指标。
 
 - npu_linear
 
-- npu_fusion_attention（该算子在 GPU 上预检时，需要额外安装 flash_attn，请用户自行安装。）
+- npu_fusion_attention（该算子在 GPU 上预检时，需要额外安装 flash_attn，请用户自行安装,建议安装2.1以上版本。）
 
 - npu_rms_norm