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

msprobe/docs/27.dump_json_instruction.md

@@ -1,8 +1,8 @@
 # dump.json文件说明及示例  
 
-## 1. dump.json文件示例（PyTorch）  
+## 1. PyTorch 场景下的 dump.json 文件
 
-### 1.1 L0级别
+### 1.1 L0 级别
 L0级别的dump.json文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。以PyTorch的Conv2d模块为例，网络中模块调用代码为:  
 `output = self.conv2(input) # self.conv2 = torch.nn.Conv2d(64, 128, 5, padding=2, bias=True)`  
 
@@ -168,7 +168,7 @@ dump.json文件中包含以下数据名称：
 }
 ```
 
-### 1.2 L1级别
+### 1.2 L1 级别
 L1级别的dump.json文件包括API的前反向的输入输出。以PyTorch的relu函数为例，网络中API调用代码为:  
 `output = torch.nn.functional.relu(input)`  
 
@@ -264,13 +264,13 @@ dump.json文件中包含以下数据名称：
 }  
 ```  
 
-### 1.3 mix级别
+### 1.3 mix 级别
 
 mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。  
 
-## 2. dump.json文件示例（MindSpore） 
+## 2. MindSpore 场景下的 dump.json 文件
 
-### 2.1 L0级别  
+### 2.1 L0 级别  
 
 L0级别的dump.json文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。
 以MindSpore的Conv2d模块为例，dump.json文件中使用的模块调用代码为:  
@@ -429,7 +429,7 @@ dump.json文件中包含以下数据名称：
 }
 ```
 
-### 2.2 L1级别
+### 2.2 L1 级别
 L1级别的dump.json文件包括API的前反向的输入输出，以MindSpore的relu函数为例，网络中API调用代码为:  
  `output = mindspore.ops.relu(input)`  
 
@@ -521,5 +521,275 @@ L1级别的dump.json文件包括API的前反向的输入输出，以MindSpore的
 }  
 ```  
 
-### 2.3 mix级别
+### 2.3 mix 级别
+
 mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。
