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

msprobe/core/overflow_check/checker.py

@@ -0,0 +1,138 @@
+# Copyright (c) 2024-2024, Huawei Technologies Co., Ltd.
+# All rights reserved.
+#
+# 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 typing import Dict, List, Optional, Any
+
+from msprobe.core.common.const import Const
+
+from msprobe.core.overflow_check.abnormal_scene import InputAnomalyOutputNormalScene, InputAnomalyOutputAnomalyScene, \
+    InputNormalOutputAnomalyScene, NumericalMutationScene, AnomalyScene
+from msprobe.core.overflow_check.api_info import APIInfo
+from msprobe.core.overflow_check.filter import IgnoreFilter
+from msprobe.core.overflow_check.level import OverflowLevel
+
+
+class StatisticsFields:
+    """统计字段常量类"""
+    CRITICAL_APIS = 'critical_apis'
+    HIGH_PRIORITY_APIS = 'high_priority_apis'
+    MEDIUM_PRIORITY_APIS = 'medium_priority_apis'
+    ANOMALY_DETAILS = 'anomaly_details'
+
+    # 所有字段
+    ALL_FIELDS = [CRITICAL_APIS, HIGH_PRIORITY_APIS, MEDIUM_PRIORITY_APIS, ANOMALY_DETAILS]
+
+
+class AnomalyDetector:
+    """异常检测器"""
+
+    def __init__(self, dump_data: Dict):
+        """
+            初始化检测器，并保存dump_data
+        Args:
+            dump_data: 数据格式如下
+                {
+                    "api/module": {statistics}
+                }
+        """
+        self.dump_data = dump_data
+        self.ignore_filter = IgnoreFilter()
+        self.scene_types = [
+            InputNormalOutputAnomalyScene,      # 输入正常，输出异常
+            InputAnomalyOutputAnomalyScene,     # 输入异常，输出异常
+            InputAnomalyOutputNormalScene,      # 输入异常，输出正常
+            NumericalMutationScene              # 输出较输入值突变
+        ]
+        self.anomaly_scenes: Dict[str, AnomalyScene] = dict()
+
+    @staticmethod
+    def _create_api_info(api_name: str, data: Dict) -> APIInfo:
+        """从原始数据创建APIInfo实例"""
+        return APIInfo(
+            api_name=api_name,
+            input_args=data.get(Const.INPUT_ARGS, []),
+            input_kwargs=data.get(Const.INPUT_KWARGS, {}),
+            output_data=data.get(Const.OUTPUT, [])
+        )
+
+    def get_statistics(self) -> Dict[str, List]:
+        """获取统计信息
+
+        使用StatisticsFields类统一管理字段名称，避免硬编码
+
+        Returns:
+            Dict[str, List]: 包含各优先级API列表和异常详情的字典
+        """
+        stats = {field: [] for field in StatisticsFields.ALL_FIELDS}
+
+        # 定义rank到结果key的映射关系
+        rank_to_key = {
+            OverflowLevel.CRITICAL: StatisticsFields.CRITICAL_APIS,
+            OverflowLevel.HIGH: StatisticsFields.HIGH_PRIORITY_APIS,
+            OverflowLevel.MEDIUM: StatisticsFields.MEDIUM_PRIORITY_APIS
+        }
+
+        for scene in self.anomaly_scenes.values():
+            stats[StatisticsFields.ANOMALY_DETAILS].append(scene.get_details())
+            # 根据rank分类API
+            key = rank_to_key.get(scene.rank, None)
+            if not key:
+                stats[key].append(scene.api_name)
+
+        return stats
+
+    def analyze(self):
+        """
+            按照异常场景对调用数据进行分析
+        Returns:
+            返回类本身，若不进行过滤，则仅调用analyze即可
+        """
+        # 遍历data item
+        for api_name, data in self.dump_data.items():
+            api_info = self._create_api_info(api_name, data)
+
+            # 每种都进行检测，可能涉及多种命中，原则如下：
+            #   - 就高原则
+            #   - 优先原则，数据异常放最后检测
+            for scene_type in self.scene_types:
+                scene = scene_type(api_info)
+                if hasattr(scene, 'matches') and scene.matches():
+                    self.anomaly_scenes[api_name] = scene
+                    break  # 直接跳过，就高原则
+        return self
+
+    def filter(self):
+        """
+            对误检数据进行过滤
+        Returns:
+            检查checker自身，方便链式调用
+        """
+        result = dict()
+        for api_name, scene in self.anomaly_scenes.items():
+            if self.ignore_filter.apply_filter(scene.api_data):
+                continue
+            result[api_name] = scene
+        self.anomaly_scenes = result
+        return self
+
+    def overflow_result(self) -> Dict[str, AnomalyScene]:
+        return self.anomaly_scenes
+
+    def has_overflow(self, api_name: str) -> bool:
+        return api_name in self.anomaly_scenes.keys()
+
+    def get_overflow_level(self, api_name: str) -> Optional[Any]:
+        scene = self.anomaly_scenes.get(api_name, None)
+        return scene.rank if scene else None

msprobe/core/overflow_check/filter.py

