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

msprobe/docs/01.installation.md

@@ -16,6 +16,7 @@ pip install mindstudio-probe
 
 |版本|发布日期|支持 PyTorch 版本|支持 MindSpore 版本|下载链接|校验码|
 |:--:|:--:|:--:|:--:|:--:|:--:|
+|1.2.1|2025.2.07|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.2.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.2/mindstudio_probe-1.2.1-py3-none-any.whl)|b64b342118558e0339b39237f88a49b93fd24551b0cb202c872fbfef4260c86b|
 |1.2.0|2025.1.13|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.2.0-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.2/mindstudio_probe-1.2.0-py3-none-any.whl)|1e3aeea1706112f6ee52fd1165037936bb209138f0b9ec42ea21e2c1c8942cdc|
 |1.1.1|2024.12.09|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.1.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.1/mindstudio_probe-1.1.1-py3-none-any.whl)|577b597555dc155b76ba1a62d575c3546004644e140a456c3ba0824d46283735|
 |1.1.0|2024.10.14|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.1.0-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.1/mindstudio_probe-1.1.0-py3-none-any.whl)|83a5a9b7c65a357639f8c9636d88c693b4cf0eb590d4f8f5cb56395ba69b1f6d|
@@ -54,6 +55,30 @@ pip install ./mindstudio_probe*.whl
 
 # 特性变更说明
 
+## 1.2.0
+
+【数据采集】
+
+- 模块级dump支持采集权重及权重梯度
+- 修复原地覆盖类API前向输入数据采集不正确的问题
+- seed_all接口支持控制dropout失效功能
+
+【精度预检】
+
+- MindSpore场景新增支持Tensor类的mint API的预检
+
+【训练状态监控】
+
+- 支持FSDP和ZeRO-0
+- 异常排序支持前向激活值和反向梯度
+
+【分级可视化构图比对】
+
+- 支持graph结构分页展示，支持graph批量构建和比对
+- 支持溢出检测模式
+
+## 1.1.1
+
 ## 1.1.1
 
 【数据采集】

msprobe/docs/02.config_introduction.md

@@ -10,14 +10,15 @@
 
 ### 1.1 通用配置
 