+
+## 3. MSAdapter 场景下的 dump.json 文件
+
+### 3.1 L0 级别
+
+L0 级别的 dump.json 文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。以 Conv2d 模块为例，网络中模块调用代码为:  
+`output = self.conv2(input) # self.conv2 = torch.nn.Conv2d(64, 128, 5, padding=2, bias=True)`  
+
+dump.json文件中包含以下数据名称：  
+
+- `Module.conv2.Conv2d.forward.0`：模块的前向数据，其中input_args为模块的输入数据（位置参数），input_kwargs为模块的输入数据（关键字参数），output为模块的输出数据，parameters为模块的参数数据，包括权重（weight）和偏置（bias）。  
+- `Module.conv2.Conv2d.parameters_grad`：模块的参数梯度数据，包括权重（weight）和偏置（bias）的梯度。  
+- `Module.conv2.Conv2d.backward.0`：模块的反向数据，其中input为模块反向的输入梯度（对应前向输出的梯度），output为模块的反向输出梯度（对应前向输入的梯度）。
+
+**说明**：当dump时传入的model参数为List[torch.nn.Module]或Tuple[torch.nn.Module]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为`{Module}.{index}.*`，*表示以上三种模块级数据的命名格式，例如：`Module.0.conv1.Conv2d.forward.0`。     
+
+```json
+{
+ "task": "tensor",
+ "level": "L0",
+ "framework": "mindtorch",
+ "dump_data_dir": "/dump/path",
+ "data": {
+  "Module.conv2.Conv2d.forward.0": {
+   "input_args": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      8,
+      16,
+      14,
+      14
+     ],
+     "Max": 1.638758659362793,
+     "Min": 0.0,
+     "Mean": 0.2544615864753723,
+     "Norm": 70.50277709960938,
+     "requires_grad": true,
+     "data_name": "Module.conv2.Conv2d.forward.0.input.0.npy"
+    }
+   ],
+   "input_kwargs": {},
+   "output": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      8,
+      32,
+      10,
+      10
+     ],
+     "Max": 1.6815717220306396,
+     "Min": -1.5120246410369873,
+     "Mean": -0.025344856083393097,
+     "Norm": 149.65576171875,
+     "requires_grad": true,
+     "data_name": "Module.conv2.Conv2d.forward.0.output.0.npy"
+    }
+   ],
+   "parameters": {
+    "weight": {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      5,
+      5
+     ],
+     "Max": 0.05992485210299492,
+     "Min": -0.05999220535159111,
+     "Mean": -0.0006165213999338448,
+     "Norm": 3.421217441558838,
+     "requires_grad": true,
+     "data_name": "Module.conv2.Conv2d.forward.0.parameters.weight.npy"
+    },
+    "bias": {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32
+     ],
+     "Max": 0.05744686722755432,
+     "Min": -0.04894155263900757,
+     "Mean": 0.006410328671336174,
+     "Norm": 0.17263513803482056,
+     "requires_grad": true,
+     "data_name": "Module.conv2.Conv2d.forward.0.parameters.bias.npy"
+    }
+   }
+  },
+  "Module.conv2.Conv2d.parameters_grad": {
+   "weight": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      5,
+      5
+     ],
+     "Max": 0.018550323322415352,
+     "Min": -0.008627401664853096,
+     "Mean": 0.0006675920449197292,
+     "Norm": 0.26084786653518677,
+     "requires_grad": false,
+     "data_name": "Module.conv2.Conv2d.parameters_grad.weight.npy"
+    }
+   ],
+   "bias": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32
+     ],
+     "Max": 0.014914230443537235,
+     "Min": -0.006656786892563105,
+     "Mean": 0.002657240955159068,
+     "Norm": 0.029451673850417137,
+     "requires_grad": false,
+     "data_name": "Module.conv2.Conv2d.parameters_grad.bias.npy"
+    }
+   ]
+  },
+  "Module.conv2.Conv2d.backward.0": {
+   "input": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      8,
+      32,
+      10,
+      10
+     ],
+     "Max": 0.0015069986693561077,
+     "Min": -0.001139344065450132,
+     "Mean": 3.3215508210560074e-06,
+     "Norm": 0.020567523315548897,
+     "requires_grad": false,
+     "data_name": "Module.conv2.Conv2d.backward.0.input.0.npy"
+    }
+   ],
+   "output": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      8,
+      16,
+      14,
+      14
+     ],
+     "Max": 0.0007466732058674097,
+     "Min": -0.00044813455315306783,
+     "Mean": 6.814070275140693e-06,
+     "Norm": 0.01474067009985447,
+     "requires_grad": false,
+     "data_name": "Module.conv2.Conv2d.backward.0.output.0.npy"
+    }
+   ]
+  }
+ }
+}
+```
+
+### 3.2 L1 级别
+L1级别的dump.json文件包括API的前反向的输入输出。以 relu API 为例，网络中 API 调用代码为:  
+`output = torch.nn.functional.relu(input)`  
+
+dump.json文件中包含以下数据名称：  
+- `Functional.relu.0.forward`：API的前向数据，其中input_args为API的输入数据（位置参数），input_kwargs为API的输入数据（关键字参数），output为API的输出数据。  
+- `Functional.relu.0.backward`：API的反向数据，其中input为API的反向输入梯度（对应前向输出的梯度），output为API的反向输出梯度（对应前向输入的梯度）。
+
+```json
+{
+ "task": "tensor",
+ "level": "L1",
+ "framework": "mindtorch",
+ "dump_data_dir":"/dump/path",
+ "data": {
+  "Functional.relu.0.forward": {
+   "input_args": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      28,
+      28
+     ],
+     "Max": 1.3864083290100098,
+     "Min": -1.3364859819412231,
+     "Mean": 0.03711778670549393,
+     "Norm": 236.20692443847656,
+     "requires_grad": true,
+     "data_name": "Functional.relu.0.forward.input.0.npy"
+    }
+   ],
+   "input_kwargs": {},
+   "output": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      28,
+      28
+     ],
+     "Max": 1.3864083290100098,
+     "Min": 0.0,
+     "Mean": 0.16849493980407715,
+     "Norm": 175.23345947265625,
+     "requires_grad": true,
+     "data_name": "Functional.relu.0.forward.output.0.npy"
+    }
+   ]
+  },
+  "Functional.relu.0.backward": {
+   "input": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      28,
+      28
+     ],
+     "Max": 0.0001815402356442064,
+     "Min": -0.00013352684618439525,
+     "Mean": 0.00011915402356442064,
+     "Norm": 0.007598237134516239,
+     "requires_grad": false,
+     "data_name": "Functional.relu.0.backward.input.0.npy"
+    }
+   ],
+   "output": [
+    {
+     "type": "mindspore.Tensor",
+     "dtype": "Float32",
+     "shape": [
+      32,
+      16,
+      28,
+      28
+     ],
+     "Max": 0.0001815402356442064,
+     "Min": -0.00012117840378778055,
+     "Mean": 2.0098118724831693e-08,
+     "Norm": 0.006532244384288788,
+     "requires_grad": false,
+     "data_name": "Functional.relu.0.backward.output.0.npy"
+    }
+   ]
+  }
+ }
+}  
+```  
+
+### 3.3 mix 级别
+
+mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。  

