mindstudio-probe 1.0.1__py3-none-any.whl → 1.0.4__py3-none-any.whl

msprobe/docs/03.config_examples.md

@@ -0,0 +1,247 @@
+# config.json 配置示例
+
+以下示例包含当前支持的所有场景可配置的完整参数。
+
+## 1 PyTorch 场景
+
+### 1.1 task 配置为 statistics
+
+```json
+{
+    "task": "statistics",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+    "seed": 1234,
+    "is_deterministic": false,
+    "enable_dataloader": false,
+
+    "statistics": {
+        "scope": [], 
+        "list": [],
+        "data_mode": ["all"],
+        "summary_mode": "statistics"
+    }
+}
+```
+
+### 1.2 task 配置为 tensor
+
+```json
+{
+    "task": "tensor",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+    "seed": 1234,
+    "is_deterministic": false,
+    "enable_dataloader": false,
+
+    "tensor": {
+        "scope": [],
+        "list":[],
+        "data_mode": ["all"],
+        "backward_input": ""
+    }
+}
+```
+
+### 1.3 task 配置为 run_ut
+
+```json
+{
+    "task": "run_ut",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+    "seed": 1234,
+    "is_deterministic": false,
+    "enable_dataloader": false,
+
+    "run_ut": {
+        "white_list": [],
+        "black_list": [],
+        "error_data_path": "./"
+    }
+}
+```
+
+### 1.4 task 配置为 overflow_check
+
+```json
+{
+    "task": "overflow_check",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+    "seed": 1234,
+    "is_deterministic": false,
+    "enable_dataloader": false,
+
+    "overflow_check": {
+        "overflow_nums": 1
+    }
+}
+```
+
+### 1.5 task 配置为 free_benchmark
+
+```json
+{
+    "task": "free_benchmark",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+    "seed": 1234,
+    "is_deterministic": false,
+    "enable_dataloader": false,
+
+    "free_benchmark": {
+        "scope": [], 
+        "list": ["conv2d"],
+        "fuzz_device": "npu",
+        "pert_mode": "improve_precision",
+        "handler_type": "check",
+        "fuzz_level": "L1",
+        "fuzz_stage": "forward",
+        "if_preheat": false,
+        "preheat_step": 15,
+        "max_sample": 20
+    }
+}
+```
+
+## 2 MindSpore 静态图场景 
+
+### 2.1 task 配置为 statistics
+
+```json
+{
+    "task": "statistics",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L2",
+
+    "statistics": {
+        "list": [],
+        "data_mode": ["all"],
+        "summary_mode": "statistics"
+    }
+}
+```
+
+### 2.2 task 配置为 tensor
+
+```json
+{
+    "task": "tensor",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L2",
+
+    "tensor": {
+        "list":[],
+        "data_mode": ["all"],
+        "backward_input": ""
+    }
+}
+```
+
+### 2.3 task 配置为 overflow_check
+
+```json
+{
+    "task": "overflow_check",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L2",
+
+    "overflow_check": {
+        "check_mode": "all"
+    }
+}
+```
+
+## 3 MindSpore 动态图场景
+
+### 3.1 task 配置为 statistics
+
+```json
+{
+    "task": "statistics",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+
+    "statistics": {
+        "scope": [], 
+        "list": [],
+        "data_mode": ["all"],
+        "summary_mode": "statistics"
+    }
+}
+```
+
+### 3.2 task 配置为 tensor
+
+```json
+{
+    "task": "tensor",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+
+    "tensor": {
+        "scope": [],
+        "list":[],
+        "data_mode": ["all"]
+    }
+}
+```
+
+### 3.3 task 配置为 overflow_check
+
+```json
+{
+    "task": "overflow_check",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+
+    "overflow_check": {
+        "overflow_nums": 1
+    }
+}
+```
+
+### 3.4 task 配置为 free_benchmark
+
+```json
+{
+    "task": "free_benchmark",
+    "dump_path": "/home/data_dump",
+    "rank": [],
+    "step": [],
+    "level": "L1",
+
+    "free_benchmark": {
+        "list": ["mindspore.ops.add"],
+        "fuzz_device": "npu",
+        "pert_mode": "improve_precision",
+        "handler_type": "check",
+        "fuzz_level": "L1",
+        "fuzz_stage": "forward"
+    }
+}
+```

msprobe/docs/04.acl_config_examples.md