-| 参数    | 解释                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 是否必选 |
-| ----------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
-| task              | dump 的任务类型，str 类型。可选参数：<br/>  "statistics"：仅采集统计信息，默认值；<br/> "tensor"：采集统计信息和完全复刻整网的真实数据；<br/> "run_ut"：精度预检，仅 PyTorch 场景支持，采集数据时勿选；<br/> "overflow_check"：溢出检测；<br/>  "free_benchmark"：无标杆比对；<br/>  "grad_probe"：梯度监控。<br/>    根据 task 参数取值的不同，可以配置不同场景参数，详见：<br/>[1.2 task 配置为 statistics](#12-task-配置为-statistics)，<br/>[1.3 task 配置为 tensor](#13-task-配置为-tensor)，<br/>[1.4 task 配置为 run_ut](#14-task-配置为-run_ut)，<br/>[1.5 task 配置为 overflow_check](#15-task-配置为-overflow_check)，<br/>[1.6 task 配置为 free_benchmark](#16-task-配置为-free_benchmark)，<br/>[1.7 task 配置为 grad_probe](#17-task-配置为-grad_probe)。 <br/>  **配置示例**："task": "tensor"。 | 否       |
-| dump_path         | 设置 dump 数据目录路径，str 类型。<br/>  **配置示例**："dump_path": "./dump_path"。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | 是       |
-| rank              | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型，默认未配置（表示采集所有卡的数据），应配置元素为 ≥0 的整数或类似"4-6"的字符串，且须配置实际可用的 Rank ID。<br/>  PyTorch 场景: Rank ID 从 0 开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的 Rank ID，则 dump 数据为空，比如当前环境 Rank ID 为 0 到 7，实际训练运行 0 到 3 卡，此时若配置 Rank ID 为 4 或不存在的 10 等其他值，dump 数据为空。<br/>  MindSpore 场景：所有节点的 Rank ID 均从 0 开始计数，最大取值为每个节点可用卡总数-1，config.json 配置一次 rank 参数对所有节点同时生效。<br/> 注意，单卡训练时，rank必须为[]，即空列表，不能指定rank。<br/>**配置示例**："rank": [1, "4-6"]。                                                                                                       | 否       |
-| step              | 指定采集某个 step 的数据，list[Union[int, str]] 类型。默认未配置，表示采集所有 step 数据。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。                                                                                                                                                                                                                                                                                                                                                                                                            | 否       |
-| level             | dump 级别，str 类型，根据不同级别采集不同数据。可选参数：<br/>"L0"：dump 模块级精度数据，仅 PyTorch 与 MindSpore 动态图场景支持，使用背景详见 [1.1.1 模块级精度数据 dump 说明](#111-模块级精度数据-dump-说明)；<br/>"L1"：dump API 级精度数据，默认值，仅 PyTorch 与 MindSpore 动态图场景支持；<br/>"L2"：dump kernel 级精度数据，PyTorch场景详细介绍见 [PyTorch 场景的 kernel dump 说明](./04.kernel_dump_PyTorch.md)；<br/>"mix"：dump module 模块级和 API 级精度数据，即"L0"+"L1"，仅 PyTorch 与 MindSpore 动态图场景支持。<br/>  **配置示例**："level": "L1"。                                                                                                                                                    | 否 |
-| enable_dataloader | 自动控制开关，bool 类型，仅 PyTorch 场景支持。可选参数 true（开启）或 false（关闭），默认为 false。配置为 true 后自动识别 step 参数指定的迭代，并在该迭代执行完成后退出训练，此时 start、stop 和 step 函数可不配置，开启该开关要求训练脚本是通过 torch.utils.data.dataloader 方式加载数据。仅支持 PyTorch 单卡训练使用，分布式训练场景下存在数据 dump 不全问题。 **这个特性下个版本将被废弃**                                                                                                                                                                                                                                                                                                           | 否       |
+| 参数    | 解释                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 是否必选 |
+| ----------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| task              | dump 的任务类型，str 类型。可选参数：<br/>  "statistics"：仅采集统计信息，默认值；<br/> "tensor"：采集统计信息和完全复刻整网的真实数据；<br/> "run_ut"：精度预检，仅 PyTorch 场景支持，采集数据时勿选；<br/> "overflow_check"：溢出检测；<br/>  "free_benchmark"：无标杆比对；<br/>  "grad_probe"：梯度监控； <br/> "structure"：仅采集模型结构以及调用栈信息，不采集具体数据。 <br/> 根据 task 参数取值的不同，可以配置不同场景参数，详见：<br/>[1.2 task 配置为 statistics](#12-task-配置为-statistics)，<br/>[1.3 task 配置为 tensor](#13-task-配置为-tensor)，<br/>[1.4 task 配置为 run_ut](#14-task-配置为-run_ut)，<br/>[1.5 task 配置为 overflow_check](#15-task-配置为-overflow_check)，<br/>[1.6 task 配置为 free_benchmark](#16-task-配置为-free_benchmark)，<br/>[1.7 task 配置为 grad_probe](#17-task-配置为-grad_probe)。 <br/>  **配置示例**："task": "tensor"。 | 否       |
+| dump_path         | 设置 dump 数据目录路径，str 类型。<br/>  **配置示例**："dump_path": "./dump_path"。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 是       |
+| rank              | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型，默认未配置（表示采集所有卡的数据），应配置元素为 ≥0 的整数或类似"4-6"的字符串，且须配置实际可用的 Rank ID。<br/>  PyTorch 场景: Rank ID 从 0 开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的 Rank ID，则 dump 数据为空，比如当前环境 Rank ID 为 0 到 7，实际训练运行 0 到 3 卡，此时若配置 Rank ID 为 4 或不存在的 10 等其他值，dump 数据为空。<br/>  MindSpore 场景：所有节点的 Rank ID 均从 0 开始计数，最大取值为每个节点可用卡总数-1，config.json 配置一次 rank 参数对所有节点同时生效。<br/> 注意，单卡训练时，rank必须为[]，即空列表，不能指定rank。<br/>**配置示例**："rank": [1, "4-6"]。                                                                                                                                                                                                                                | 否       |
+| step              | 指定采集某个 step 的数据，list[Union[int, str]] 类型。默认未配置，表示采集所有 step 数据。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 否       |
+| level             | dump 级别，str 类型，根据不同级别采集不同数据。可选参数：<br/>"L0"：dump 模块级精度数据，仅 PyTorch 与 MindSpore 动态图场景支持，使用背景详见 [1.1.1 模块级精度数据 dump 说明](#111-模块级精度数据-dump-说明)；<br/>"L1"：dump API 级精度数据，默认值，仅 PyTorch 与 MindSpore 动态图场景支持；<br/>"L2"：dump kernel 级精度数据，PyTorch场景详细介绍见 [PyTorch 场景的 kernel dump 说明](./04.kernel_dump_PyTorch.md)；MindSpore场景详细介绍见 [MindSpore 场景的 kernel dump 说明](./28.kernel_dump_MindSpore.md)；<br/>"mix"：dump module 模块级和 API 级精度数据，即"L0"+"L1"，仅 PyTorch 与 MindSpore 动态图场景支持。<br/>"debug"：单点保存功能，细节详见[单点保存工具 README](./28.debugger_save_instruction.md)<br/>  **配置示例**："level": "L1"。                                                                                                                                                                                                                                                                 | 否 |
+| enable_dataloader | 自动控制开关，bool 类型，仅 PyTorch 场景支持。可选参数 true（开启）或 false（关闭），默认为 false。配置为 true 后自动识别 step 参数指定的迭代，并在该迭代执行完成后退出训练，此时 start、stop 和 step 函数可不配置，开启该开关要求训练脚本是通过 torch.utils.data.dataloader 方式加载数据。仅支持 PyTorch 单卡训练使用，分布式训练场景下存在数据 dump 不全问题。 **这个特性下个版本将被废弃**                                                                                                                                                                                                                                                                                                                                                                                                                                    | 否       |
+| async_dump        | 异步 dump 开关，bool 类型。可选参数 true（开启）或 false（关闭），默认为 false。配置为 true 后开启异步 dump，即采集的精度数据会在当前 step 训练结束后统一落盘，训练过程中工具不触发同步操作。由于使用该模式有**显存溢出**的风险，当 task 配置为 tensor 时，即真实数据的异步dump模式，必须配置 [list](#13-task-配置为-tensor) 参数，指定需要 dump 的 tensor 。该模式暂不支持复数类型 tensor <br/>的统计量计算。                                                                                                                                                                                                                                                                                                                                                                                                                      | 否       |
 
 #### 1.1.1 模块级精度数据 dump 说明
 
@@ -29,17 +30,19 @@
 
 模块指的是继承 nn.Module 类（PyTorch场景）或 nn.Cell 类（MindSpore场景）的子类，通常情况下这类模块就是一个小模型，可以被视为一个整体，dump 数据时以模块为粒度进行 dump。
 
+
+
 ### 1.2 task 配置为 statistics
 
 <table>
     <tr><th>参数</th><th>解释</th><th>是否必选</th></tr>
-    <tr><td>scope</td><td>PyTorch 和 MindSpore 动态图场景 dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 API 的数据）。该参数可以在 [ ] 内配置两个模块名或 API 名，要求列表长度必须为2，需要配置按照工具命名格式的完整模块名或API名称，用于锁定区间，dump 该范围内的数据。<br/><b>配置示例</b>：  
-    "scope": ["Module.conv1.Conv2d.forward.0", "Module.fc2.Linear.forward.0"],                             
+    <tr><td>scope</td><td>PyTorch 和 MindSpore 动态图场景 dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 API 的数据）。该参数可以在 [ ] 内配置两个模块名或 API 名，要求列表长度必须为2，需要配置按照工具命名格式的完整模块名或API名称，用于锁定区间，dump 该范围内的数据。<br/><b>配置示例</b>：
+    "scope": ["Module.conv1.Conv2d.forward.0", "Module.fc2.Linear.forward.0"],
     或 "scope": ["Cell.conv1.Conv2d.forward.0", "Cell.fc2.Dense.backward.0"], 或"scope": ["Tensor.add.0.forward", "Functional.square.2.forward"]。与 level 参数取值相关，level 为 L0 级别时，可配置模块名；level 为 L1 级别时，可配置 API 名， level为 mix 级别时，可配置为模块名或API名。</td><td>否</td></tr>
     <tr><td rowspan="4">list</td><td>自定义采集的算子列表，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 API 的数据），包含以下配置方法：</td><td rowspan="4">否</td></tr>
     <tr><td>PyTorch 和 MindSpore 动态图场景配置具体的 API 全称，dump 该 API 数据。在 PyTorch 场景，如果 level 配置成 L2，该配置为必填项。<br/><b>配置示例</b>："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。<br/> PyTorch 和 MindSpore 动态图场景在level为 mix 级别时可以配置模块名称，dump该模块展开数据 （dump该模块从执行开始到执行结束期间的所有数据）。
     <br/><b>配置示例</b>："list": ["Module.module.language_model.encoder.layers.0.mlp.ParallelMlp.forward.0"], 或 "list": ["Cell.network_with_loss.language_model.encoder.layers.0.mlp.ParallelMlp.forward.0"]</td></tr>
-    <tr><td>PyTorch 和 MindSpore 动态图场景指定某一类 API，dump 某一类的 API 级别输入输出数据。<br/><b>配置示例</b>："list": ["relu"]。 <br/>    PyTorch 和 MindSpore 动态图场景在level为 mix 级别时, 会dump名称中包含list中配置的字符串的API数据，还会将名称中包含list中配置的字符串的模块进行展开dump （dump该模块从执行开始到执行结束期间的所有数据）。</td></tr> 
+    <tr><td>PyTorch 和 MindSpore 动态图场景指定某一类 API，dump 某一类的 API 级别输入输出数据。<br/><b>配置示例</b>："list": ["relu"]。 <br/>    PyTorch 和 MindSpore 动态图场景在level为 mix 级别时, 会dump名称中包含list中配置的字符串的API数据，还会将名称中包含list中配置的字符串的模块进行展开dump （dump该模块从执行开始到执行结束期间的所有数据）。</td></tr>
     <tr><td>MindSpore 静态图场景配置 kernel_name，可以是算子的名称列表，也可以指定算子类型（"level": "L2"时不支持），还可以配置算子名称的正则表达式（当字符串符合“name-regex(xxx)”格式时，后台则会将其作为正则表达式。<br/><b>配置示例</b>：list: ["name-regex(Default/.+)"]<br/>可匹配算子名称以“Default/”开头的所有算子。</td></tr>
     <tr><td rowspan="3">data_mode</td><td>dump 数据过滤，str 类型。</td><td rowspan="3">否</td></tr>
     <tr><td>PyTorch 与 MindSpore 动态图场景：支持"all"、"forward"、"backward"、"input"和"output"，除"all"外，其余参数可以自由组合。默认为["all"]，即保存所有 dump 的数据。<br/> <b>配置示例</b>："data_mode": ["backward"] （仅保存反向数据）或 "data_mode": ["forward", "input"]（仅保存前向的输入数据）。</td></tr>
@@ -161,4 +164,3 @@ PyTorch 与 MindSpore 动态图场景下，"level"须为"L0"或"L1"；MindSpore
 
    intervals就是根据值分布bounds划分出的区间。
    MindSpore静态图模式下，L0级别中暂不支持"MD5"
-

msprobe/docs/03.config_examples.md

@@ -100,6 +100,18 @@
 }
 ```
 
+### 1.6 task 配置为 structure
+
+```json
+{
+    "task": "structure",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "mix"
+}
+```
+
 ## 2 MindSpore 静态图场景
 
 ### 2.1 task 配置为 statistics
@@ -228,3 +240,15 @@
     }
 }
 ```
+
+### 3.5 task 配置为 structure
+
+```json
+{
+    "task": "structure",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "mix"
+}
+```

msprobe/docs/05.data_dump_PyTorch.md

@@ -44,7 +44,7 @@ level 配置为"L0"或"mix"时，必须在该接口或 **start** 接口中配置
 debugger.start(model=None)
 ```
 
-1. model：指定需要采集 Module 级数据的模型，支持传入 torch.nn.Module 或 list[torch.nn.Module] 类型，默认未配置。
+1. model：指定需要采集 Module 级数据的模型，支持传入 torch.nn.Module、list[torch.nn.Module]或Tuple[torch.nn.Module] 类型，默认未配置。
 level 配置为"L0"或"mix"时，必须在该接口或 **PrecisionDebugger** 接口中配置该参数。
 本接口中的 model 比 PrecisionDebugger 中 model 参数优先级更高，会覆盖 PrecisionDebugger 中的 model 参数。
 
@@ -52,8 +52,10 @@ level 配置为"L0"或"mix"时，必须在该接口或 **PrecisionDebugger** 接
 
 **功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。
 若 **stop** 函数添加在反向计算代码（如loss.backward）之后，则会采集 **start** 和该函数之间的前反向数据。
-若 **stop** 函数添加在反向计算代码之前，则需要将 **step** 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
-**step** 函数详细介绍见1.5章节。使用示例可参见 [2.1 快速上手](#21-快速上手) 和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
+若 **stop** 函数添加在反向计算代码之前，则需要将 [**step**](#15-step) 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
+使用示例可参见 [2.1 快速上手](#21-快速上手) 和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
+
+**注意**：**stop** 函数必须调用，否则可能导致精度数据落盘不全。
 
 **原型**：
 
@@ -123,7 +125,7 @@ seed_all(seed=1234, mode=False, rm_dropout=True)
 1. seed: 随机性种子。参数示例: seed=1000。默认值：1234。非必选
 2. mode：确定性计算模式。可配置True或False。参数示例：mode=True。默认为False。非必选（注意：确定性计算会导致API执行性能降低，建议在发现模型多次执行结果不同的情况下开启）
 3. rm_dropout：控制dropout失效的开关。可配置 True 或 False，默认值：True，非必选。参数示例：rm_dropout=True。
-该参数设置为 True 后， 工具会自动将 `torch.nn.functional.dropout`、`torch.nn.functional.dropout2d`、`torch.nn.functional.dropout3d`、`torch.nn.Dropout`、`torch.nn.Dropout2d`、`torch.nn.Dropout3d` 
+该参数设置为 True 后， 工具会自动将 `torch.nn.functional.dropout`、`torch.nn.functional.dropout2d`、`torch.nn.functional.dropout3d`、`torch.nn.Dropout`、`torch.nn.Dropout2d`、`torch.nn.Dropout3d`
 的接口参数 p 置为0，以避免因随机dropout造成的网络随机性。 注意：通过rm_dropout控制dropout失效或生效需要在初始化dropout实例前调用才能生效。
 
 当前工具 dump 默认不会固定随机性和使 dropout 失效，若希望每次采集的数据保持一致，建议在 dump 数据前调用 seed_all 接口。
@@ -169,6 +171,22 @@ train_loader = torch.utils.data.DataLoader(
 )
 ```
 
+### 1.9 save
+
+**功能说明**：单点保存网络执行过程中正反向数值，并以统计值/张量文件落盘。
+
+**原型**：
+```python
+save(variable, name, save_backward=True)
+```
+
+**参数说明**:
+| 参数名称        | 参数含义          |        支持数据类型    |   是否必选|
+| ----------     | ------------------| ------------------- | ------------------- |
+| variable       | 需要保存的变量     |dict, list, torch.tensor, int, float, str |  是  |
+| name           | 指定的名称         | str                 | 是  |
+| save_backward  | 是否保存反向数据   | boolean             | 否 |
+
 ## 2 示例代码
 
 ### 2.1 快速上手
@@ -254,7 +272,7 @@ for data, label in data_loader:
     debugger.start()  # 开启数据dump
     # 如下是模型每个step执行的逻辑
     output = model(data)
-    
+
     debugger.forward_backward_dump_end()  # 插入该函数到start函数之后，只dump start函数到该函数之间的前反向数据。
     # ...
     loss.backward()
@@ -300,7 +318,7 @@ if __name__ == "__main__":
     loss = out.sum()                   # module_dump_end和stop接口之间的数据正常dump
     loss.backward()
     # 关闭数据dump
-    debugger.stop()  
+    debugger.stop()
 ```
 
 ## 3 dump 结果文件介绍
@@ -313,14 +331,15 @@ if __name__ == "__main__":
 │   |   ├── rank0
 │   |   │   ├── dump_tensor_data
 |   |   |   |    ├── Tensor.permute.1.forward.pt
-|   |   |   |    ├── Module.conv1.Conv2d.forward.0.input.0.pt   # 命名格式为{Module}.{module_name}.{class_name}.{forward/backward}.{调用次数}.{input/output}.{参数序号}, 其中，“参数序号”表示该Module的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该Module的第1个参数的第1个元素。
-|   |   |   |    ├── Module.conv1.Conv2D.forward.0.parameters.bias.pt  # 模块参数数据：命名格式为{Module}.{module_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
-|   |   |   |    ├── Module.conv1.Conv2D.parameters_grad.weight.pt  # 模块参数梯度数据：命名格式为{Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
+|   |   |   |    ├── Functional.linear.5.backward.output.pt    # 命名格式为{api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号}, 其中，“参数序号”表示该API的第n个输入或输出，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个元素。
 |   |   |   |    ...
-|   |   |   |    └── Functional.linear.5.backward.output.pt    # 命名格式为{api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号}, 其中，“参数序号”表示该API的第n个输入或输出，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个元素。
-│   |   |   ├── dump.json       
-│   |   |   ├── stack.json        
-│   |   |   └── construct.json        
+|   |   |   |    ├── Module.conv1.Conv2d.forward.0.input.0.pt          # 命名格式为{Module}.{module_name}.{class_name}.{forward/backward}.{调用次数}.{input/output}.{参数序号}, 其中，“参数序号”表示该Module的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该Module的第1个参数的第1个元素。
+|   |   |   |    ├── Module.conv1.Conv2D.forward.0.parameters.bias.pt  # 模块参数数据：命名格式为{Module}.{module_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
+|   |   |   |    └── Module.conv1.Conv2D.parameters_grad.weight.pt     # 模块参数梯度数据：命名格式为{Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
+|   |   |   |                                                          # 当dump时传入的model参数为List[torch.nn.Module]或Tuple[torch.nn.Module]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为{Module}.{index}.*，*表示以上三种模块级数据的命名格式，例如：Module.0.conv1.Conv2d.forward.0.input.0.pt。
+│   |   |   ├── dump.json
+│   |   |   ├── stack.json
+│   |   |   └── construct.json
 │   |   ├── rank1
 |   |   |   ├── dump_tensor_data
 |   |   |   |   └── ...
@@ -333,12 +352,12 @@ if __name__ == "__main__":
 │   ├── step1
 │   |   ├── ...
 │   ├── step2
-```  
+```
 * `rank`：设备 ID，每张卡的数据保存在对应的 `rank{ID}` 目录下。非分布式场景下没有 rank ID，目录名称为 rank。
 * `dump_tensor_data`：保存采集到的张量数据。
 * `dump.json`： 保存API或Module前反向数据的统计量信息。包含dump数据的API名称或Module名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#1-dumpjson文件介绍pytorch)。
 * `stack.json`：API/Module的调用栈信息。
-* `construct.json`：分层分级结构，level为L1时，construct.json内容为空。  
+* `construct.json`：分层分级结构，level为L1时，construct.json内容为空。
 
 
 dump 过程中，pt 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。

msprobe/docs/06.data_dump_MindSpore.md

@@ -28,31 +28,33 @@ msprobe 工具通过在训练脚本中添加 `PrecisionDebugger` 接口并启动
 
 dump 的"tensor"模式采集数据量大小，可以参考[数据量基线](data_dump_MindSpore/data_dump_MindSpore_baseline.md)。
 
-## 5. 场景介绍 
+## 5. 场景介绍
 
-### 5.1 静态图场景 
-在静态图场景下，msprobe 仅支持 **L2 Level**  的数据采集。 
+### 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`）** ： 
+### 5.2 动态图场景
+在动态图场景下，msprobe 支持 **L0** 、**L1** 、**mix** 、**L2 Level**、 **debug**  的数据采集，具体分为以下几种情况：
+- **使用高阶 API（如 `Model 高阶API`）** ：
   - 需要使用 `MsprobeStep` 回调类来控制数据采集的启停，适用于 **L0** 、**L1** 、**mix** 、**L2** 数据采集。
- 
-- **未使用高阶 API** ： 
+
+- **未使用高阶 API** ：
   - 手动在训练循环中调用 `start`、`stop`、`step` 等接口，适用于 **L0** 、**L1** 、**mix** 、**L2** 数据采集。
 
 采集方式请参见[示例代码 > 动态图场景](#72-动态图场景)。
 
-> **注意** ：动态图模式下，使用 `PSJit` 或 `PIJit` 装饰的部分实际以静态图模式执行，此时的 **Kernel 级（L2 Level）**  数据采集方式与静态图场景相同。 
+> **注意** ：动态图模式下，使用 `PSJit` 或 `PIJit` 装饰的部分实际以静态图模式执行，此时的 **Kernel 级（L2 Level）**  数据采集方式与静态图场景相同。
 - **L0 Level（Cell 级）** ：采集 `Cell` 对象的数据，适用于需要分析特定网络模块的情况。
- 
+
 - **L1 Level（API 级）** ：采集 MindSpore API 的输入输出数据，适用于定位 API 层面的精度问题。
 
 - **mix（模块级 + API 级）** ：在 `L0` 和 `L1` 级别的基础上同时采集模块级和 API 级数据，适用于需要分析模块和 API 层面精度问题的场景。
 
+- **debug level （单点保存）**：单点保存网络中变量的正反向数据，适用于用户熟悉网络结构的场景。
+
 
 详细介绍请参见[《config.json 配置文件介绍》](./02.config_introduction.md#11-通用配置)中的“level 参数”和[《config.json 配置示例》](./03.config_examples.md#3-mindspore-动态图场景) 中的“MindSpore 动态图场景”。
 
@@ -88,13 +90,15 @@ start(model=None)
 
 **参数说明**:
 
-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. model：指定需要采集数据的实例化模型，支持传入mindspore.nn.Cell、List[mindspore.nn.Cell]或Tuple[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 数据。
 
 #### 6.1.2 stop
 
 **功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。若 **stop** 函数添加在反向计算代码之后，则会采集 **start** 和该函数之间的前反向数据。
-若 **stop** 函数添加在反向计算代码之前，则需要将 **step** 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
-**step** 函数详细介绍见6.1.3章节。**仅未使用 Model 高阶 API 的动态图场景支持。**
+若 **stop** 函数添加在反向计算代码之前，则需要将 [**step**](#613-step) 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
+**仅未使用 Model 高阶 API 的动态图场景支持。**
+
+**注意**：**stop** 函数必须调用，否则可能导致精度数据落盘不全。
 
 **原型**：
 
@@ -128,6 +132,24 @@ step()
 forward_backward_dump_end()
 ```
 
+#### 6.1.5 save
+
+**功能说明**：单点保存网络执行过程中正反向数值，并以统计值/张量文件落盘。
+
+**原型**：
+```python
+save(variable, name, save_backward=True)
+```
+
+**参数说明**:
+| 参数名称        | 参数含义          |        支持数据类型    |   是否必选|
+| ----------     | ------------------| ------------------- | ------------------- |
+| variable       | 需要保存的变量     |dict, list, torch.tensor, int, float, str |  是  |
+| name           | 指定的名称         | str                 | 是  |
+| save_backward  | 是否保存反向数据   | boolean             | 否 |
+
+
+
 ### 6.2 msprobe.mindspore.common.utils.MsprobeStep
 
 **功能说明**：MindSpore Callback类，自动在每个step开始时调用start()接口，在每个step结束时调用stop()、step()接口。实现使用 Model 高阶 API 的动态图场景下 L0、L1、mix 级别的精度数据采集控制，控制粒度为单个 **Step** ，而 PrecisionDebugger.start, PrecisionDebugger.stop 接口的控制粒度任意训练代码段。
@@ -183,7 +205,7 @@ debugger.start()
 
 #### 7.2.1 L0 ,L1, mix 级别
 
-##### 7.2.1.1 未使用 Model 高阶 API 
+##### 7.2.1.1 未使用 Model 高阶 API
 
 
 ```python
@@ -207,7 +229,7 @@ for data, label in data_loader:
     debugger.step()         # 更新迭代数
 ```
 
-##### 7.2.1.2 使用 Model 高阶 API 
+##### 7.2.1.2 使用 Model 高阶 API
 
 
 ```python
@@ -231,7 +253,7 @@ trainer.train(1, train_dataset, callbacks=[MsprobeStep(debugger)])
 
 #### 7.2.2 L2 级别
 
-##### 7.2.2.1 未使用 Model 高阶 API 
+##### 7.2.2.1 未使用 Model 高阶 API
 
 
 ```python
@@ -254,7 +276,7 @@ for data, label in data_loader:
 ```
 
 
-##### 7.2.2.2 使用 Model 高阶 API 
+##### 7.2.2.2 使用 Model 高阶 API
 
 
 ```python
@@ -322,14 +344,15 @@ dump 结果目录结构示例如下：
 │   |   │   ├── dump_tensor_data
 |   |   |   |    ├── MintFunctional.relu.0.backward.input.0.npy
 |   |   |   |    ├── Mint.abs.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个元素。   
+|   |   |   |    ├── 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
 |   |   |   |    ├── 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个元素。   
+|   |   |   |    ├── 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时传入的model参数为List[mindspore.nn.Cell]或Tuple[mindspore.nn.Cell]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为{Cell}.{index}.*，*表示以上三种模块级数据的命名格式，例如：Cell.0.relu.ReLU.forward.0.input.0.npy。
 │   |   |   ├── dump.json
 │   |   |   ├── stack.json
 │   |   |   └── construct.json
@@ -351,7 +374,7 @@ dump 结果目录结构示例如下：
 * `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内容为空。  
+* `construct.json`：分层分级结构，level为L1时，construct.json内容为空。
 
 dump 过程中，npy 文件在对应API或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，因此，程序异常终止时，被执行API对应的 npy 文件已被保存，但 json 文件中的数据可能丢失。
 

msprobe/docs/09.accuracy_checker_MindSpore.md

@@ -4,9 +4,11 @@
 
 **MindSpore 动态图精度预检**<sup>a</sup>通过扫描昇腾 NPU 上用户训练 MindSpore 模型中的所有 Mint API，输出精度情况的诊断和分析。工具以模型中所有 Mint API 前反向的 dump 结果为输入，构造相应的 API 单元测试，将 NPU 输出与标杆（CPU 高精度）比对，计算对应的精度指标，从而找出 NPU 中存在精度问题的 Mint API。本工具支持**随机生成模式和真实数据模式**<sup>b</sup>。
 
-a. 支持 Mindspore 版本：2.4；
+a. 支持 Mindspore 版本：2.4/2.5；
 
-b. 在预检时可以由工具构造随机数据或者获取真实dump数据进行预检操作。随机生成模式执行效率高，可以快速获得结果，但结果准确度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，并且需要较大磁盘空间存放待预检数据，但是结果准确度高，可以准确判断精度问题。
+b. （可选）当使用Msadapter时，由于需要环境中同时存在 Torch 与 Msadapter，所以只支持在**安装原生Torch**的场景下通过export PYTHONPATH="xx/msadapter/build/lib"等通过**环境变量使能Msadapter的方式**的环境中进行预检,预检工具能够自动索引得到所需的 Torch 与 Msadapter环境,环境安装详细参考:[msadapter官网](https://gitee.com/mindspore/msadapter)。
+
+c. 在预检时可以由工具构造随机数据或者获取真实dump数据进行预检操作。随机生成模式执行效率高，可以快速获得结果，但结果准确度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，并且需要较大磁盘空间存放待预检数据，但是结果准确度高，可以准确判断精度问题。
 
 ## 2 离线预检流程