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

msprobe/docs/26.data_dump_PyTorch_baseline.md

@@ -0,0 +1,37 @@
+# PyTorch 场景的精度数据采集基线
+
+## "tensor"模式采集数据量参考基线
+
+该基线为pytorch框架下，使用"tensor"模式采集数据量参考基线。本基线测试了两个模型，分别为LLAMA2-7B和LLAMA2-13B，测试了不同采集模式下，不同global_batch_size下，单卡和8卡下，数据量的变化。
+
+### LLAMA2-7B
+
+<table>
+    <tr><th>采集模式</th><th>global_batch_size</th><th>单卡</th><th>8卡</th></tr>
+    </td><td rowspan="3">L0</td><td>1</td><td>7.8GB</td><td>63GB</td></tr>
+    <tr><td>2</td><td>16GB</td><td>125GB</td></tr>
+    <tr><td>3</td><td>24GB</td><td>187GB</td></tr>
+    </td><td rowspan="3">L1</td><td>1</td><td>300.8GB</td><td>2.3TB</td></tr>
+    <tr><td>2</td><td>480GB</td><td>3.6TB</td></tr>
+    <tr><td>3</td><td>640GB</td><td>4.9TB</td></tr>
+    </td><td rowspan="3">mix</td><td>1</td><td>313.6GB</td><td>2.4TB</td></tr>
+    <tr><td>2</td><td>512GB</td><td>3.8TB</td></tr>
+    <tr><td>3</td><td>672GB</td><td>5.1TB</td></tr>
+
+</table>
+
+### LLAMA2-13B
+
+<table>
+    <tr><th>采集模式</th><th>global_batch_size</th><th>单卡</th><th>8卡</th></tr>
+    </td><td rowspan="3">L0</td><td>1</td><td>13GB</td><td>97GB</td></tr>
+    <tr><td>2</td><td>25B</td><td>194GB</td></tr>
+    <tr><td>3</td><td>37G</td><td>291GB</td></tr>
+    </td><td rowspan="3">L1</td><td>1</td><td>440GB</td><td>3.4TB</td></tr>
+    <tr><td>2</td><td>720GB</td><td>5.4TB</td></tr>
+    <tr><td>3</td><td>960GB</td><td>7.3TB</td></tr>
+    </td><td rowspan="3">mix</td><td>1</td><td>480GB</td><td>3.6TB</td></tr>
+    <tr><td>2</td><td>720GB</td><td>5.6TB</td></tr>
+    <tr><td>3</td><td>1000GB</td><td>7.7TB</td></tr>
+
+</table>

msprobe/docs/27.dump_json_instruction.md

@@ -0,0 +1,525 @@
+# dump.json文件说明及示例  
+
+## 1. dump.json文件示例（PyTorch）  
+
+### 1.1 L0级别
+L0级别的dump.json文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。以PyTorch的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": "pytorch",
+ "dump_data_dir": "/dump/path",
+ "data": {
+  "Module.conv2.Conv2d.forward.0": {
+   "input_args": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "input_kwargs": {},
+   "output": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "parameters": {
+    "weight": {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    },
+    "bias": {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   }
+  },
+  "Module.conv2.Conv2d.parameters_grad": {
+   "weight": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "bias": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ]
+  },
+  "Module.conv2.Conv2d.backward.0": {
+   "input": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "output": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ]
+  }
+ }
+}
+```
+
+### 1.2 L1级别
+L1级别的dump.json文件包括API的前反向的输入输出。以PyTorch的relu函数为例，网络中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": "pytorch",
+ "dump_data_dir":"/dump/path",
+ "data": {
+  "Functional.relu.0.forward": {
+   "input_args": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "input_kwargs": {},
+   "output": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ]
+  },
+  "Functional.relu.0.backward": {
+   "input": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ],
+   "output": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.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.pt"
+    }
+   ]
+  }
+ }
+}  
+```  
+
+### 1.3 mix级别
+
+mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。  
+
+## 2. dump.json文件示例（MindSpore） 
+
+### 2.1 L0级别  
+
+L0级别的dump.json文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。
+以MindSpore的Conv2d模块为例，dump.json文件中使用的模块调用代码为:  
+`output = self.conv2(input) # self.conv2 = mindspore.nn.Conv2d(64, 128, 5, pad_mode='same', has_bias=True)`  
+
+dump.json文件中包含以下数据名称：  
+- `Cell.conv2.Conv2d.forward.0`：模块的前向数据，其中input_args为模块的输入数据（位置参数），input_kwargs为模块的输入数据（关键字参数），output为模块的输出数据，parameters为模块的参数数据，包括权重（weight）和偏置（bias）。  
+- `Cell.conv2.Conv2d.parameters_grad`：模块的参数梯度数据，包括权重（weight）和偏置（bias）的梯度。  
+- `Cell.conv2.Conv2d.backward.0`：模块的反向数据，其中input为模块反向的输入梯度（对应前向输出的梯度），output为模块的反向输出梯度（对应前向输入的梯度）。
+
+**说明**：当dump时传入的model参数为List[mindspore.nn.Cell]或Tuple[mindspore.nn.Cell]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为`{Cell}.{index}.*`，*表示以上三种模块级数据的命名格式，例如：`Cell.0.conv2.Conv2d.forward.0`。
+
+```json
+{
+ "task": "tensor",
+ "level": "L0",
+ "framework": "mindspore",
+ "dump_data_dir": "/dump/path",
+ "data": {
+  "Cell.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,
+     "data_name": "Cell.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,
+     "data_name": "Cell.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,
+     "data_name": "Cell.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,
+     "data_name": "Cell.conv2.Conv2d.forward.0.parameters.bias.npy"
+    }
+   }
+  },
+  "Cell.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,
+     "data_name": "Cell.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,
+     "data_name": "Cell.conv2.Conv2d.parameters_grad.bias.npy"
+    }
+   ]
+  },
+  "Cell.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,
+     "data_name": "Cell.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,
+     "data_name": "Cell.conv2.Conv2d.backward.0.output.0.npy"
+    }
+   ]
+  }
+ }
+}
+```
+
+### 2.2 L1级别
+L1级别的dump.json文件包括API的前反向的输入输出，以MindSpore的relu函数为例，网络中API调用代码为:  
+ `output = mindspore.ops.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": "mindspore",
+ "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,
+     "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,
+     "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,
+     "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,
+     "data_name": "Functional.relu.0.backward.output.0.npy"
+    }
+   ]
+  }
+ }
+}  
+```  
+
+### 2.3 mix级别
+mix级别的dump.json文件同时包括L0和L1级别的dump数据，文件格式与上述示例相同。