@@ -0,0 +1,157 @@
+# Copyright (c) 2024-2024, Huawei Technologies Co., Ltd.
+# All rights reserved.
+#
+# 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 os.path
+from dataclasses import dataclass, field
+from typing import Set
+
+from msprobe.core.common.file_utils import load_yaml
+from msprobe.core.overflow_check.api_info import APIInfo
+from msprobe.core.overflow_check.utils import has_nan_inf
+
+cur_path = os.path.dirname(os.path.realpath(__file__))
+
+
+class IgnoreFilter:
+    def __init__(self, rule_path=os.path.join(cur_path, './ignore_rules.yaml')):
+        self.rules = dict()
+        self._load_rules(rule_path)
+
+    def has_api_rule(self, api_name: str) -> bool:
+        return api_name in self.rules.keys()
+
+    def apply_filter(self, api_info: APIInfo) -> bool:
+        """
+            应用过滤规则，返回是否需要被过滤
+        Args:
+            api_info: API调用信息
+        Returns:
+            是否为误检，是否需要过滤
+        """
+        torch_api = api_info.torch_api_name
+        if not self.has_api_rule(torch_api):
+            return False
+        rule = self.rules.get(torch_api)
+        if not rule.match(api_info):
+            return False
+        return True
+
+    def _load_rules(self, rule_file_path):
+        if self.rules and len(self.rules):
+            return
+        data = load_yaml(rule_file_path)
+        self.rules = dict()
+        for rule_item in data.get('ignore_nan_inf', []):
+            rule = Rule(
+                api_name=rule_item.get('api_name', ''),
+                desc=rule_item.get('description', ''),
+                input_ignore=rule_item.get('input_ignore', []),
+                output_ignore=rule_item.get('output_ignore', [])
+            )
+            if not rule.verify_field():
+                continue
+            if self.has_api_rule(rule.api_name):
+                continue
+            self.rules[rule.api_name] = rule
+
+
+class Rule:
+
+    def __init__(self, api_name, desc='', input_ignore=None, output_ignore=None):
+        self.api_name = api_name
+        self.desc = desc
+        self.input_ignore = IgnoreItem()
+        self.output_ignore = IgnoreItem()
+        self._init_ignore(input_ignore, output_ignore)
+
+    def __repr__(self):
+        return (f'Rule(api_name={self.api_name}, desc={self.desc}, input_ignore={self.input_ignore}, output_ignore='
+                f'{self.output_ignore})')
+
+    def verify_field(self):
+        if self.api_name == '':
+            return False
+        # 若无输入输出规则长度，则为无效规则
+        if not (len(self.input_ignore.index) + len(self.input_ignore.name) + len(self.output_ignore.index)):
+            return False
+        return True
+
+    def match(self, api_info: APIInfo) -> bool:
+        """
+            匹配API信息是否符合规则
+        Returns:
+            bool: True if the api_info matches this rule, False otherwise
+        """
+        # 首先检查API名称是否匹配
+        api_name = api_info.torch_api_name
+        if api_name != self.api_name:
+            return False
+
+        # 检查输入参数中的NaN/Inf
+        if self.input_ignore.index and len(api_info.input_args):
+            for idx, arg in enumerate(api_info.input_args):
+                if has_nan_inf(arg) and not self.input_ignore.has_index(idx):
+                    return False
+
+        # 检查输入kwargs中的NaN/Inf
+        if self.input_ignore.name and len(api_info.input_kwargs):
+            for name, value in api_info.input_kwargs.items():
+                if has_nan_inf(value) and not self.input_ignore.has_name(name):
+                    return False
+
+        # 检查输出中的NaN/Inf
+        if self.output_ignore.index and len(api_info.output_data):
+            for idx, out in enumerate(api_info.output_data):
+                if has_nan_inf(out) and not self.output_ignore.has_index(idx):
+                    return False
+
+        return True
+
+    def _init_ignore(self, input_ignore=None, output_ignore=None):
+        """初始化忽略项"""
+        if input_ignore is None:
+            input_ignore = []
+        if output_ignore is None:
+            output_ignore = []
+
+        # 处理输入忽略规则
+        for item in input_ignore:
+            if 'index' in item:
+                self.input_ignore.add_index(item['index'])
+            if 'name' in item:
+                self.input_ignore.add_name(item['name'])
+
+        # 处理输出忽略规则
+        for item in output_ignore:
+            if 'index' in item:
+                self.output_ignore.add_index(item['index'])
+
+
+@dataclass
+class IgnoreItem:
+    """存储需要忽略的索引和名称"""
+    index: Set[int] = field(default_factory=set)
+    name: Set[str] = field(default_factory=set)
+
+    def add_index(self, idx: int):
+        self.index.add(idx)
+
+    def add_name(self, name: str):
+        self.name.add(name)
+
+    def has_index(self, idx: int) -> bool:
+        return idx in self.index
+
+    def has_name(self, name: str) -> bool:
+        return name in self.name

msprobe/core/overflow_check/ignore_rules.yaml

