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

msprobe/docs/05.data_dump_PyTorch.md

@@ -2,7 +2,7 @@
 
 msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。
 
-dump的'tensor'模式采集数据量大小，可以参考[数据量基线](./26.data_dump_PyTorch_baseline.md)。
+dump "statistics"模式的性能膨胀大小"与"tensor"模式采集的数据量大小，可以参考[dump基线](./26.data_dump_PyTorch_baseline.md)。
 
 本工具提供固定的 API 支持列表，若需要删除或增加 dump 的 API，可以在 msprobe/pytorch/hook_module/support_wrap_ops.yaml 文件内手动修改，如下示例：
 
@@ -15,6 +15,52 @@ functional:  # functional为算子类别，找到对应的类别，在该类别
 
 删除API的场景：部分模型代码逻辑会存在API原生类型校验，工具执行dump操作时，对模型的API封装可能与模型的原生API类型不一致，此时可能引发校验失败，详见《[FAQ](FAQ.md)》中“异常情况”的第10和11条。
 
+## 快速上手
+
+这个示例定义了一个 nn.Module 类型的简单网络，使用原型函数 PrecisionDebugger 进行数据采集。
+
+```python
+# 根据需要import包
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+# 导入工具的数据采集接口
+from msprobe.pytorch import PrecisionDebugger, seed_all
+
+# 在模型训练开始前固定随机性
+seed_all()
+
+# 在模型训练开始前实例化PrecisionDebugger
+debugger = PrecisionDebugger()
+
+# 定义网络
+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()
+    
+    # 开启数据 dump
+    debugger.start(model=module)
+    x = torch.randn(10, 8)
+    out = module(x)
+    loss = out.sum()
+    loss.backward()
+
+    # 关闭数据 dump
+    debugger.stop()
+```
+
 ## 1 接口介绍
 
 ### 1.1 PrecisionDebugger
@@ -30,9 +76,11 @@ PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, model
 1. config_path：指定 dump 配置文件路径；
 2. model：指定需要采集 Module 级数据的模型，支持传入 torch.nn.Module 或 list[torch.nn.Module] 类型，默认未配置。
 level 配置为"L0"或"mix"时，必须在该接口或 **start** 接口中配置该参数。该参数在将来会从该接口移除，建议在 **start** 接口中配置该参数。
-3. 其他参数均在 [config.json](../config.json) 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。
+3. 其他参数均在 config.json 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。
 
-此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。
+此接口的参数均不是必要（均不配置的情况下默认采集所有 rank 和 step 的 L1 级别的统计数据），且优先级高于 config.json 文件中的配置，但可配置的参数相比 config.json 较少。
+
+注：此接口的初始化需与采集目标在同一个进程中，否则将无法采集目标数据。
 
 ### 1.2 start
 
@@ -41,12 +89,15 @@ level 配置为"L0"或"mix"时，必须在该接口或 **start** 接口中配置
 **原型**：
 
 ```Python
-debugger.start(model=None)
+debugger.start(model=None, token_range=None)
 ```
 
 1. model：指定需要采集 Module 级数据的模型，支持传入 torch.nn.Module、list[torch.nn.Module]或Tuple[torch.nn.Module] 类型，默认未配置。
-level 配置为"L0"或"mix"时，必须在该接口或 **PrecisionDebugger** 接口中配置该参数。
+level 配置为"L0"|"mix"或token_range不为None时，必须在该接口或 **PrecisionDebugger** 接口中配置该参数。
 本接口中的 model 比 PrecisionDebugger 中 model 参数优先级更高，会覆盖 PrecisionDebugger 中的 model 参数。
+<br>对于复杂模型，如果仅需要监控一部分(如model.A，model.A extends torch.nn.Module)，传入需要监控的部分(如model.A)即可。  
+注意：传入的当前层不会被dump，工具只会dump传入层的子层级。如传入了model.A，A本身不会被dump，而是会dump A.x, A.x.xx等。
+2. token_range：指定推理模型采集时的token循环始末范围，支持传入[int, int]类型，代表[start, end]，范围包含边界，默认未配置。
 
 ### 1.3 stop
 
@@ -183,58 +234,65 @@ save(variable, name, save_backward=True)
 **参数说明**:
 | 参数名称        | 参数含义          |        支持数据类型    |   是否必选|
 | ----------     | ------------------| ------------------- | ------------------- |
-| variable       | 需要保存的变量     |dict, list, torch.tensor, int, float, str |  是  |
+| variable       | 需要保存的变量     |dict, list, tuple, torch.tensor, int, float, str |  是  |
 | name           | 指定的名称         | str                 | 是  |
 | save_backward  | 是否保存反向数据   | boolean             | 否 |
 
