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

msprobe/docs/27.dump_json_instruction.md

@@ -0,0 +1,521 @@
+# dump.json文件说明及示例  
+
+## 1. dump.json文件介绍（Pytorch）  
+
+### 1.1 L0级别
+L0级别的dump.json文件包括模块的前反向的输入输出，以及模块的参数和参数梯度。以Pytorch的Conv2d模块为例，网络中模块调用代码为:  
+`output = torch.nn.Conv2d(64, 128, 5, padding=2, bias=True)(input)`  
+
+dump.json文件中包含以下字段：  
+
+1. `Module.conv2.Conv2d.forward.0`为模块的前向数据，其中input_args为模块的输入数据（位置参数），input_kwargs为模块的输入数据（关键字参数），output为模块的输出数据，parameters为模块的参数数据，包括权重（weight）和偏置（bias）。  
+2. `Module.conv2.Conv2d.parameters_grad`为模块的参数梯度数据，包括权重（weight）和偏置（bias）的梯度。  
+3. `Module.conv2.Conv2d.backward.0`为模块的反向数据，其中input为模块反向的输入梯度（对应前向输出的梯度），output为模块的反向输出梯度（对应前向输入的梯度）。
+
+```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文件中包含以下字段：  
+1. `Functional.relu.0.forward`为API的前向数据，其中input_args为API的输入数据（位置参数），input_kwargs为API的输入数据（关键字参数），output为API的输出数据。  
+2. `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 = mindspore.nn.Conv2d(64, 128, 5, pad_mode='same', has_bias=True)(input)`  
+
+dump.json文件中包含以下字段：  
+1. `Cell.conv2.Conv2d.forward.0`为模块的前向数据，其中input_args为模块的输入数据（位置参数），input_kwargs为模块的输入数据（关键字参数），output为模块的输出数据，parameters为模块的参数数据，包括权重（weight）和偏置（bias）。  
+2. `Cell.conv2.Conv2d.parameters_grad`为模块的参数梯度数据，包括权重（weight）和偏置（bias）的梯度。  
+3. `Cell.conv2.Conv2d.backward.0`为模块的反向数据，其中input为模块反向的输入梯度（对应前向输出的梯度），output为模块的反向输出梯度（对应前向输入的梯度）。
+
+```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文件中包含以下字段：  
+1. `Functional.relu.0.forward`为API的前向数据，其中input_args为API的输入数据（位置参数），input_kwargs为API的输入数据（关键字参数），output为API的输出数据。  
+2. `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/FAQ.md

@@ -13,6 +13,29 @@
 2. 如果存在namedtuple类型的数据作为nn.Module的输出，工具会将各字段数据dump下来，但是输出数据类型会被转成tuple，原因是什么？
    - 这是由于pytorch框架自身，在注册module的backward hook时，会将namedtuple类型转成tuple类型。
 
+3. 如果某个api在dump支持列表support_wrap_ops.yaml中，但没有dump该api的数据，原因是什么？
+   - 首先确认api调用是否在采集范围内，即需要在 **start** 和 **stop** 接口涵盖的范围内。
+   - 其次，由于工具只在被调用时才对api进行patch，从而使得数据可以被dump下来。因此当api是被直接import进行调用时，由于该api的地址已经确定，
+   工具无法再对其进行patch，故而该api数据无法被dump下来。如下示例，relu将无法被dump：
+   ```python
+   import torch
+   from torch import relu  # 此时relu地址已经确定，无法修改
+
+   from msprobe.pytorch import PrecisionDebugger
+
+   debugger = PrecisionDebugger(dump_path="./dump_data")
+   x = torch.randn(10)
+   debugger.start()  # 此时会对torch下面的api进行patch，但已无法对import进来的api进行patch了
+   x = relu(x)          
+   debugger.stop()
+   ```
+   在上述场景中，若希望采集relu数据，只需要将`relu(x)`修改为`torch.relu(x)`即可。
+
+4. 在使用L0 dump时，发现有些 module 的数据没有采集下来，原因是什么？
+   - 确认日志打印中是否存在`The {module_name} has registered deprecated register_backward_hook`信息，
+     该信息说明 module 挂载了被 PyTorch 框架废弃的 register_backward_hook，这与工具使用的 register_full_backward_hook 接口会产生冲突，故工具会跳过该 module 的反向数据采集。
+   - 如果您希望所有 module 数据都能采集下来，可以将模型中使用的 register_backward_hook 接口改为 PyTorch 框架推荐的 register_full_backward_pre_hook 或 register_full_backward_hook 接口。
+
 # 2 精度预检(PyTorch)
 
 1. 预检工具在 dump 和 run_ut 的过程中，是否需要同时开启或关闭 jit 编译（jit_compile）？
@@ -183,9 +206,10 @@ def npu_forward_fused_softmax(self, input_, mask):
 
     答：注释工具目录 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中 `Tensor: ` 下的 `- __getitem__`，工具会跳过采集该 API。如果是需要采集关键位置 API 也可以考虑根据报错堆栈信息注释引发报错的类型检查。
 
-11. 添加 msprobe 工具后 F.gelu 触发 ValueError 报错：`activation_func must be F.gelu` 等。以及采集 Megatron 数据时报错：`ValueError(Only support fusion of gelu and swiglu)`。
+11. 使用 msprobe 工具数据采集功能后，模型出现报错，报错信息为：`activation_func must be F.gelu` 或 `ValueError(Only support fusion of gelu and swiglu)`。
 
-    答：这一类问题是因为工具本身封装了 torch 算子，所以校验算子名时会报错。注释 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中的 `-gelu` 或者 `-silu`，工具会跳过采集该 API。如果需要采集关键位置 API 也可以考虑根据报错堆栈信息注释引发报错的类型检查。
+    答：这一类报错常见于 Megatron/MindSpeed/ModelLink 等加速库或模型仓中，原因是工具本身会封装 torch 的 API（API类型和地址会发生改变），而有些 API 在工具使能前类型和地址就已经确定，此时工具无法对这类 API 再进行封装，而加速库中会对某些 API 进行类型检查，即会把工具无法封装的原始的 API和工具封装之后的 API 进行判断，所以会报错。
+    规避方式有3种：①将PrecisionDebugger的实例化放在文件的开始位置，即导包后的位置，确保所有API都被封装；②注释 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中的 `-gelu` 或者 `-silu`，工具会跳过采集该 API。③ 可以考虑根据报错堆栈信息注释引发报错的类型检查。
 
 12. 添加 msprobe 工具后触发与 AsStrided 算子相关、或者编译相关的报错，如：`Failed to compile Op [AsStrided]`。
 

msprobe/docs/accuracy_checker_MindSpore/accuracy_checker_MindSpore_baseline.md

@@ -0,0 +1,14 @@
+# MindSpore 场景的精度预检基线
+
+## "multi_run_ut"模式精度预检耗时参考基线
+
+该基线为MindSpore框架下，使用"multi_run_ut"模式精度预检耗时参考基线。本基线测试了38B语言大模型在不同卡数下耗时的变化。
+
+### 38B语言大模型
+
+| 卡数  | 总耗时 (分钟) | 备注       |
+| ----- |----------|---------- |
+| 1 卡  | 21.0     | 单卡基线    |
+| 2 卡  | 11.5     | 双卡基线    |
+| 4 卡  | 6.7      | 四卡基线    |
+| 8 卡  | 3.5      | 八卡基线    |

msprobe/docs/data_dump_MindSpore/data_dump_MindSpore_baseline.md

@@ -0,0 +1,22 @@
+# MindSpore 场景的精度数据采集基线
+
+## "tensor"模式采集数据量参考基线
+
+该基线为MindSpore框架下，使用"tensor"模式采集数据量参考基线。本基线测试了38B语言大模型在不同采集模式下，不同global_batch_size下，单卡和8卡下，数据量的变化。
+
+### 38B语言大模型
+
+<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>262GB</td><td>2.1T</td></tr>
+    <tr><td>2</td><td>480GB</td><td>3.8T</td></tr>
+    <tr><td>3</td><td>928GB</td><td>7.4T</td></tr>
+    </td><td rowspan="3">L1</td><td>1</td><td>2.1TB</td><td>17.1TB</td></tr>
+    <tr><td>2</td><td>2.8T</td><td>22.7TB</td></tr>
+    <tr><td>3</td><td>4.2T</td><td>34.3TB</td></tr>
+    </td><td rowspan="3">mix</td><td>1</td><td>2.4T</td><td>19.2TB</td></tr>
+    <tr><td>2</td><td>3.3TB</td><td>26.6TB</td></tr>
+    <tr><td>3</td><td>5.1TB</td><td>41.4TB</td></tr>
+
+</table>
+