msprobe/docs/28.debugger_save_instruction.md

@@ -1,28 +1,33 @@
-# 单点保存工具 README
+# 单点保存工具
 
 ## 简介
-L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被批量dump下来。单点保存提供类似np.save和print的功能和使用体验，可以保存指定的变量。同时针对大模型场景进行了增强，具备以下特性：
+L0, L1, mix级别的dump能力存在盲区，网络中的非API或module的输入输出不会被批量dump下来。单点保存提供类似np.save和print的功能和使用体验，可以保存指定的变量。同时针对大模型场景进行了增强，具备以下特性：
 - 可保存变量的反向梯度结果。
 - 能直接保存嵌套结构数据（如 list、dict），无需手动遍历。
-- 自动分 rank 保存。
+- 自动分 Rank 保存。
+- 可分 Step 保存数据。
 - 多次调用时会自动计数。
-- 可配置保存统计值或者张量。
+- 可配置保存统计值（MindSpore静态图暂不支持）或者张量。
+- 支持异步保存。
 
 ## 支持场景
-仅支持 PyTorch 与 MindSpore 的动态图场景。
 
-## 使能方式
+## 动态图场景（Pytorch&MindSpore）
 
-### 配置文件说明
+###  使能方式
 
-通用配置：
+#### 配置文件说明
+
+通用配置 （细节详见[通用配置说明](./02.config_introduction.md#11-通用配置) ）：
 
 | 参数     | 解释                                       | 是否必选 |
 | -------- |-------------------------------------------| -------- |
 | task     | dump 的任务类型，str 类型。 单点保存场景仅支持传入"statistics", "tensor"。    |  是     |
 | level    | dump 级别，str 类型，根据不同级别采集不同数据。单点保存场景传入"debug"。  | 是  |
-| dump_path  | 设置 dump 数据目录路径，str 类型。细节详见[通用配置说明](./02.config_introduction.md#11-通用配置)  | 是       |
-| rank        | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型。细节详见[通用配置说明](./02.config_introduction.md#11-通用配置)  | 否       |
+| dump_path  | 设置 dump 数据目录路径，str 类型。 | 是       |
+| rank        | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型。  | 否       |
+| step    |   指定采集某个 Step 的数据，list[Union[int, str]] 类型。  | 否       |
+| async_dump        | 异步 dump 开关，bool 类型。  | 否       |
 
 "statistics" 任务子配置项：
 | 参数     | 解释                                       | 是否必选 |
@@ -31,19 +36,21 @@ L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被
 
 "tensor" 任务无子配置项。
 
-### 接口调用说明
-
-调用PrecisionDebugger.save，传入需要保存的变量，指定变量名称以及是否需要保存反向数据。接口入参说明详见[pytorch单点保存接口](./05.data_dump_PyTorch.md#19-save)，[mindspore单点保存接口](./06.data_dump_MindSpore.md#615-save)
+#### 接口调用说明
 
-### 实例（以pytorch场景为例）
+调用PrecisionDebugger.save，传入需要保存的变量，指定变量名称以及是否需要保存反向数据。接口入参说明详见[PyTorch单点保存接口](./05.data_dump_PyTorch.md#19-save)，[MindSpore单点保存接口](./06.data_dump_MindSpore.md#615-save)
 
+#### 实例
+（以PyTorch场景为例，MindSpore场景只需要从msprobe.mindspore模块导包即可）
 配置文件
 ```json
 {
     "task": "statistics",
     "dump_path": "./dump_path",
     "rank": [],
+    "step": [],
     "level": "debug",
+    "async_dump": false,
     "statistics": {
         "summary_mode": "statistics"
     }
@@ -53,7 +60,7 @@ L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被
 初始化
 ```python
 # 训练启动py脚本
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 debugger = PrecisionDebugger("./config.json")
 for data, label in data_loader:
     # 执行模型训练
@@ -64,7 +71,7 @@ for data, label in data_loader:
 初始化（无配置文件）
 ```python
 # 训练启动py脚本
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 debugger = PrecisionDebugger(dump_path="dump_path", level="debug")
 for data, label in data_loader:
     # 执行模型训练
@@ -75,20 +82,104 @@ for data, label in data_loader:
 调用保存接口
 ```python
 # 训练过程中被调用py文件
-from mindspore.pytorch import PrecisionDebugger
+from msprobe.pytorch import PrecisionDebugger
 dict_variable = {"key1": "value1", "key2": [1, 2]}
 PrecisionDebugger.save(dict_variable, "dict_variable", save_backward=False)
 
 ```
 
+## 静态图场景（MindSpore）
+
+### 使能方式
+
+#### 接口调用说明
+工具提供两个对外接口`save`和`save_grad`，分别用于保存训练中的tensor以及tensor对应的反向数据
+| 接口名称 | 入参   | device         | MindSpore版本 |备注                                                         |
+| ------- | ------ | -------------- | --------------|--------------------------------------------------- |
+| save     | save_dir name, data    | Ascend   | >= 2.6.0   |  （主流场景）图模式下只支持Ascend，pynative下支持Ascend/GPU/CPU。         |
+| save_grad | save_dir, name, data | Ascend     | >= 2.6.0   |  （主流场景）图模式下只支持Ascend，pynative下支持Ascend/GPU/CPU。         |
+
+
+----
+> 函数原型:
+`save(save_dir:str, name:str, data)`
+- save_dir：表示要保存的目录。
+- name    ：表示要保存的文件标志名称。
+- data    ：表示数据入参，可以是`mindspore.Tensor`或者是`List`,`Tuple`,`Dict`等嵌套结构。
+
+> 函数原型：
+`save_grad(save_dir:str, name:str, data)`
+- save_dir：表示要保存的目录。
+- name    ：表示要保存的文件标志名称。
+- data    ：表示数据入参，**只能**是`mindspore.Tensor`。
+
+#### 实例
+
+- save接口使用：
+
+```python
+# save api usage
+# **first import**
+from msprobe.mindspore import save
+
+
+class Net(nn.Cell):
+    def construct(self, x, y, z):
+        # **use save api**
+        save("./test_dump", 'x', x)
+        return x * y * z
+
+x = Tensor([1, 2], ms.float32)
+y = Tensor([-2, 3], ms.float32)
+z = Tensor([0, 3], ms.float32)
+net = Net()
+output = grad(net, grad_position=(1, 2))(x, y, z)
+time.sleep(1)
+
+# then will generate **./test_dump/step0/rank0/x_float32_0.npy**
+```
+
+- save_grad接口使用：
+
+```python
+# save_grad usage
+# **first import**
+from msprobe.mindspore import save_grad
+class Net(nn.Cell):
+    def construct(self, x, y, z):
+        # **use save api** the return value of save_grad must be received by origin
+        z = save_grad("./test_dump", 'z', z)
+        return x * y * z
+
+x = Tensor([1, 2], ms.float32)
+y = Tensor([-2, 3], ms.float32)
+z = Tensor([0, 3], ms.float32)
+net = Net()
+output = grad(net, grad_position=(1, 2))(x, y, z)
+time.sleep(1)
+
+# then will generate **./test_dump/step0/rank0/z_grad_float32_0.npy**
+```
+**注意**save_grad需要将返回值回传给原tensor，此操作不会有精度影响，只会传递原值。
+
+
 ## 输出结果
+### 动态图场景（Pytorch&MindSpore）
   * **"task" 配置为 "statistics" 场景** ：在 dump 目录下会生成包含变量统计值信息的 `debug.json` 文件。
-  * **"task" 配置为 "tensor" 场景** ：除了在 dump 目录下生成包含变量统计值信息的 `debug.json` 文件外，还会在 dump 子目录 `dump_tensor_data` 中保存张量二进制文件，文件名称格式为 `{variable_name}{grad_flag}.{count}.tensor.{indexes}.{file_suffix}`。
+  `debug.json` 中统计值的key命名格式为 `{variable_name}{grad_flag}.{count}.debug`。
+  * **"task" 配置为 "tensor" 场景** ：除了在 dump 目录下生成包含变量统计值信息的 `debug.json` 文件外，还会在 dump 子目录 `dump_tensor_data` 中保存张量二进制文件，文件名称格式为 `{variable_name}{grad_flag}.{count}.debug.{indexes}.{file_suffix}`。
 
     - variable_name： 传入save接口的变量名称。
     - grad_flag： 反向数据标识，反向数据为"_grad"，正向数据为""。
     - count： 调用计数，多次以相同变量名称调用时的计数。
-    - indexes： 索引，在保存嵌套结构数据时的索引。例如：嵌套结构为`{"key1": "value1", "key2": ["value2", "value3"]}`，"value2"的索引为"key2.0"
-    - file_suffix：文件后缀，pytorch场景为"pt"，mindspore场景为"npy"
+    - indexes： 索引，在保存嵌套结构数据时的索引。例如：嵌套结构为`{"key1": "value1", "key2": ["value2", "value3"]}`，"value2"的索引为"key2.0"。
+    - file_suffix：文件后缀，PyTorch场景为"pt"，MindSpore场景为"npy"。
+
+### 静态图场景（MindSpore）
+在指定目录`save_dir`下生成`{step}/{rank}`目录，目录下生成指定`{name}`的npy文件，如果是save_grad接口调用，则会生成`{name}_grad`的npy文件。
+
+如`save("./test_dump", 'x', x)` -> `./test_dump/step0/rank0/x_float32_0.npy`。
+
+或如`z = save_grad("./test_dump", 'z', z)` -> `./test_dump/step0/rank0/z_grad_float32_0.npy`。
 
 

msprobe/docs/28.kernel_dump_MindSpore.md

@@ -1,4 +1,4 @@
-# MindSpore 场景的 kernel dump 说明
+# MindSpore 动态图场景的 kernel dump 说明
 
 当使用 msprobe 数据采集功能时，level 配置为 "L2" 表示采集 kernel 层级的算子数据，仅支持昇腾 NPU 平台。