@@ -0,0 +1,76 @@
+# acl_config.json 配置文件说明
+
+当 PyTorch 场景 level 取"L2"时，须配置 acl_config 参数，并指定 acl_config.json 文件（用于指定 L2 kernel 级 dump 的配置），此时 **config.json** 文件配置示例如下：
+
+## 1 前向 kernel dump 配置示例
+
+"scope"配置为前向 API 名称，仅支持配置一个 API。
+
+```json
+{
+	"task": "tensor",
+	"dump_path": "/home/data_dump",
+	"level": "L2",
+	"rank": [0],
+	"step": [0],
+	"is_deterministic": false,
+	"tensor": {
+		"scope": ["Tensor.__mul__.10.forward"],
+		"list":[],
+		"data_mode": ["all"],
+		"backward_input": [""],
+		"file_format": "npy"
+		},
+	"acl_config": "acl_config.json"
+}
+```
+
+## 2 反向 kernel dump 配置示例
+
+执行反向 kernel dump 前需要先使用工具 dump 该 API 的反向输入，保存 pt 文件，"backward_input"参数中传入该 pt 文件路径。
+
+"scope"配置为反向API名称，仅支持配置一个API。
+
+```json
+{
+	"task": "tensor",
+	"dump_path": "/home/data_dump",
+	"level": "L2",
+	"rank": [0],
+	"step": [0],
+	"is_deterministic": false,
+	"tensor": {
+		"scope": ["Tensor.__mul__.10.backward"],
+		"list":[],
+		"data_mode": ["all"],
+		"backward_input": ["Tensor.__mul__.10.backward.input.0.pt"],
+		"file_format": "npy"
+		},
+	"acl_config": "acl_config.json"
+}
+```
+
+## 3 acl_config.json 配置示例
+
+该文件须自行创建，配置示例如下：
+
+```json
+{
+ "dump":
+ {
+	"dump_list":[],
+	"dump_path":"./dump/output",
+	"dump_mode":"all",
+	"dump_op_switch":"on"
+ }
+}
+```
+
+**acl_config.json 参数说明**
+
+| 字段名         | 解释                                                         |
+| -------------- | ------------------------------------------------------------ |
+| dump_list      | 待 dump 数据的 API 模型。为空，无需配置。                        |
+| dump_path      | dump 数据文件存储到运行环境的目录，主要配置的是 kernel 级数据的存放路径。支持配置绝对路径或相对路径。dump_path 须为已存在目录。 |
+| dump_mode      | dump 数据模式，可取值，<br/> output：dump API 的输出数据，默认值；<br/> input：dump API 的输入数据；<br/> all：dump API 的输入、输出数据。 |
+| dump_op_switch | 单 API 模型 dump 数据开关，可取值，<br>        off：关闭单API模型dump，默认值；<br>        on：开启单API模型dump。 |

msprobe/docs/05.data_dump_PyTorch.md

