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

msprobe/docs/25.tool_function_introduction.md

@@ -0,0 +1,29 @@
+# msprobe 工具功能模块简介、适用场景和当前版本局限性
+
+## 1 PyTorch框架
+
+| 功能名（英文）                                                                            | 简介                                                            | 适用场景/优势                                                                  | 当前版本局限性                                                                                                         |
+|------------------------------------------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
+| [数据采集<br>（dump）](./05.data_dump_PyTorch.md)                                        | 采集模型训练过程中的API或Module层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。      | 1、将模型中训练的API或Module的前反向输入输出数据保存下来分析<br> 2、模型出现溢出时，可用于查看哪些API或Module出现了溢出 | 1、API级数据采集仅支持白名单列表上的API<br>2、工具会做一些同步操作，引入工具可能会导致一些同步问题消失<br>3、当前对inplace操作API或Module的支持度有限<br>4、暂不支持参数及参数梯度的采集 |
+| [离线预检<br>（api_accuracy_checker）](./07.accuracy_checker_PyTorch.md)                 | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。 | 1、对模型中所有的API做精度初步排查<br>2、精度排查不受模型累计误差影响                                  | 1、依赖GPU环境<br>2、不支持通信算子<br>3、仅支持部分融合算子                                                                           | 
+| [整网比对<br>（compare）](./10.accuracy_compare_PyTorch.md)                              | 计算模型整网NPU和标杆设备的精度误差指标，标记精度异常API或Module，助力快速定位精度问题根因。          | 1、整网比对定位精度可疑算子                                                           | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                            | 
+| [在线预检<br>（online_api_accuracy_checker）](./08.accuracy_checker_online_PyTorch.md)   | 通过TCP通信或共享存储空间的方式，进行在线精度预检，解决离线预检大数据量落盘、传输困难痛点。               | 1、使用离线预检，数据量较大落盘困难或传输耗时长时，可通过在线预检进行精度排查                                  | 1、依赖GPU环境，NPU和GPU能够通信<br>2、重计算模式下，不支持反向aten算子预检                                                                 | 
+| [溢出检查<br>（overflow_checker）](./12.overflow_check_PyTorch.md)                       | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                         | 1、当模型出现溢出时，用于快速定位最先溢出的API或Module<br>2、相比数据采集，性能更优，磁盘压力更小                 | 1、局限性同数据采集                                                                                                      | 
+| [数据解析<br>（parse_tool）](./14.data_parse_PyTorch.md)                                 | 互交式界面处理解析kernel层级dump数据，便于查看分析。                               | 1、比对kernel层级dump数据的一致性                                                   | 1、仅限于NPU                                                                                                        | 
+| [无标杆比对<br>（free_benchmark）](./15.free_benchmarking_PyTorch.md)                     | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。            | 1、无标杆数据场景下的算子精度排查<br>2、对个别算子进行升精度、“to cpu”等操作，以验证其对模型loss的影响             | 1、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用<br>2、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用        |
+| [梯度状态监测<br>（grad_probe）](./17.grad_probe.md)                                       | 可导出模型权重梯度数据并对比相似度，助力确认训练过程精度问题step和反向中的异常。                    | 1、需要分析梯度数据时<br>2、需要定位发生问题的step时                                          | 暂无                                                                                                              | 
+| [在线精度比对<br>（online_dispatch）](./18.online_dispatch.md)                             | 训练过程中直接完成NPU和CPU的精度比对并输出比对结果。                                 | 1、执行一次就可获取NPU和CPU分别执行后的精度比对结果                                            | 暂无                                                                                                              |
+| [训练状态监控<br>（monitor）](./19.monitor.md)                                             | 收集模型训练过程中的激活值、梯度和优化器状态，助力分析计算、通信、优化器各部分异常情况。                  | 1、通过监控模块级统计量指标，快速定位异常模块位置，如loss出现nan                                     | 1、仅支持模块级别统计量指标分析<br>2、仅支持megatron、deepspeed框架<br>3、少量增加时间和显存膨胀                                                  |
+| [可视化比对<br>（visualization） ](./21.visualization_PyTorch.md)                         | 解析dump的精度数据，还原模型图结构，比对各层级精度数据，助力理解模型结构、分析精度问题。                | 1、整网精度比对定位可疑算子，通过浏览器展示比对结果，支持快速搜索到可疑算子<br>2、支持查看模型层级结果，比对模型层级结构差异        | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                            |
+| [单API自动生成脚本<br>（generate_operator） ](./23.generate_operator_PyTorch.md)                         | 解析dump的精度数据，提取可疑的API算子，自动生成单API复现脚本，并根据不同的API采用不同的比对算法，给定最终比对结果数据；帮助开发者分析算子精度问题。                | 1、该工具支持从整网dump下来的数据中提取可疑算子，并自动生成单API脚本<br>2、除了支持复现单API的前反向过程，同时会根据不同的API选择不同的比对方法，并给出比对结果                 |1、不支持通信算子<br>2、融合算子需手动修改脚本进行适配<br>3、目前比对的标杆均为和CPU进行比对，暂不支持直接NPU和GPU比对
+
+## 2 MindSpore框架
+
+| 功能名（英文）                                                              | 简介                                                                | 适用场景/优势                                                                      | 当前版本局限性                                                                                                                                           |
+|----------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| [数据采集<br>（dump）](./06.data_dump_MindSpore.md)                        | 采集模型训练过程中的API或Cell层级的前反向输入输出数据，包括层次关系、统计值信息、真实数据和调用栈等。            | 1、将模型中训练的API或Cell的前反向输入输出数据保存下来分析<br> 2、模型出现溢出时，可用于查看哪些API或Cell出现了溢出         | 1、API级数据采集仅支持白名单列表上的API<br>2、当前对inplace操作API或Cell的支持度有限<br>3、暂不支持参数及参数梯度的采集                                                                       |
+| [离线预检<br>（api_accuracy_checker）](./09.accuracy_checker_MindSpore.md) | 为网络中每个API创建用例，检验其精度，并根据不同比对算法综合判定API在NPU上的精度是否达标，快速找出精度差异API。     | 1、对模型中所有的API做精度初步排查<br>2、精度排查不受模型累计误差影响                                      | 1、仅针对MindSpore.mint API                                                                                                                           |
+| [整网比对<br>（compare）](./11.accuracy_compare_MindSpore.md)              | NPU精度数据与标杆数据的比对，支持MindSpore框架内和与PyTorch跨框架的比对，助力快速定位精度异常API或Cell。 | 1、MindSpore同框架静态图比对<br>2、MindSpore同框架动态图比对<br>3、MindSpore vs PyTorch跨框架动态图比对 | 1、部分PyTorch的API关联不到MindSpore，需要手动配置映射关系                                                                                                           |
+| [溢出检查<br>（overflow_checker）](./13.overflow_check_MindSpore.md)       | 检测模型计算过程的输入输出，并在溢出时落盘数据，助力用户快速定位溢出位置。                             | 1、当模型出现溢出时，可用于定位最先溢出的API或Cell或kernel<br>2、相比数据采集，性能更优，磁盘压力更小                 | 1、除具有与数据采集功能相同的局限性外，动态图场景下，不支持 Primitive 和 Jit 类 API 的检测<br>2、动态图场景下，仅支持检测API或Cell级别溢出<br>3、静态图场景下，仅支持检测kernel级别溢出                                |
+| [无标杆比对<br>（free_benchmark）](./16.free_benchmarking_MindSpore.md)     | 不依赖标杆数据，通过对算子输入增加微小扰动，计算扰动后输出与原始输出的相对误差，识别有精度风险算子。                | 1、无标杆数据场景下的算子精度排查<br>2、对个别算子进行升精度修复，验证其对模型loss的影响                            | 1、仅支持动态图场景<br>2、由于需要拷贝输入进行二次执行，所以在遇到大张量的输入时容易发生显存OOM的问题, 特别是反向比对过程。建议结合白名单使用<br>3、比对会延长训练时间，整网比对可能会造成严重的耗时膨胀，建议结合白名单使用<br>4、不支持“to cpu”操作，不支持预热功能 |
+| [可视化比对<br>（visualization） ](./22.visualization_MindSpore.md)         | 解析dump的精度数据，还原模型图结构，比对各层级精度数据，助力理解模型结构、分析精度问题。                    | 1、整网精度比对定位可疑算子，通过浏览器展示比对结果，支持快速搜索到可疑算子<br>2、支持查看模型层级结果，比对模型层级结构差异            | 1、由于使用整网dump数据，定位的可疑算子受累计误差影响<br>2、当模型规模较大时，比对所需时间较长                                                                                              |

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,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

@@ -10,6 +10,32 @@
    - 输入参数或输出参数类型当前工具不支持，会有日志打印提醒。
    - 输入或者输出tensor的dtype为bool时，Mean和Norm等字段为null。
 
+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）？
@@ -180,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      | 八卡基线    |