msprobe/docs/28.debugger_save_instruction.md

@@ -0,0 +1,94 @@
+# 单点保存工具 README
+
+## 简介
+L0, L1, mix dump存在盲区，网络中的非api/module的输入输出不会被批量dump下来。单点保存提供类似np.save和print的功能和使用体验，可以保存指定的变量。同时针对大模型场景进行了增强，具备以下特性：
+- 可保存变量的反向梯度结果。
+- 能直接保存嵌套结构数据（如 list、dict），无需手动遍历。
+- 自动分 rank 保存。
+- 多次调用时会自动计数。
+- 可配置保存统计值或者张量。
+
+## 支持场景
+仅支持 PyTorch 与 MindSpore 的动态图场景。
+
+## 使能方式
+
+### 配置文件说明
+
+通用配置：
+
+| 参数     | 解释                                       | 是否必选 |
+| -------- |-------------------------------------------| -------- |
+| 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-通用配置)  | 否       |
+
+"statistics" 任务子配置项：
+| 参数     | 解释                                       | 是否必选 |
+| -------- |-------------------------------------------| -------- |
+| summary_mode     | 控制 dump 文件输出的模式，str 类型。支持传入"statistics", "md5"。 细节详见[statistics任务子配置项说明](./02.config_introduction.md#12-task-配置为-statistics)    |  否     |
+
+"tensor" 任务无子配置项。
+
+### 接口调用说明
+
+调用PrecisionDebugger.save，传入需要保存的变量，指定变量名称以及是否需要保存反向数据。接口入参说明详见[pytorch单点保存接口](./05.data_dump_PyTorch.md#19-save)，[mindspore单点保存接口](./06.data_dump_MindSpore.md#615-save)
+
+### 实例（以pytorch场景为例）
+
+配置文件
+```json
+{
+    "task": "statistics",
+    "dump_path": "./dump_path",
+    "rank": [],
+    "level": "debug",
+    "statistics": {
+        "summary_mode": "statistics"
+    }
+}
+```
+
+初始化
+```python
+# 训练启动py脚本
+from mindspore.pytorch import PrecisionDebugger
+debugger = PrecisionDebugger("./config.json")
+for data, label in data_loader:
+    # 执行模型训练
+    train(data, label)
+
+```
+
+初始化（无配置文件）
+```python
+# 训练启动py脚本
+from mindspore.pytorch import PrecisionDebugger
+debugger = PrecisionDebugger(dump_path="dump_path", level="debug")
+for data, label in data_loader:
+    # 执行模型训练
+    train(data, label)
+
+```
+
+调用保存接口
+```python
+# 训练过程中被调用py文件
+from mindspore.pytorch import PrecisionDebugger
+dict_variable = {"key1": "value1", "key2": [1, 2]}
+PrecisionDebugger.save(dict_variable, "dict_variable", save_backward=False)
+
+```
+
+## 输出结果
+  * **"task" 配置为 "statistics" 场景** ：在 dump 目录下会生成包含变量统计值信息的 `debug.json` 文件。
+  * **"task" 配置为 "tensor" 场景** ：除了在 dump 目录下生成包含变量统计值信息的 `debug.json` 文件外，还会在 dump 子目录 `dump_tensor_data` 中保存张量二进制文件，文件名称格式为 `{variable_name}{grad_flag}.{count}.tensor.{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"
+
+