@@ -0,0 +1,55 @@
+ignore_nan_inf:
+  # Create an uninitialized memory
+  - api_name: "torch.empty"
+    description: "Creates a tensor with uninitialized data. The values may contain NaN or Inf because the memory is not cleared or set to zero."
+    output_ignore:
+      - index: 0
+
+  - api_name: "torch.empty_like"
+    description: "Creates an uninitialized tensor with the same size, dtype, and device as the input tensor. The values may contain NaN or Inf due to uninitialized memory."
+    output_ignore:
+      - index: 0
+
+  - api_name: "torch.empty_strided"
+    description: "Creates a tensor with uninitialized data using specified strides. NaN or Inf may be present due to uninitialized memory."
+    output_ignore:
+      - index: 0
+
+  # Distributed func
+  - api_name: "distributed.recv"
+    description: "Receives a tensor from another process. The input tensor may contain uninitialized data before the recv call, but it will be overwritten with received data."
+    input_ignore:
+      - index: 0  # tensor (the input buffer, which may be uninitialized before receiving)
+      - name: tensor
+
+  - api_name: "distributed.all_gather"
+    description: "Gathers tensors from all processes and distributes them to each process. The tensors in tensor_list may contain uninitialized data before the all_gather call, but they will be overwritten with collected data from all processes."
+    input_ignore:
+      - index: 0  # tensor_list (the input list of tensors, which may contain uninitialized data before the all_gather call)
+
+  - api_name: "distributed.reduce_scatter"
+    description: "Combines reduction and scatter operations. The output tensor may contain uninitialized data before the reduce_scatter call, but it will be overwritten with the reduced and scattered data from all processes."
+    input_ignore:
+      - index: 0
+      - name: output
+
+  - api_name: "distributed._reduce_scatter_base"
+    description: "Performs a combined reduction and scatter operation using a single input tensor. The output tensor may contain uninitialized data before the _reduce_scatter_base call, but it will be overwritten with the reduced and scattered data."
+    input_ignore:
+      - index: 0
+
+  - api_name: "distributed.all_gather_into_tensor"
+    description: "Gathers tensors from all processes into a single output tensor. The output tensor may contain uninitialized data before the all_gather_into_tensor call, but it will be overwritten with collected data from all processes."
+    input_ignore:
+      - index: 0
+
+  - api_name: "distributed.reduce_scatter_tensor"
+    description: "Performs a reduction operation across all processes and scatters the result into the output tensor. The output tensor may contain uninitialized data before the reduce_scatter_tensor call, but it will be overwritten with the reduced and scattered data."
+    input_ignore:
+      - index: 0
+
+  # Tensor inplace func
+  - api_name: "tensor.masked_fill_"
+    description: "Inplace fill tensor with given value by filtered mask"
+    input_ignore:
+      - index: 0

msprobe/core/overflow_check/level.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2024-2024, Huawei Technologies Co., Ltd.
+# All rights reserved.
+#
+# 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 enum import Enum
+
+
+class OverflowLevel(Enum):
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"

msprobe/core/overflow_check/utils.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2024-2024, Huawei Technologies Co., Ltd.
+# All rights reserved.
+#
+# 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 typing import Any
+
+CHECK_FIELDS = ['Max', 'Min', 'Mean', 'Norm']
+OVERFLOW_VALUES = ['inf', '-inf', 'nan']
+
+
+def has_nan_inf(value: Any) -> bool:
+    """检查值是否包含NaN或Inf"""
+    if isinstance(value, dict):
+        for k, v in value.items():
+            if k in CHECK_FIELDS and str(v).lower() in OVERFLOW_VALUES:
+                return True
+    return False

msprobe/docs/01.installation.md

@@ -16,6 +16,7 @@ pip install mindstudio-probe
 
 |版本|发布日期|支持 PyTorch 版本|支持 MindSpore 版本|下载链接|校验码|
 |:--:|:--:|:--:|:--:|:--:|:--:|
+|1.1.0|2024.10.14|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.1.0-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.1/mindstudio_probe-1.1.0-py3-none-any.whl)|83a5a9b7c65a357639f8c9636d88c693b4cf0eb590d4f8f5cb56395ba69b1f6d|
 |1.0.4|2024.09.09|1.11/2.0/2.1/2.2|2.4.0|[mindstudio_probe-1.0.4-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.4-py3-none-any.whl)|4e1909566a71a855b356597750c20ee43d964a22b2c2b02ac08312a5def75fd6|
 | 1.0.3 | 2024.08.23 | 1.11/2.0/2.1/2.2 | 2.4.0 | [mindstudio_probe-1.0.3-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.3-py3-none-any.whl) | 7060cc141a5b98ef770cd9220995d299393f32a61938261e632c7e8b5160bef2 |
 | 1.0.2 | 2024.08.09 | 1.11/2.0/2.1/2.2 | 2.4.0 | [mindstudio_probe-1.0.2-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.2-py3-none-any.whl) | e4a980e5d98c426ce5ce9842520d9bc031d3b3de621c74b3d59414cc6e238e0e |
@@ -49,6 +50,15 @@ pip install ./mindstudio_probe*.whl
 
 <table>
     <tr><th>版本</th><th>特性</th></tr>