-## 2 示例代码
+### 1.10 set_init_step
 
-### 2.1 快速上手
+**功能说明**：设置起始step数，step数默认从0开始计数，使用该接口后step从指定值开始计数。该函数需要写在训练迭代的循环开始前，不能写在循环内。
 
-这个示例定义了一个 nn.Module 类型的简单网络，在进行数据采集时使用原型函数 PrecisionDebugger 传入 config_path 参数和 model 参数。
+**原型**：
 
-```python
-# 根据需要import包
-import torch
-import torch.nn as nn
-import torch.nn.functional as F
+```Python
+debugger.set_init_step(step)
+```
 
-# 导入工具的数据采集接口
-from msprobe.pytorch import PrecisionDebugger, seed_all
+**参数说明**:
 
-# 在模型训练开始前固定随机性
-seed_all()
-# 在模型训练开始前实例化PrecisionDebugger
-debugger = PrecisionDebugger(config_path='./config.json')
+1.step: 指定的起始step数。
 
-# 定义网络
-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)
+### 1.11 register_custom_api
 
-    def forward(self, x):
-        x1 = self.linear_1(x)
-        x2 = self.linear_2(x1)
-        r1 = F.relu(x2)
-        return r1
+**功能说明**：注册用户自定义的api到工具用于 L1 dump 。
 
-if __name__ == "__main__":
-    module = ModuleOP()
-    # 开启数据 dump
-    debugger.start(model=module)
+**原型**：
 
-    x = torch.randn(10, 8)
-    out = module(x)
-    loss = out.sum()
-    loss.backward()
+```Python
+debugger.register_custom_api(module, api_name, api_prefix)
+```
+**参数说明**:
 
-    # 关闭数据 dump
-    debugger.stop()
+以 torch.matmul api 为例
+
+1.module: api 所属的包，即传入 torch。
+
+2.api_name: api 名，string类型，即传入 "matmul"。
+
+3.api_prefix: [dump.json](./27.dump_json_instruction.md) 中 api 名的前缀，可选，默认为包名的字符串格式, 即 "torch"。
+
+### 1.12 restore_custom_api
+
+**功能说明**：恢复用户原有的自定义的api，取消 dump 。
+
+**原型**：
+
+```Python
+debugger.restore_custom_api(module, api_name)
 ```
+**参数说明**:
+
+以 torch.matmul api 为例
+
+1.module: api 所属的包，即传入 torch。
+
+2.api_name: api 名，string类型，即传入 "matmul"。
 
-### 2.2 采集完整的前反向数据
+
+## 2 示例代码
+
+
+### 2.1 采集完整的前反向数据
 
 ```Python
 from msprobe.pytorch import PrecisionDebugger, seed_all
@@ -255,7 +313,7 @@ for data, label in data_loader:
     debugger.step()  # 结束一个step的dump
 ```
 
-### 2.3 采集指定代码块的前反向数据
+### 2.2 采集指定代码块的前反向数据
 
 ```Python
 from msprobe.pytorch import PrecisionDebugger, seed_all
@@ -279,7 +337,7 @@ for data, label in data_loader:
     debugger.step()  # 结束一个step的dump
 ```
 
-### 2.4 采集函数模块化数据
+### 2.3 采集函数模块化数据
 
 ```Python
 # 根据需要import包
