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

msprobe/mindspore/doc/dump.md

@@ -12,7 +12,7 @@ msprobe工具主要通过在训练脚本内添加dump接口并启动训练的方
 
 通过加载dump配置文件的方式来确定dump操作的详细配置。
 
-可以在from msprobe.mindspore import PrecisionDebugger和模型初始化之间的任意位置添加该接口。
+PrecisionDebugger可以在from msprobe.mindspore import PrecisionDebugger之后的位置添加。详细使用可参考“**示例代码**”。
 
 **原型**
 
@@ -24,7 +24,7 @@ PrecisionDebugger(config_path=None)
 
 | 参数名      | 说明                                                         | 是否必选 |
 | ----------- | ------------------------------------------------------------ | -------- |
-| config_path | 指定dump配置文件路径，String类型。参数示例："./config.json"。未配置该路径时，默认使用[config.json](../../config)文件的默认配置。config.json文件可以配置更多参数，若需要进行更多场景的精度数据dump，建议配置[config.json](../../config/config.json)文件。 | 否       |
+| config_path | 指定dump配置文件路径，String类型。参数示例："./config.json"。未配置该路径时，默认使用[config.json](../../config)文件的默认配置。config.json文件可以配置更多参数，若需要进行更多场景的精度数据dump，建议配置[config.json](../../config/config.json)文件。config.json文件的配置可参考《[配置文件说明](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/config/README.md)》。 | 否       |
 
 ### start函数
 
@@ -32,16 +32,64 @@ PrecisionDebugger(config_path=None)
 
 启动函数。
 
+在模型初始化之后的位置添加。需要与stop函数一起添加在for循环内。
+
 **原型**
 
 ```Python
-debugger.start()
+debugger.start(model = None)
 ```
 
-该函数为类函数，可以使用debugger.start()也可以使用PrecisionDebugger.start()。
+该函数为类函数，可以使用debugger.start(model = None)也可以使用PrecisionDebugger.start(model = None)
+
+
+**参数说明**
+
+| 参数名      | 说明                                                                                    | 是否必选 |
+| ----------- |---------------------------------------------------------------------------------------| -------- |
+| model | 指具体的mindspore.nn.Cell，默认未配置，L1级别下传入model可以使能对primitive op的dump，否则无法dump primitive op。 | 否       |
+
+
+### stop函数
+
+**功能说明**
+
+dump停止函数。
+
+在**start**函数之后的任意位置添加。需要与start函数一起添加在for循环内。若需要dump反向数据，则需要添加在反向计算代码之后。
+
+仅MindSpore动态图场景支持。
+
+**原型**
+
+```Python
+debugger.stop()
+```
+
+该函数为类函数，可以使用debugger.stop()也可以使用PrecisionDebugger.stop()。
+
+### step函数
+
+**功能说明**
+
+结束标识。
+
+在最后一个**stop**函数后或一个step结束的位置添加。
+
+仅MindSpore动态图场景支持。
+
+**原型**
+
+```Python
+debugger.step()
+```
+
+该函数为类函数，可以使用debugger.step()也可以使用PrecisionDebugger.step()。
 
 ## 示例代码
 
+### MindSpore静态图场景
+
 ```Python
 from msprobe.mindspore import PrecisionDebugger
 debugger = PrecisionDebugger(config_path="./config.json")
@@ -51,15 +99,119 @@ debugger.start()
 ...
 ```
 
+### MindSpore动态图场景
+
+当使用模型使用for循环时，在每个迭代的开始插入debugger.start()，在每个迭代的结束插入debugger.stop()与debugger.step()：
+
+```Python
+import mindspore as ms
+from msprobe.mindspore import PrecisionDebugger
+
+# 请勿将PrecisionDebugger的初始化插入到循环代码中
+debugger = PrecisionDebugger(config_path="./config.json")
+
+# 模型、损失函数的定义以及初始化等操作
+# ...
+
+# 数据集迭代的地方往往是模型开始训练的地方
+for data, label in data_loader:
+    debugger.start()    # 开启数据dump
+    net = Model()
+    # 如下是模型每个step执行的逻辑
+    grad_net = ms.grad(net)(data)
+    # ...
+    debugger.stop()     # 关闭数据dump
+    debugger.step()     # 结束一个step的dump
+```
+
+当使用模型的train方法而非for循环时，可以通过在callbacks参数中传入MsprobeStep(debugger)：
+
+```Python
+from msprobe.mindspore.common.utils import MsprobeStep
+from msprobe.mindspore import PrecisionDebugger
+
+# 初始化PrecisionDebugger
+debugger = PrecisionDebugger(config_path="./config.json")
+
+# 自动在每个step开始时调用start()，在每个step结束时调用stop()和step()。
+# 这意味着您无需手动在循环内添加start、stop和step函数，框架会自动完成数据的dump操作。
+trainer.train(1, dataset_train, callbacks=[loss_monior, MsprobeStep(debugger)])
+
+```
+
 ## dump结果文件介绍
 