+    <tr><td rowspan="5">1.1.0</td><td>【总体】</br>1. 训练精度一体化工具 atat 统一更名为 msprobe；</br>2. msprobe 支持日志分级功能。</td></tr>
+    <tr><td>【精度预检】</br>1. 支持配置 blacklist 黑名单字段；</br>2. 补充了支持的融合算子列表。</td></tr>
+    <tr><td>【精度比对】</br>1. 支持 data mapping 和 layer mapping 的比对功能。</td></tr>
+    <tr><td>【数据采集】</br>1. 增加 L1 dump 接口，支持在指定区间内进行正反向 dump 功能；</br>2. 在 MindSpore 中新增 mix 模式，支持指定模块内部进行 dump；</br>3. 新增 MindSpore 函数式接口的通信 API dump 功能。</td></tr>
+    <tr><td>【梯度工具】</br>1. 增加了梯度工具中关于 JIT 限制的说明。</td></tr>
+    <tr><td rowspan="4">1.0.4</td><td>【数据采集】</br>1. 支持在 config.json 中传入 step 范围配置；</br>2. 优化了 MindSpore 场景下的 step 机制，step 结束后训练继续运行。</td></tr>
+    <tr><td>【精度预检】</br>1. 在 PyTorch 场景下，支持部分 NPU 融合算子精度预检。</td></tr>
+    <tr><td>【精度比对】</br>1. 解决了在 MindSpore 场景下需要安装 PyTorch 的问题。</td></tr>
+    <tr><td>【无标杆比对】</br>1. 补充了 PyTorch 场景的性能基线报告；</br>2. 支持 MindSpore 场景下的 change_value 扰动模式。</td></tr>
     <tr><td rowspan="2">1.0.3</td><td>【精度预检】</br>1. 落盘数据小；</br>2. 支持随机生成模式和真实数据模式；</br>3. 单 API 测试，排除整网中的累计误差问题。</td></tr>
     <tr><td>【梯度检测】</br>1. 使用便捷，无需在训练流程里插入代码。</br>2. 可以精准定位问题出现的 step。</td></tr>
 </table>

msprobe/docs/02.config_introduction.md

@@ -10,15 +10,14 @@
 
 ### 1.1 通用配置
 