@@ -321,6 +379,80 @@ if __name__ == "__main__":
     debugger.stop()
 ```
 
+### 2.4 跨文件采集数据
+为了确保所有API都被工具封装，PrecisionDebugger的实例化通常放在训练工程的入口位置，但有的时候，模型定义会在另一个文件中。 假设有两个文件，train.py（为训练工程入口）module.py（为模型定义文件），为了采集module.py中定义的ModuleOP模块中某些子模块或API的前反向数据，需要在train.py和module.py文件中分别导入PrecisionDebugger并进行如下配置。
+
+train.py文件：
+
+```Python
+# 根据需要import包
+import torch
+from module import ModuleOP
+
+# 导入工具的数据采集接口
+from msprobe.pytorch import PrecisionDebugger
+
+# 将PrecisionDebugger的实例化放在文件的开始位置，即导包后的位置，确保所有API都被封装
+debugger = PrecisionDebugger(config_path='./config.json')
+
+if __name__ == "__main__":
+    module = ModuleOP()
+
+    x = torch.randn(10, 8)
+    out = module(x)
+    loss = out.sum()
+    loss.backward()
+```
+
+module.py文件：
+
+```Python
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from msprobe.pytorch import PrecisionDebugger
+
+# 定义网络
+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):
+        PrecisionDebugger.start()
+        x1 = self.linear_1(x)
+        PrecisionDebugger.stop()
+        x2 = self.linear_2(x1)
+        r1 = F.relu(x2)
+        return r1
+
+```
+
+### 2.5 推理模型采集指定token_range
+
+```Python
+from vllm import LLM, SamplingParams
+from msprobe.pytorch import PrecisionDebugger, seed_all
+# 在模型训练开始前固定随机性
+seed_all()
+# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
+debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
+# 模型定义及初始化等操作
+prompts = ["Hello, my name is"]
+sampling_params = SamplingParams(temprature=0.8, top_p=0.95)
+llm = LLM(model='...')
+model = llm.llm_engine.model_executor.driver_worker.worker.model_runner.get_model()
+# 开启数据dump, 指定采集推理模型逐字符循环推理中的第1~3次
+debugger.start(model=model, token_range=[1,3])  
+# 推理模型生成的逻辑
+output = llm.generate(prompts, sampling_params=sampling_params)
+# 关闭数据dump并落盘
+debugger.stop()
+debugger.step()
+```
+
 ## 3 dump 结果文件介绍
 
 训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。目录结构示例如下：
@@ -334,8 +466,8 @@ if __name__ == "__main__":
 |   |   |   |    ├── Functional.linear.5.backward.output.pt    # 命名格式为{api_type}.{api_name}.{API调用次数}.{forward/backward}.{input/output}.{参数序号}, 其中，“参数序号”表示该API的第n个输入或输出，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个元素。
 |   |   |   |    ...
 |   |   |   |    ├── Module.conv1.Conv2d.forward.0.input.0.pt          # 命名格式为{Module}.{module_name}.{class_name}.{forward/backward}.{调用次数}.{input/output}.{参数序号}, 其中，“参数序号”表示该Module的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该Module的第1个参数的第1个元素。
-|   |   |   |    ├── Module.conv1.Conv2D.forward.0.parameters.bias.pt  # 模块参数数据：命名格式为{Module}.{module_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
-|   |   |   |    └── Module.conv1.Conv2D.parameters_grad.weight.pt     # 模块参数梯度数据：命名格式为{Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
+|   |   |   |    ├── Module.conv1.Conv2d.forward.0.parameters.bias.pt  # 模块参数数据：命名格式为{Module}.{module_name}.{class_name}.forward.{调用次数}.parameters.{parameter_name}。
+|   |   |   |    └── Module.conv1.Conv2d.parameters_grad.weight.pt     # 模块参数梯度数据：命名格式为{Module}.{module_name}.{class_name}.parameters_grad.{parameter_name}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
 |   |   |   |                                                          # 当dump时传入的model参数为List[torch.nn.Module]或Tuple[torch.nn.Module]时，模块级数据的命名中包含该模块在列表中的索引index，命名格式为{Module}.{index}.*，*表示以上三种模块级数据的命名格式，例如：Module.0.conv1.Conv2d.forward.0.input.0.pt。
 │   |   |   ├── dump.json
 │   |   |   ├── stack.json
@@ -355,7 +487,7 @@ if __name__ == "__main__":
 ```
 * `rank`：设备 ID，每张卡的数据保存在对应的 `rank{ID}` 目录下。非分布式场景下没有 rank ID，目录名称为 rank。
 * `dump_tensor_data`：保存采集到的张量数据。
-* `dump.json`： 保存API或Module前反向数据的统计量信息。包含dump数据的API名称或Module名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#1-dumpjson文件介绍pytorch)。
+* `dump.json`： 保存API或Module前反向数据的统计量信息。包含dump数据的API名称或Module名称，各数据的dtype、 shape、max、min、mean、L2norm（L2范数，平方根）统计信息以及当配置summary_mode="md5"时的CRC-32数据。具体介绍可参考[dump.json文件说明](./27.dump_json_instruction.md#1-PyTorch场景下的dump.json文件)。
 * `stack.json`：API/Module的调用栈信息。
 * `construct.json`：分层分级结构，level为L1时，construct.json内容为空。
 
@@ -366,12 +498,14 @@ dump 过程中，pt 文件在对应算子或者模块被执行后就会落盘，
 
 pt 文件保存的前缀和 PyTorch 对应关系如下：
 
-| 前缀        | Torch模块           |
-| ----------- | ------------------- |
+| 前缀          | Torch模块             |
+|-------------|---------------------|
 | Tensor      | torch.Tensor        |
 | Torch       | torch               |
 | Functional  | torch.nn.functional |
-| NPU         | NPU 亲和算子         |
+| NPU         | NPU 亲和算子            |
 | VF          | torch._VF           |
 | Aten        | torch.ops.aten      |
 | Distributed | torch.distributed   |
+| MindSpeed   | mindspeed.ops       |
+