+### MindSpore静态图场景
+
 训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。
 
-- level为L1时
+- jit_level为O0/O1时
 
   dump结果目录请参见MindSpore官网中的《[同步Dump数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%90%8C%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)》。
 
-- level为L2时
+- jit_level为O2时
 
   dump结果目录请参见MindSpore官网中的《[异步Dump数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%BC%82%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)》。
 
+jit_level请参见[mindspore.set_context](https://www.mindspore.cn/docs/zh-CN/r2.3.0/api_python/mindspore/mindspore.JitConfig.html#mindspore-jitconfig)配置jit_config。
+
+### MindSpore动态图场景
+
+训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。
+
+dump结果目录结构示例如下：
+
+```bash
+├── dump_path
+│   ├── step0
+│   |   ├── rank0
+│   |   │   ├── dump_tensor_data
+|   |   |   |    ├── MintFunctional.relu.0.backward.input.0.npy
+|   |   |   |    ├── Mint.abs.0.forward.input.0.npy
+|   |   |   |    ├── Functional.split.0.forward.input.0.npy
+|   |   |   |    ├── Tensor.__add__.0.forward.output.0.npy
+|   |   |   |    ...
+|   |   |   |    └── Jit.AlexNet.0.forward.input.0.npy
+│   |   |   ├── 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        # 分层分级结构，level为L1时，construct.json内容为空
+│   |   ├── rank1
+|   |   |   ├── dump_tensor_data
+|   |   |   |   └── ...
+│   |   |   ├── dump.json
+│   |   |   ├── stack.json
+|   |   |   └── construct.json
+│   |   ├── ...
+│   |   |
+|   |   └── rank7
+│   ├── step1
+│   |   ├── ...
+│   ├── step2
+```
+
+dump过程中，npy文件在对应算子或者模块被执行后就会落盘，而json文件则需要在正常执行PrecisionDebugger.stop()后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关npy文件，可能会导致json文件中数据丢失。
+
+其中rank为设备上各卡的ID，每张卡上dump的数据会生成对应dump目录。非分布式场景下没有rank ID，目录名称为rank。
+
+动态图场景下使能PSJit或PIJit，装饰特定Cell或function，被装饰的部分会全部/部分使能静态图流程。PSJit场景下config.json文件配置level为L1时，被PSJit装饰的部分也作为API被dump到对应目录；若配置level为L2时，则只会dump用户网络中静态图流程下的相关kernel。PIJit场景开启dump工具后，会被还原为动态图，按API粒度进行dump。
+
+npy文件保存的前缀和MindSpore对应关系如下：
+
+| 前缀           | MindSpore模块                |
+| -------------- | ---------------------------- |
+| Tensor         | mindspore.Tensor             |
+| Functional     | mindspore.ops                |
+| Mint           | mindspore.mint               |
+| MintFunctional | mindspore.mint.nn.functional |
+| Jit            | mindspore.jit                |
+
+## 工具支持的API列表
+
+msprobe工具维护固定的API支持列表，若需要删除或增加dump的API，可以在msprobe/mindspore/dump/hook_cell/support_wrap_ops.yaml文件内手动修改，如下示例：
+
+```bash
+ops:  # ops为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API
+  - adaptive_avg_pool1d
+  - adaptive_avg_pool2d
+  - adaptive_avg_pool3d
+```

msprobe/mindspore/dump/dump_tool_factory.py

@@ -1,24 +1,25 @@
+from msprobe.mindspore.common.const import Const
 from msprobe.mindspore.debugger.debugger_config import DebuggerConfig
-from msprobe.mindspore.dump.api_kbk_dump import ApiKbkDump
+from msprobe.mindspore.dump.kernel_kbyk_dump import KernelKbykDump
 from msprobe.mindspore.dump.kernel_graph_dump import KernelGraphDump
 
 
 class DumpToolFactory:
     tools = {
-        "cell": {
-            "kbk": None,
-            "graph": None,
-            "pynative": None
+        Const.CELL: {
+            Const.GRAPH_KBYK_MODE: None,
+            Const.GRAPH_GE_MODE: None,
+            Const.PYNATIVE_MODE: None
         },
-        "api": {
-            "kbk": ApiKbkDump,
-            "graph": None,
-            "pynative": None
+        Const.API: {
+            Const.GRAPH_KBYK_MODE: None,
+            Const.GRAPH_GE_MODE: None,
+            Const.PYNATIVE_MODE: None
         },
-        "kernel": {
-            "kbk": None,
-            "graph": KernelGraphDump,
-            "pynative": None
+        Const.KERNEL: {
+            Const.GRAPH_KBYK_MODE: KernelKbykDump,
+            Const.GRAPH_GE_MODE: KernelGraphDump,
+            Const.PYNATIVE_MODE: KernelKbykDump
         }
     }
 
@@ -26,13 +27,9 @@ class DumpToolFactory:
     def create(config: DebuggerConfig):
         tool = DumpToolFactory.tools.get(config.level)
         if not tool:
-            raise Exception("valid level is needed.")
-        if config.level == "api":
-            tool = tool.get("kbk")
-        elif config.level == "kernel":
-            tool = tool.get("graph")
-        elif config.level == "cell":
-            raise Exception("Cell dump in not supported now.")
+            raise Exception("Valid level is needed.")
+        tool = tool.get(config.execution_mode)
         if not tool:
-            raise Exception("Data dump in not supported in this mode.")
-        return tool(config)
+            raise Exception(f"Data dump is not supported in {config.execution_mode} mode "
+                            f"when dump level is {config.level}.")
+        return tool(config)

msprobe/mindspore/dump/hook_cell/api_registry.py

@@ -0,0 +1,104 @@
+# Copyright 2024 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+
+import mindspore as ms
+from msprobe.mindspore.dump.hook_cell.wrap_functional import get_functional_ops, setup_hooks, \
+    HOOKFunctionalOP, HOOKMintOP, HOOKMintNNFunctionalOP
+from msprobe.mindspore.dump.hook_cell.wrap_tensor import get_tensor_ops, wrap_tensor_ops_and_bind, HOOKTensor
+from msprobe.core.common.utils import Const
+
+
+class ApiRegistry:
+    def __init__(self):
+        self.tensor_ori_attr = {}
+        self.functional_ori_attr = {}
+        self.mint_ops_ori_attr = {}
+        self.mint_func_ops_ori_attr = {}
+        self.norm_inner_ops_ori_attr = {}
+
+        self.tensor_hook_attr = {}
+        self.functional_hook_attr = {}
+        self.mint_ops_hook_attr = {}
+        self.mint_func_ops_hook_attr = {}
+        self.norm_inner_ops_hook_attr = {}
+
+        self.norm_inner_ops = ["norm", "square", "sqrt", "is_complex"]
+
+    @staticmethod
+    def store_ori_attr(ori_api_group, api_list, api_ori_attr):
+        for api in api_list:
+            if Const.SEP in api:
+                sub_module_name, sub_op = api.rsplit(Const.SEP, 1)
+                sub_module = getattr(ori_api_group, sub_module_name)
+                api_ori_attr[api] = getattr(sub_module, sub_op)
+            else:
+                api_ori_attr[api] = getattr(ori_api_group, api)
+
+    @staticmethod
+    def set_api_attr(api_group, attr_dict):
+        for api, api_attr in attr_dict.items():
+            if Const.SEP in api:
+                sub_module_name, sub_op = api.rsplit(Const.SEP, 1)
+                sub_module = getattr(api_group, sub_module_name, None)
+                if sub_module is not None:
+                    setattr(sub_module, sub_op, api_attr)
+            else:
+                setattr(api_group, api, api_attr)
+
+    def norm_inner_op_set_hook_func(self):
+        self.set_api_attr(ms.ops, self.norm_inner_ops_hook_attr)
+
+    def norm_inner_op_set_ori_func(self):
+        self.set_api_attr(ms.ops, self.norm_inner_ops_ori_attr)
+
+    def api_set_hook_func(self):
+        self.set_api_attr(ms.Tensor, self.tensor_hook_attr)
+        self.set_api_attr(ms.ops, self.functional_hook_attr)
+        self.set_api_attr(ms.mint, self.mint_ops_hook_attr)
+        self.set_api_attr(ms.mint.nn.functional, self.mint_func_ops_hook_attr)
+
+    def api_set_ori_func(self):
+        self.set_api_attr(ms.Tensor, self.tensor_ori_attr)
+        self.set_api_attr(ms.ops, self.functional_ori_attr)
+        self.set_api_attr(ms.mint, self.mint_ops_ori_attr)
+        self.set_api_attr(ms.mint.nn.functional, self.mint_func_ops_ori_attr)
+
+    def initialize_hook(self, hook):
+        self.store_ori_attr(ms.Tensor, get_tensor_ops(), self.tensor_ori_attr)
+        wrap_tensor_ops_and_bind(hook)
+        for attr_name in dir(HOOKTensor):
+            if attr_name.startswith(Const.ATTR_NAME_PREFIX):
+                self.tensor_hook_attr[attr_name[Const.ATTR_NAME_PREFIX_LEN:]] = getattr(HOOKTensor, attr_name)
+
+        functional_ops, mint_ops, mint_func_ops = get_functional_ops()
+        self.store_ori_attr(ms.ops, self.norm_inner_ops, self.norm_inner_ops_ori_attr)
+        self.store_ori_attr(ms.ops, functional_ops, self.functional_ori_attr)
+        self.store_ori_attr(ms.mint, mint_ops, self.mint_ops_ori_attr)
+        self.store_ori_attr(ms.mint.nn.functional, mint_func_ops, self.mint_func_ops_ori_attr)
+        setup_hooks(hook)
+        for attr_name in dir(HOOKFunctionalOP):
+            if attr_name.startswith(Const.ATTR_NAME_PREFIX):
+                self.functional_hook_attr[attr_name[Const.ATTR_NAME_PREFIX_LEN:]] = getattr(HOOKFunctionalOP, attr_name)
+                if attr_name[Const.ATTR_NAME_PREFIX_LEN:] in self.norm_inner_ops:
+                    self.norm_inner_ops_hook_attr[attr_name[Const.ATTR_NAME_PREFIX_LEN:]] = getattr(HOOKFunctionalOP, attr_name)
+        for attr_name in dir(HOOKMintOP):
+            if attr_name.startswith(Const.ATTR_NAME_PREFIX):
+                self.mint_ops_hook_attr[attr_name[Const.ATTR_NAME_PREFIX_LEN:]] = getattr(HOOKMintOP, attr_name)
+        for attr_name in dir(HOOKMintNNFunctionalOP):
+            if attr_name.startswith(Const.ATTR_NAME_PREFIX):
+                self.mint_func_ops_hook_attr[attr_name[Const.ATTR_NAME_PREFIX_LEN:]] = getattr(HOOKMintNNFunctionalOP, attr_name)
+
+
+api_register = ApiRegistry()

msprobe/mindspore/dump/hook_cell/hook_cell.py

@@ -0,0 +1,53 @@
+# Copyright 2024 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+from collections import defaultdict
+
+from mindspore import nn
+from msprobe.core.common.const import Const
+
+
+class HOOKCell(nn.Cell):
+    cell_count = defaultdict(int)
+    g_stop_hook = False
+
+    def __init__(self, build_hook) -> None:
+        super(HOOKCell, self).__init__()
+        self.changed_status = False
+        self.input_kwargs = {}
+        self.prefix = ""
+        if not HOOKCell.g_stop_hook:
+            HOOKCell.g_stop_hook = True
+            self.changed_status = True
+            if hasattr(self, "prefix_op_name_"):
+                self.prefix = self.prefix_op_name_
+
+            HOOKCell.cell_count[self.prefix] += 1
+            self.prefix = self.prefix + str(HOOKCell.cell_count[self.prefix] - 1) + Const.SEP
+            forward_hook, backward_hook = build_hook(self.prefix)
+            self.register_forward_hook(forward_hook)
+            self.register_backward_hook(backward_hook)
+
+    # 重载call，加全局标志。
+    def __call__(self, *args, **kwargs):
+        try:
+            self.input_kwargs = kwargs
+            out = super(HOOKCell, self).__call__(*args, **kwargs)
+        except Exception as e:
+            raise e
+        finally:
+            if self.changed_status:
+                self.changed_status = False
+                HOOKCell.g_stop_hook = False
+        return out