-| 参数    | 解释    | 是否必选 |
-| ----------------- | ---------------- | -------- |
-| task              | dump 的任务类型，str 类型。可选参数：<br/>  "statistics"：仅采集统计信息，默认值；<br/> "tensor"：采集统计信息和完全复刻整网的真实数据；<br/> "run_ut"：精度预检，仅 PyTorch 场景支持，采集数据时勿选；<br/> "overflow_check"：溢出检测；<br/>  "free_benchmark"：无标杆比对。<br/>    根据 task 参数取值的不同，可以配置不同场景参数，详见：<br/>[1.2 task 配置为 statistics](#12-task-配置为-statistics)，<br/>[1.3 task 配置为 tensor](#13-task-配置为-tensor)，<br/>[1.4 task 配置为 run_ut](#14-task-配置为-run_ut)，<br/>[1.5 task 配置为 overflow_check](#15-task-配置为-overflow_check)，<br/>[1.6 task 配置为 free_benchmark](#16-task-配置为-free_benchmark)。 <br/>  **配置示例**："task": "tensor"。  | 否       |
-| dump_path         | 设置 dump 数据目录路径，str 类型。<br/>  **配置示例**："dump_path": "./dump_path"。 | 是       |
-| rank              | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型，默认未配置（表示采集所有卡的数据），应配置元素为 ≥0 的整数或类似"4-6"的字符串，且须配置实际可用的 Rank ID。<br/>  PyTorch 场景: Rank ID 从 0 开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的 Rank ID，则 dump 数据为空，比如当前环境 Rank ID 为 0 到 7，实际训练运行 0 到 3 卡，此时若配置 Rank ID 为 4 或不存在的 10 等其他值，dump 数据为空。<br/>  MindSpore 场景：所有节点的 Rank ID 均从 0 开始计数，最大取值为每个节点可用卡总数-1，config.json 配置一次 rank 参数对所有节点同时生效。<br/>**配置示例**："rank": [1, "4-6"]。 | 否       |
-| step              | 指定采集某个 step 的数据，list[Union[int, str]] 类型。默认未配置，表示采集所有 step 数据。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。 | 否       |
-| level             | dump 级别，str 类型，根据不同级别采集不同数据。可选参数：<br/>"L0"：dump 模块级精度数据，仅 PyTorch 与 MindSpore 动态图场景支持，使用背景详见 [1.1.1 模块级精度数据 dump 说明](#111-模块级精度数据-dump-说明)；<br/>"L1"：dump API 级精度数据，默认值，仅 PyTorch 与 MindSpore 动态图场景支持；<br/>"L2"：dump kernel 级精度数据，PyTorch 场景下须配置 acl_config 参数；<br/>"mix"：dump module 模块级和 API 级精度数据，即"L0"+"L1"，仅 PyTorch 与 MindSpore 动态图场景支持。<br/>  **配置示例**："level": "L1"。 | 否 |
-| acl_config        | kernel dump 的配置文件，str 类型。当 PyTorch 场景的 level 取"L2"时，该参数必选；level 为其他值时，该参数不选。<br/> **配置示例**：acl_config="./acl_config.json"。具体配置见[ acl_config 示例](./04.acl_config_examples.md)。 | 否       |
-| enable_dataloader | 自动控制开关，bool 类型，仅 PyTorch 场景支持。可选参数 true（开启）或 false（关闭），默认为 false。配置为 true 后自动识别 step 参数指定的迭代，并在该迭代执行完成后退出训练，此时 start、stop 和 step 函数可不配置，开启该开关要求训练脚本是通过 torch.utils.data.dataloader 方式加载数据。仅支持 PyTorch 单卡训练使用，分布式训练场景下存在数据 dump 不全问题。 | 否       |
+| 参数    | 解释                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 是否必选 |
+| ----------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| task              | dump 的任务类型，str 类型。可选参数：<br/>  "statistics"：仅采集统计信息，默认值；<br/> "tensor"：采集统计信息和完全复刻整网的真实数据；<br/> "run_ut"：精度预检，仅 PyTorch 场景支持，采集数据时勿选；<br/> "overflow_check"：溢出检测；<br/>  "free_benchmark"：无标杆比对；<br/>  "grad_probe"：梯度监控。<br/>    根据 task 参数取值的不同，可以配置不同场景参数，详见：<br/>[1.2 task 配置为 statistics](#12-task-配置为-statistics)，<br/>[1.3 task 配置为 tensor](#13-task-配置为-tensor)，<br/>[1.4 task 配置为 run_ut](#14-task-配置为-run_ut)，<br/>[1.5 task 配置为 overflow_check](#15-task-配置为-overflow_check)，<br/>[1.6 task 配置为 free_benchmark](#16-task-配置为-free_benchmark)，<br/>[1.7 task 配置为 grad_probe](#17-task-配置为-grad_probe)。 <br/>  **配置示例**："task": "tensor"。 | 否       |
+| dump_path         | 设置 dump 数据目录路径，str 类型。<br/>  **配置示例**："dump_path": "./dump_path"。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | 是       |
+| rank              | 指定对某张卡上的数据进行采集，list[Union[int, str]] 类型，默认未配置（表示采集所有卡的数据），应配置元素为 ≥0 的整数或类似"4-6"的字符串，且须配置实际可用的 Rank ID。<br/>  PyTorch 场景: Rank ID 从 0 开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的 Rank ID，则 dump 数据为空，比如当前环境 Rank ID 为 0 到 7，实际训练运行 0 到 3 卡，此时若配置 Rank ID 为 4 或不存在的 10 等其他值，dump 数据为空。<br/>  MindSpore 场景：所有节点的 Rank ID 均从 0 开始计数，最大取值为每个节点可用卡总数-1，config.json 配置一次 rank 参数对所有节点同时生效。<br/> 注意，单卡训练时，rank必须为[]，即空列表，不能指定rank。<br/>**配置示例**："rank": [1, "4-6"]。                                                                                                       | 否       |
+| step              | 指定采集某个 step 的数据，list[Union[int, str]] 类型。默认未配置，表示采集所有 step 数据。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。                                                                                                                                                                                                                                                                                                                                                                                                            | 否       |
+| level             | dump 级别，str 类型，根据不同级别采集不同数据。可选参数：<br/>"L0"：dump 模块级精度数据，仅 PyTorch 与 MindSpore 动态图场景支持，使用背景详见 [1.1.1 模块级精度数据 dump 说明](#111-模块级精度数据-dump-说明)；<br/>"L1"：dump API 级精度数据，默认值，仅 PyTorch 与 MindSpore 动态图场景支持；<br/>"L2"：dump kernel 级精度数据，PyTorch场景详细介绍见 [PyTorch 场景的 kernel dump 说明](./04.kernel_dump_PyTorch.md)；<br/>"mix"：dump module 模块级和 API 级精度数据，即"L0"+"L1"，仅 PyTorch 与 MindSpore 动态图场景支持。<br/>  **配置示例**："level": "L1"。                                                                                                                                                    | 否 |
+| enable_dataloader | 自动控制开关，bool 类型，仅 PyTorch 场景支持。可选参数 true（开启）或 false（关闭），默认为 false。配置为 true 后自动识别 step 参数指定的迭代，并在该迭代执行完成后退出训练，此时 start、stop 和 step 函数可不配置，开启该开关要求训练脚本是通过 torch.utils.data.dataloader 方式加载数据。仅支持 PyTorch 单卡训练使用，分布式训练场景下存在数据 dump 不全问题。 **这个特性下个版本将被废弃**                                                                                                                                                                                                                                                                                                           | 否       |
 
 #### 1.1.1 模块级精度数据 dump 说明
 
@@ -34,19 +33,21 @@
 
 <table>
     <tr><th>参数</th><th>解释</th><th>是否必选</th></tr>
-    <tr><td>scope</td><td>PyTorch 和 MindSpore 动态图场景 dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 API 的数据）。该参数可以在 [ ] 内配置两个模块名或 API 名，用于锁定区间，dump 该范围内的数据；也可以在 [ ] 内配置一个模块名，表示dump此模块内部的API或子模块数据（仅level配置为mix时支持配置一个模块名）。<br/><b>配置示例</b>："scope": ["MyModuleOP1", "MyModuleOP2"]或"scope": ["MyModuleOP1"]。与 level 参数取值相关，level 为 L0 和 mix 级别时，可配置模块名；level 为 L1 级别时，可配置 API 名。</td><td>否</td></tr>
+    <tr><td>scope</td><td>PyTorch 和 MindSpore 动态图场景 dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 API 的数据）。该参数可以在 [ ] 内配置两个模块名或 API 名，要求列表长度必须为2，需要配置按照工具命名格式的完整模块名或API名称，用于锁定区间，dump 该范围内的数据。<br/><b>配置示例</b>：  
+    "scope": ["Module.conv1.Conv2d.forward.0", "Module.fc2.Linear.forward.0"],                             
+    或 "scope": ["Cell.conv1.Conv2d.forward.0", "Cell.fc2.Dense.backward.0"], 或"scope": ["Tensor.add.0.forward", "Functional.square.2.forward"]。与 level 参数取值相关，level 为 L0 级别时，可配置模块名；level 为 L1 级别时，可配置 API 名， level为 mix 级别时，可配置为模块名或API名。</td><td>否</td></tr>
     <tr><td rowspan="4">list</td><td>自定义采集的算子列表，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 API 的数据），包含以下配置方法：</td><td rowspan="4">否</td></tr>
-    <tr><td>PyTorch 和 MindSpore 动态图场景配置具体的 API 全称，dump 该 API 数据。<br/><b>配置示例</b>："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。</td></tr>
-    <tr><td>PyTorch 和 MindSpore 动态图场景指定某一类 API，dump 某一类的 API 级别输入输出数据。<br/><b>配置示例</b>："list": ["relu"]。</td></tr>
+    <tr><td>PyTorch 和 MindSpore 动态图场景配置具体的 API 全称，dump 该 API 数据。在 PyTorch 场景，如果 level 配置成 L2，该配置为必填项。<br/><b>配置示例</b>："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。<br/> PyTorch 和 MindSpore 动态图场景在level为 mix 级别时可以配置模块名称，dump该模块展开数据 （dump该模块执行前到执行期间结束所有的数据）。
+    <br/><b>配置示例</b>："list": ["Module.module.language_model.encoder.layers.0.mlp.ParallelMlp.forward.0"], 或 "list": ["Cell.network_with_loss.language_model.encoder.layers.0.mlp.ParallelMlp.forward.0"]</td></tr>
+    <tr><td>PyTorch 和 MindSpore 动态图场景指定某一类 API，dump 某一类的 API 级别输入输出数据。<br/><b>配置示例</b>："list": ["relu"]。 <br/>    PyTorch 和 MindSpore 动态图场景在level为 mix 级别时, 会dump名称中包含list中配置的字符串的API数据，还会将名称中包含list中配置的字符串的模块进行展开dump （dump该模块执行前到执行期间结束所有的数据）。</td></tr> 
     <tr><td>MindSpore 静态图场景配置 kernel_name，可以是算子的名称列表，也可以指定算子类型（"level": "L2"时不支持），还可以配置算子名称的正则表达式（当字符串符合“name-regex(xxx)”格式时，后台则会将其作为正则表达式。<br/><b>配置示例</b>：list: ["name-regex(Default/.+)"]<br/>可匹配算子名称以“Default/”开头的所有算子。</td></tr>
     <tr><td rowspan="3">data_mode</td><td>dump 数据过滤，str 类型。</td><td rowspan="3">否</td></tr>
-    <tr><td>PyTorch 场景：支持"all"、"forward"、"backward"、"input"和"output"，表示仅采集包含"forward"、"backward"、"input"和"output"字段的数据。<br/> <b>配置示例</b>："data_mode": ["backward"] 或 "data_mode": ["forward", "backward"]。默认为["all"]，即保存所有 dump 的数据。除了 all 参数只能单独配置外，其他参数可以自由组合。</td></tr>
-    <tr><td>MindSpore 场景：仅支持"all"、"input"和"output"参数，且各参数只能单独配置，不支持自由组合。<br/><b>配置示例</b>："data_mode": ["all"]。</td></tr>
-    <tr><td>summary_mode</td><td>控制 dump 文件输出的模式，str 类型，仅 PyTorch 场景支持，可选参数：<br/> md5：dump 输出包含 md5 值以及 API 统计信息的 dump.json 文件，用于验证数据的完整性；<br/> statistics：dump 仅输出包含 API 统计信息的 dump.json 文件，默认值。<br/><b>配置示例</b>："summary_mode": "md5"。</td><td>否</td></tr>
+    <tr><td>PyTorch 与 MindSpore 动态图场景：支持"all"、"forward"、"backward"、"input"和"output"，除"all"外，其余参数可以自由组合。默认为["all"]，即保存所有 dump 的数据。<br/> <b>配置示例</b>："data_mode": ["backward"] （仅保存反向数据）或 "data_mode": ["forward", "input"]（仅保存前向的输入数据）。</td></tr>
+    <tr><td>MindSpore 静态图场景：仅支持"all"、"input"和"output"参数，且各参数只能单独配置，不支持自由组合。<br/><b>配置示例</b>："data_mode": ["all"]。</td></tr>
+    <tr><td>summary_mode</td><td>控制 dump 文件输出的模式，str 类型，仅 PyTorch 与 MindSpore 动态图场景支持，可选参数：<br/> md5：dump 输出包含 CRC-32 值以及 API 统计信息的 dump.json 文件，用于验证数据的完整性；<br/> statistics：dump 仅输出包含 API 统计信息的 dump.json 文件，默认值。<br/><b>配置示例</b>："summary_mode": "md5"。</td><td>否</td></tr>
 </table>
 
-
-
+**说明**："summary_mode"配置为"md5"时，所使用的校验算法为CRC-32算法。
 
 ### 1.3 task 配置为 tensor
 
@@ -54,9 +55,6 @@
 | -------------- | ---------------------- | -------- |
 | scope          | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同。 | 否       |
 | list           | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同。 | 否       |
-| backward_input | 首次运行训练采集得到反向 API 输入的 dump 文件，list[str] 类型，仅支持 PyTorch 场景的 kernel dump，默认未配置。例如，若需要采集 Functional.conv2d.1 API 反向过程的输入输出，则需要在 dump 目录下查找命名包含 Functional.conv2d.1、backward 和 input 字段的 dump 文件。<br/>**配置示例**："backward_input": ["./npu_dump/step0/rank0/dump_tensor_data/Functional.conv2d.1.backward.input.0.pt"] | 否       |
-| list           | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同。另外，<br/> PyTorch 和 MindSpore 动态图场景配置 kernel_api，dump 前向和反向 API 的kernel_api 级别数据，其中 dump 反向 API 时需要配置 **backward_input** 参数。<br/>**前向 API 配置示例**："list": ["Tensor.permute.1.forward"]；<br/>**反向 API 配置示例**："list": ["Tensor.permute.1.forward"], "backward.input": ["./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"]。<br/> | 否       |
-| backward_input | 该输入文件为首次运行训练 dump 得到反向 API 输入的 dump 文件，list[str] 类型，仅 PyTorch 场景支持，默认未配置。例如若需要 dump Functional.conv2d.1 API 的反向过程的输入输出，则需要在 dump 目录下查找命名包含 Functional.conv2d.1、backward 和 input 字段的 dump 文件。<br/>**配置示例**："backward_input": ["./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"] | 否       |
 | data_mode      | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同 | 否       |
 | file_format    | tensor 数据的保存格式，str 类型，仅支持 MindSpore 静态图场景的 L2，不支持 L0 和 L1。可选参数：<br/> "bin"：dump 的 tensor 文件为二进制格式；<br/>"npy"：dump 的 tensor 文件后缀为 .npy，默认值。 | 否       |
 | online_run_ut<sup>a</sup>  | 在线预检模式开关，bool 类型，可选参数 true（开启）、false（关闭），默认未配置，表示关闭。配置为 true 表示开启在线预检。| 否 |
@@ -85,7 +83,7 @@
 
 ### 1.5 task 配置为 overflow_check
 
-PyTorch 与 MindSpore 动态图场景下，"level"须为"L1"；MindSpore 静态图场景下，"level"须为"L2"，且模型编译优化等级（jit_level）须为"O2"。
+PyTorch 与 MindSpore 动态图场景下，"level"须为"L0"或"L1"；MindSpore 静态图场景下，"level"须为"L2"，且模型编译优化等级（jit_level）须为"O2"。
 
 | 参数        | 解释                 | 是否必选 |
 | ------------- | ---------------------- | -------- |
@@ -112,7 +110,7 @@ PyTorch 与 MindSpore 动态图场景下，"level"须为"L1"；MindSpore 静态
     <tr><td>pert_mode</td><td>无标杆扰动因子，str 类型。可选参数：<br/>  "improve_precision"：对输入做升精度，默认值；<br/>        "add_noise"：对输入增加噪声；<br/>        "no_change"：不加扰动直接二次执行；<br/>        "bit_noise"：输入的末位比特翻转，MindSpore 场景不支持 BF16 类型的向量；<br/>        "change_value"：输入的张量首尾值调换；<br/>        "to_cpu"：在 CPU 等价执行（仅 PyTorch 场景支持）。<br/><b>配置示例</b>："pert_mode": "improve_precision"。</td><td>否</td></tr>
     <tr><td>handler_type</td><td>处理类型，可选参数：<br/> "check"：进行无标杆比对检查，默认值；<br/> "fix"：将扰动后的 API 输出结果覆盖原始 API 输出结果，尝试将 Loss 曲线恢复正常，该模式下不支持预热功能与反向过程，且仅支持"improve_precision"、"to_cpu"（ PyTorch 场景）两种扰动因子。<br/> <b>配置示例</b>："handler_type": "check"。</td><td>否</td></tr>
     <tr><td>fuzz_level</td><td>无标杆数据 dump 级别，即选择比对结果文件应输出的表头属性，当前仅支持取值为："L1"。输出结果详见 <a href="#161-无标杆比对数据存盘格式">1.6.1 无标杆比对数据存盘格式</a>。</td><td>否</td></tr>
-    <tr><td>fuzz_stage</td><td>比对过程，选择对 API 前向或反向进行无标杆比对，可选参数：<br/> "forward"：前向，默认值；<br/>  "backward"：反向, 仅 PyTorch 场景支持。当 fuzz_stage 为 "backward" 时，handler_type 只能为 "check"。<br/>  <b>配置示例</b>："fuzz_stage": "backward"。</td><td>否</td></tr>
+    <tr><td>fuzz_stage</td><td>比对过程，选择对 API 前向或反向进行无标杆比对，可选参数：<br/> "forward"：前向，默认值；<br/>  "backward"：反向。当 fuzz_stage 为 "backward" 时，handler_type 只能为 "check"。<br/>  <b>配置示例</b>："fuzz_stage": "backward"。</td><td>否</td></tr>
     <tr><td>if_preheat</td><td>预热功能（仅 PyTorch 场景支持），bool 类型。开启功能后工具可以根据每次迭代的输出调整精度算法的阈值，从而更准确地找出存在精度问题的 API。当"handler_type": "fix"时，不支持预热。可选参数：<br/>  true（开启）或 false（关闭），默认关闭。<br/>  <b>配置示例</b>："if_preheat": "true"。</td><td>否</td></tr>
     <tr><td>preheat_step</td><td>开启预热的迭代数量（仅 PyTorch 场景支持），int 类型，默认值为 15。须配置 "if_preheat": "true"。</td><td>否</td></tr>
     <tr><td>max_sample</td><td>每个算子预热的采样次数的最大阈值（仅 PyTorch 场景支持），int 类型，默认值为 20。须配置 "if_preheat": "true"。</td><td>否</td></tr>
@@ -135,3 +133,32 @@ PyTorch 与 MindSpore 动态图场景下，"level"须为"L1"；MindSpore 静态
 | dtype        | 输入的 dtype，string 类型。                                    |
 | shape        | 输入的 shape，tuple 类型。                                     |
 | output_index | 如果输出为列表或元组，其中一个元素检测不一致，则会有该元素的 index，否则为空，int 类型。 |
+
+
+### 1.7 task 配置为 grad_probe
+
+   **参数说明**
+
+   | 参数                       | 说明                          | 输入类型                     | 是否必选 |
+   |--------------------------------|-----------------------------------|-----------------|----------|
+   | task            | 填为"grad_probe"。 |  str | 是 |
+   | dump_path            | 输出目录。如果不存在就会创建一个新目录。 |  str | 是 |
+   | rank                   | rank id列表，在多卡场景下，表示需要导出梯度数据的进程的rank id。列表为空就表示导出所有rank的数据。默认为空。采集特定 rank 时，须指定为训练脚本中存在的 rank_id，可逐个配置，也可以指定范围。<br/>  **配置示例**："rank": [0, 1 , 2, "4-6"]。（MindSpore静态图模式下，当前暂不支持指定rank功能） | list[Union[int, str]] | 否       |
+   | step                   | step列表，表示需要导出数据的step列表。列表为空就表示导出所有step的数据。默认为空。采集特定 step 时，须指定为训练脚本中存在的 step，可逐个配置，也可以指定范围。<br/>  **配置示例**："step": [0, 1 , 2, "4-6"]。（MindSpore静态图模式下，当前暂不支持指定step功能） | list[Union[int, str]] | 否 |
+   | grad_level                  | 输出级别。决定导出数据的详细程度，级别越大导出数据越详细。可取值：L0, L1, L2。默认L1。|str  | 否     |
+   | param_list             | 权重名称列表，表示需要监控的权重。列表为空就表示监控所有权重。默认为空。 | List[str] | 否       |
+   | bounds                 | 区间列表，用来划分区间以统计数值的分布。需要保证由数据小到大排列，并且列表中的元素需要在int64取值范围内。可以使用默认值[-1, 0, 1]。 | List[float, int] | 否  |
+
+   
+   **不同级别的level的导出数据**
+
+
+   | 级别 | 特征数据表头                                                 | 是否有方向数据 |
+   | ---- | ------------------------------------------------------------ | -------------- |
+   | L0   | ("param_name", "MD5", "max", "min", "norm", "shape")         | 否             |
+   | L1   | ("param_name", "max", "min", "norm", "shape")         | 是             |
+   | L2   | ("param_name", *intervals, "=0", "max", "min", "norm", "shape") | 是             |
+
+   intervals就是根据值分布bounds划分出的区间。
+   MindSpore静态图模式下，L0级别中暂不支持"MD5"
+

msprobe/docs/03.config_examples.md

@@ -13,7 +13,6 @@
     "rank": [],
     "step": [],
     "level": "L1",
-    "enable_dataloader": false,
 
     "statistics": {
         "scope": [], 
@@ -33,13 +32,11 @@
     "rank": [],
     "step": [],
     "level": "L1",
-    "enable_dataloader": false,
 
     "tensor": {
         "scope": [],
         "list":[],
-        "data_mode": ["all"],
-        "backward_input": []
+        "data_mode": ["all"]
     }
 }
 ```
@@ -53,7 +50,6 @@
     "rank": [],
     "step": [],
     "level": "L1",
-    "enable_dataloader": false,
 
     "run_ut": {
         "white_list": [],
@@ -72,7 +68,6 @@
     "rank": [],
     "step": [],
     "level": "L1",
-    "enable_dataloader": false,
 
     "overflow_check": {
         "overflow_nums": 1
@@ -89,7 +84,6 @@
     "rank": [],
     "step": [],
     "level": "L1",
-    "enable_dataloader": false,
 
     "free_benchmark": {
         "scope": [], 
@@ -138,8 +132,7 @@
 
     "tensor": {
         "list":[],
-        "data_mode": ["all"],
-        "backward_input": []
+        "data_mode": ["all"]
     }
 }
 ```