@@ -0,0 +1,198 @@
+# PyTorch 场景的精度数据采集
+
+msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。
+
+本工具提供固定的 API 支持列表，若需要删除或增加 dump 的 API，可以在 msprobe/pytorch/hook_module/support_wrap_ops.yaml 文件内手动修改，如下示例：
+
+```yaml
+functional:  # functional为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API
+  - conv1d
+  - conv2d
+  - conv3d
+```
+
+## 1 接口介绍
+
+### 1.1 PrecisionDebugger
+
+**功能说明**：通过加载 dump 配置文件的方式来确定 dump 操作的详细配置。
+
+**原型**：
+
+```Python
+PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, model=None, step=None)
+```
+
+1. config_path：指定 dump 配置文件路径；model：指定具体的 torch.nn.Module，默认未配置，level 配置为"L0"或"mix"时必须配置该参数。其他参数均在 [config.json](../config.json) 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。
+2. 此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。
+
+### 1.2 start
+
+**功能说明**：启动精度数据采集。在模型初始化之后的位置添加。需要与 stop 函数一起添加在 for 循环内。
+
+**原型**：
+
+```Python
+debugger.start()
+```
+
+### 1.3 stop
+
+**功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。若需要 dump 反向数据，则需要添加在反向计算代码（如，loss.backward）之后。使用示例可参见 [2.1 采集 model 的精度数据](#21-采集-model-的精度数据)和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
+
+**原型**：
+
+```Python
+debugger.stop()
+```
+
+### 1.4 forward_backward_dump_end
+
+**功能说明**：停止精度数据采集。用于 dump 指定代码的前反向数据。在 **start** 函数之后，反向计算代码（如，loss.backward）之前的任意位置添加，可以采集 **start** 函数和该函数之间的前反向数据，可以通过调整 **start** 函数与该函数的位置，来指定需要 dump 的代码块。要求 **stop** 函数添加在反向计算代码（如，loss.backward）之后，此时该函数与 **stop** 函数之间的代码不会被 dump。使用示例可参见 [2.3 采集指定代码块的前反向数据](#23-采集指定代码块的前反向数据)
+
+**原型**：
+
+```Python
+forward_backward_dump_end()
+```
+
+### 1.5 step
+
+**功能说明**：更新 dump 参数。在最后一个 **stop** 函数后或一个 step 结束的位置添加。需要与 **start** 函数一起添加在 for 循环内。
+
+**原型**：
+
+```Python
+debugger.step()
+```
+
+## 2 示例代码
+
+### 2.1 采集 model 的精度数据
+
+这个示例定义了一个 nn.Module 类型的简单网络，在进行数据采集时使用原型函数 PrecisionDebugger 传入 config_path 参数和 model 参数。
+
+```python
+# 根据需要import包
+import torch
+import torch.nn as nn
+import torch_npu  # 需安装 torch_npu
+import torch.nn.functional as F
+from msprobe.pytorch import PrecisionDebugger
+
+
+torch.npu.set_device("npu:0")
+# 定义网络
+class ModuleOP(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.linear_1 = nn.Linear(in_features=8,out_features=4)
+        self.linear_2 = nn.Linear(in_features=4,out_features=2)
+
+    def forward(self,x):
+        x1 = self.linear_1(x)
+        x2 = self.linear_2(x1)
+        r1 = F.relu(x2)
+        return r1
+
+if __name__ == "__main__":
+	module = ModuleOP()
+	# 注册工具
+	debugger = PrecisionDebugger('./config.json', model=module)
+	debugger.start()
+	x = torch.randn(10,8)
+	out = module(x)
+	loss = out.sum()
+	loss.backward()
+	debugger.stop()
+
+```
+### 2.2 采集完整的前反向数据
+
+```Python
+from msprobe.pytorch import PrecisionDebugger
+
+# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
+debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
+# 模型、损失函数的定义及初始化等操作
+# ...
+# 数据集迭代的位置一般为模型训练开始的位置
+for data, label in data_loader:
+	debugger.start() # 开启数据dump
+	# 如下是模型每个step执行的逻辑
+    output = model(data)
+    #...
+    loss.backward()
+	debugger.stop() # 关闭数据dump
+	debugger.step() # 结束一个step的dump
+```
+
+### 2.3 采集指定代码块的前反向数据
+
+```Python
+from msprobe.pytorch import PrecisionDebugger
+
+# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
+debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
+
+# 模型、损失函数的定义及初始化等操作
+# ...
+# 数据集迭代的位置一般为模型训练开始的位置
+for data, label in data_loader:
+	debugger.start() # 开启数据dump
+	# 如下是模型每个step执行的逻辑
+    output = model(data)
+    debugger.forward_backward_dump_end() # 插入该函数到start函数之后，只dump start函数到该函数之间代码的前反向数据，本函数到stop函数之间的数据则不dump
+    #...
+    loss.backward()
+	debugger.stop() # 关闭数据dump
+	debugger.step() # 结束一个step的dump
+```
+
+
+
+## 3 dump 结果文件介绍
+
+训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。目录结构示例如下：
+
+```Python
+├── dump_path
+│   ├── step0
+│   |   ├── rank0
+│   |   │   ├── dump_tensor_data
+|   |   |   |    ├── Tensor.permute.1.forward.pt
+|   |   |   |    ├── MyModule.0.forward.input.pt        # 开启模块级精度数据dump时存在模块级的dump数据文件
+|   |   |   |    ...
+|   |   |   |    └── Fcuntion.linear.5.backward.output.pt
+│   |   |   ├── dump.json        # 保存前反向算子、算子的统计量信息或溢出算子信息。包含dump数据的API名称（命名格式为：`{api_type}_{api_name}_{API调用次数}_{前向反向}_{input/output}.{参数序号}`）、dtype、 shape、各数据的max、min、mean、L2norm统计信息以及当配置summary_mode="md5"时的md5数据。其中，“参数序号”表示该API下的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个子参数；L2norm表示L2范数（平方根）
+│   |   |   ├── stack.json        # 算子调用栈信息
+│   |   |   └── construct.json        # 分层分级结构
+│   |   ├── rank1
+|   |   |   ├── dump_tensor_data
+|   |   |   |   └── ...
+│   |   |   ├── dump.json
+│   |   |   ├── stack.json
+|   |   |   └── construct.json
+│   |   ├── ...
+│   |   |
+|   |   └── rank7
+│   ├── step1
+│   |   ├── ...
+│   ├── step2
+```
+
+dump 过程中，pt 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。
+
+其中 rank 为设备上各卡的 ID，每张卡上 dump 的数据会生成对应 dump 目录。非分布式场景下没有rank ID，目录名称为rank。
+
+pt 文件保存的前缀和 PyTorch 对应关系如下：
+
+| 前缀        | Torch模块           |
+| ----------- | ------------------- |
+| Tensor      | torch.Tensor        |
+| Torch       | torch               |
+| Functional  | torch.nn.functional |
+| NPU         | NPU亲和算子         |
+| VF          | torch._VF           |
+| Aten        | torch.ops.aten      |
+| Distributed | torch.distributed   |