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

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 rowspan="2">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 rowspan="2">否</td><tr><td>MindSpore静态图jit_level=O2场景L2级dump，支持上述配置的同时额外支持配置统计项列表，可选统计项为max、min、mean、l2norm，可从中任意选取组合搭配。其中mean、l2norm的结果为float数据格式。<br/><b>配置示例</b>："summary_mode": ["max", "min"]。</td></tr></tr>
 </table>
 
-
-
+**说明**："summary_mode"配置为"md5"时，所使用的校验算法为CRC-32算法。
 
 ### 1.3 task 配置为 tensor
 
@@ -54,11 +55,8 @@
 | -------------- | ---------------------- | -------- |
 | 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，默认值。 | 否       |
+| file_format    | tensor 数据的保存格式，str 类型，仅支持 MindSpore 静态图场景的 L2 级别配置该字段，其他场景不生效。可选参数：<br/> "bin"：dump 的 tensor 文件为二进制格式；<br/>"npy"：dump 的 tensor 文件后缀为 .npy，默认值。 | 否       |
 | online_run_ut<sup>a</sup>  | 在线预检模式开关，bool 类型，可选参数 true（开启）、false（关闭），默认未配置，表示关闭。配置为 true 表示开启在线预检。| 否 |
 | nfs_path<sup>a</sup> | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。仅在 online_run_ut 字段配置为 true 时生效，配置该参数后 host 和 port 不生效。 | 否 |
 | host<sup>a</sup> | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。仅在 online_run_ut 字段配置为 true 时生效，局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 |
@@ -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"]
     }
 }
 ```

msprobe/docs/04.kernel_dump_PyTorch.md

@@ -0,0 +1,73 @@
+# PyTorch 场景的 kernel dump 说明
+
+当使用 msprobe 数据采集功能时，level 配置为 "L2" 表示采集 kernel 层级的算子数据，仅支持昇腾 NPU 平台。 
+
+本文主要介绍 kernel dump 的配置示例和采集结果介绍， msprobe 数据采集功能的详细使用参考 《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》。
+
+## 1 kernel dump 配置示例
+
+使用 kernel dump 时，list 必须要填一个 API 名称，kernel dump 目前每个 step 只支持采集一个 API 的数据。
+API 名称填写参考 L1 dump 结果文件 dump.json 中的API名称，命名格式为：`{api_type}.{api_name}.{API调用次数}.{forward/backward}`。
+
+```json
+{
+    "task": "tensor",
+    "dump_path": "/home/data_dump",
+    "level": "L2",
+    "rank": [],
+    "step": [],
+    "tensor": {
+        "scope": [],
+        "list": ["Functional.linear.0.backward"]
+    }
+}
+```
+
+## 2 结果文件介绍
+
+### 2.1 采集结果说明
+    
+如果 API kernel 级数据采集成功，会打印以下信息：
+
+```bash
+The kernel data of {api_name} is dumped successfully.
+```
+
+注意：如果打印该信息后，没有数据生成，参考**常见问题3.1**进行排查。
+
+如果 kernel dump 遇到不支持的 API， 会打印以下信息：
+
+```bash
+The kernel dump does not support the {api_name} API.
+```
+
+其中 {api_name} 是对应溢出的 API 名称。
+
+### 2.2 输出文件说明
+kernel dump 采集成功后，会在指定的 dump_path 目录下生成如下文件：
+
+```
+├── /home/data_dump/
+│   ├── step0
+│   │   ├── 20241201103000    # 日期时间格式，表示2024-12-01 10:30:00
+│   │   │   ├── 0             # 表示 device id
+│   │   │   │   ├──{op_type}.{op_name}.{task_id}.{stream_id}.{timestamp}    # kernel 层算子数据
+│   │   │  ...
+│   │   ├── kernel_config_{device_id}.json    # kernel dump 在接口调用过程中生成的中间文件，一般情况下无需关注
+│   │  ...     
+│   ├── step1
+│  ...
+```
+成功采集到数据后，可以使用 msprobe 工具提供的《[PyTorch 场景的数据解析](./14.data_parse_PyTorch.md)》功能分析数据。
+
+## 3 常见问题
+
+#### 3.1 采集结果文件为空，有可能是什么原因？
+
+1. 首先需要确认工具使用方式、配置文件内容、list 填写的 API 名称格式是否都正确无误。
+
+2. 其次需要确认 API 是否运行在昇腾 NPU 上，如果是运行在其他设备上则不会存在 kernel 级数据。
+
+3. 如果排除上述两点仍然没有数据，您可以使用《[Ascend Extension for PyTorch 插件](https://gitee.com/ascend/pytorch)》提供的
+torch_npu.npu 接口进行 kernel 层数据采集，工具的 kernel dump 也是基于其中的init_dump、set_dump和finalize_dump三个子接口实现的。
+torch_npu.npu 接口详细描述见《[torch_npu.npu API 概述](https://www.hiascend.com/document/detail/zh/Pytorch/60RC3/apiref/apilist/ptaoplist_000192.html)》。

msprobe/docs/05.data_dump_PyTorch.md

@@ -2,6 +2,8 @@
 
 msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。
 
+dump的'tensor'模式采集数据量大小，可以参考[数据量基线](./26.data_dump_PyTorch_baseline.md)。
+
 本工具提供固定的 API 支持列表，若需要删除或增加 dump 的 API，可以在 msprobe/pytorch/hook_module/support_wrap_ops.yaml 文件内手动修改，如下示例：
 
 ```yaml
@@ -11,6 +13,8 @@ functional:  # functional为算子类别，找到对应的类别，在该类别
   - conv3d
 ```
 
+删除API的场景：部分模型代码逻辑会存在API原生类型校验，工具执行dump操作时，对模型的API封装可能与模型的原生API类型不一致，此时可能引发校验失败，详见《[FAQ](FAQ.md)》中“异常情况”的第10和11条。
+
 ## 1 接口介绍
 
 ### 1.1 PrecisionDebugger
@@ -23,8 +27,12 @@ functional:  # functional为算子类别，找到对应的类别，在该类别
 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"时，必须在该接口或 **start** 接口中配置该参数。其他参数均在 [config.json](../config.json) 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。
-2. 此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。
+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)。
+
+此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。
 
 ### 1.2 start
 
@@ -36,12 +44,16 @@ PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, model
 debugger.start(model=None)
 ```
 
-1.  model：指定具体的 torch.nn.Module，默认未配置，level 配置为"L0"或"mix"时，必须在该接口或 **PrecisionDebugger** 接口中配置该参数。
+1. model：指定需要采集 Module 级数据的模型，支持传入 torch.nn.Module 或 list[torch.nn.Module] 类型，默认未配置。
+level 配置为"L0"或"mix"时，必须在该接口或 **PrecisionDebugger** 接口中配置该参数。
 本接口中的 model 比 PrecisionDebugger 中 model 参数优先级更高，会覆盖 PrecisionDebugger 中的 model 参数。
 
 ### 1.3 stop
 
-**功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。若需要 dump 反向数据，则需要添加在反向计算代码（如，loss.backward）之后。使用示例可参见 [2.1 快速上手](#21-快速上手)和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
+**功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。
+若 **stop** 函数添加在反向计算代码（如loss.backward）之后，则会采集 **start** 和该函数之间的前反向数据。
+若 **stop** 函数添加在反向计算代码之前，则需要将 **step** 函数添加到反向计算代码之后，才能采集 **start** 和该函数之间的前反向数据。
+**step** 函数详细介绍见1.5章节。使用示例可参见 [2.1 快速上手](#21-快速上手) 和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
 
 **原型**：
 
@@ -51,7 +63,8 @@ debugger.stop()
 
 ### 1.4 forward_backward_dump_end
 
-**功能说明**：停止精度数据采集。用于 dump 指定代码的前反向数据。在 **start** 函数之后，反向计算代码（如，loss.backward）之前的任意位置添加，可以采集 **start** 函数和该函数之间的前反向数据，可以通过调整 **start** 函数与该函数的位置，来指定需要 dump 的代码块。要求 **stop** 函数添加在反向计算代码（如，loss.backward）之后，此时该函数与 **stop** 函数之间的代码不会被 dump。使用示例可参见 [2.3 采集指定代码块的前反向数据](#23-采集指定代码块的前反向数据)
+**功能说明**：停止精度数据采集。与 **stop** 函数功能相同，该函数在将来会被移除，建议使用 **stop** 函数。
+使用示例可参见 [2.3 采集指定代码块的前反向数据](#23-采集指定代码块的前反向数据)。
 
 **原型**：
 
@@ -61,7 +74,8 @@ forward_backward_dump_end()
 
 ### 1.5 step
 
-**功能说明**：更新 dump 参数。在最后一个 **stop** 函数后或一个 step 结束的位置添加。需要与 **start** 函数一起添加在 for 循环内。
+**功能说明**：结束一个 step 的数据采集，完成所有数据落盘并更新 dump 参数。在一个 step 结束的位置添加，且必须在 **stop** 函数之后的位置调用。
+该函数需要配合 **start** 和 **stop** 函数使用，尽量添加在反向计算代码（如loss.backward）之后，否则可能会导致反向数据丢失。使用示例可参见[2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。
 
 **原型**：
 
@@ -101,13 +115,18 @@ module_dump_end()
 
 **原型**：
 ```python
-seed_all(seed=1234, mode=False)
+seed_all(seed=1234, mode=False, rm_dropout=True)
 ```
 
 **参数说明**:
 
 1. seed: 随机性种子。参数示例: seed=1000。默认值：1234。非必选
 2. mode：确定性计算模式。可配置True或False。参数示例：mode=True。默认为False。非必选（注意：确定性计算会导致API执行性能降低，建议在发现模型多次执行结果不同的情况下开启）
+3. rm_dropout：控制dropout失效的开关。可配置 True 或 False，默认值：True，非必选。参数示例：rm_dropout=True。
+该参数设置为 True 后， 工具会自动将 `torch.nn.functional.dropout`、`torch.nn.functional.dropout2d`、`torch.nn.functional.dropout3d`、`torch.nn.Dropout`、`torch.nn.Dropout2d`、`torch.nn.Dropout3d` 
+的接口参数 p 置为0，以避免因随机dropout造成的网络随机性。 注意：通过rm_dropout控制dropout失效或生效需要在初始化dropout实例前调用才能生效。
+
+当前工具 dump 默认不会固定随机性和使 dropout 失效，若希望每次采集的数据保持一致，建议在 dump 数据前调用 seed_all 接口。
 
 seed_all 函数可固定随机数的范围如下表。
 
@@ -126,29 +145,30 @@ seed_all 函数可固定随机数的范围如下表。
 | torch.backends.cudnn.enable=False        | 关闭 cuDNN                   |
 | torch.backends.cudnn.benchmark=False     | cuDNN 确定性地选择算法       |
 | torch.backends.cudnn.deterministic=True  | cuDNN 仅使用确定性的卷积算法 |
+| torch.nn.functional.dropout              | 将 dropout 的接口参数 p 置为0 |
+| torch.nn.functional.dropout2d            | 将 dropout2d 的接口参数 p 置为0 |
+| torch.nn.functional.dropout3d            | 将 dropout3d 的接口参数 p 置为0 |
+| torch.nn.Dropout                         | 将 Dropout 的接口参数 p 置为0 |
+| torch.nn.Dropout2d                       | 将 Dropout2d 的接口参数 p 置为0 |
+| torch.nn.Dropout3d                       | 将 Dropout3d 的接口参数 p 置为0 |
 
 需要保证 CPU 或 GPU 以及 NPU 的模型输入完全一致，dump 数据的比对才有意义，seed_all 并不能保证模型输入完全一致，如下表所示场景需要保证输入的一致性。
 
 | 场景            | 固定方法      |
 | --------------- | ------------- |
 | 数据集的 shuffle | 关闭 shuffle。 |
-| dropout         | 关闭 dropout。 |
 
 关闭 shuffle 示例：
 
 ```python
 train_loader = torch.utils.data.DataLoader(
-train_dataset,
-batch_size = batch_size,
-shuffle = False,
-num_workers = num_workers
+    train_dataset,
+    batch_size=batch_size,
+    shuffle=False,
+    num_workers=num_workers
 )
 ```
 
-关闭 dropout：
-
-在使用 `from msprobe.pytorch import PrecisionDebugger` 后，工具会自动将 `torch.nn.functional.dropout`、`torch.nn.functional.dropout2d`、`torch.nn.functional.dropout3d`、`torch.nn.Dropout`、`torch.nn.Dropout2d`、`torch.nn.Dropout3d` 的接口参数 p 置为0.
-
 ## 2 示例代码
 
 ### 2.1 快速上手
@@ -159,38 +179,43 @@ num_workers = num_workers
 # 根据需要import包
 import torch
 import torch.nn as nn
-import torch_npu  # 需安装 torch_npu
 import torch.nn.functional as F
+
+# 导入工具的数据采集接口
 from msprobe.pytorch import PrecisionDebugger, seed_all
+
 # 在模型训练开始前固定随机性
 seed_all()
+# 在模型训练开始前实例化PrecisionDebugger
+debugger = PrecisionDebugger(config_path='./config.json')
 
-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)
+        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):
+    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()
+    module = ModuleOP()
+    # 开启数据 dump
+    debugger.start(model=module)
 
+    x = torch.randn(10, 8)
+    out = module(x)
+    loss = out.sum()
+    loss.backward()
+
+    # 关闭数据 dump
+    debugger.stop()
 ```
+
 ### 2.2 采集完整的前反向数据
 
 ```Python
@@ -203,19 +228,20 @@ debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path
 # ...
 # 数据集迭代的位置一般为模型训练开始的位置
 for data, label in data_loader:
-	debugger.start() # 开启数据dump
-	# 如下是模型每个step执行的逻辑
+    debugger.start()  # 开启数据dump
+    # 如下是模型每个step执行的逻辑
     output = model(data)
     #...
     loss.backward()
-	debugger.stop() # 关闭数据dump
-	debugger.step() # 结束一个step的dump
+    debugger.stop()  # 关闭数据dump
+    debugger.step()  # 结束一个step的dump
 ```
 
 ### 2.3 采集指定代码块的前反向数据
 
 ```Python
 from msprobe.pytorch import PrecisionDebugger, seed_all
+
 # 在模型训练开始前固定随机性
 seed_all()
 # 请勿将PrecisionDebugger的初始化流程插入到循环代码中
@@ -225,14 +251,14 @@ debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path
 # ...
 # 数据集迭代的位置一般为模型训练开始的位置
 for data, label in data_loader:
-	debugger.start() # 开启数据dump
-	# 如下是模型每个step执行的逻辑
+    debugger.start()  # 开启数据dump
+    # 如下是模型每个step执行的逻辑
     output = model(data)
-    debugger.forward_backward_dump_end() # 插入该函数到start函数之后，只dump start函数到该函数之间代码的前反向数据，本函数到stop函数之间的数据则不dump
-    #...
+    
+    debugger.forward_backward_dump_end()  # 插入该函数到start函数之后，只dump start函数到该函数之间的前反向数据。
+    # ...
     loss.backward()
-	debugger.stop() # 关闭数据dump
-	debugger.step() # 结束一个step的dump
+    debugger.step()  # 结束一个step的dump
 ```
 
 ### 2.4 采集函数模块化数据
@@ -241,11 +267,14 @@ for data, label in data_loader:
 # 根据需要import包
 import torch
 import torch.nn as nn
-import torch_npu  # 需安装 torch_npu
 import torch.nn.functional as F
+
+# 导入工具的数据采集接口
 from msprobe.pytorch import PrecisionDebugger, module_dump, module_dump_end
 
-torch.npu.set_device("npu:0")
+# 在模型训练开始前实例化PrecisionDebugger
+debugger = PrecisionDebugger(config_path='./config.json')
+
 # 定义网络
 class ModuleOP(nn.Module):
     def __init__(self) -> None:
@@ -261,37 +290,37 @@ class ModuleOP(nn.Module):
 
 if __name__ == "__main__":
     module = ModuleOP()
-    # 注册工具
-    debugger = PrecisionDebugger(config_path='./config.json')
-    debugger.start()                   # 开启数据dump
-    
-    x = torch.randn(10, 8)             
+    # 开启数据dump
+    debugger.start()
+    x = torch.randn(10, 8)
     # ...                              # start和module_dump接口之间的数据正常dump
     module_dump(module, "MyModuleOP")  # 开启模块级精度数据dump
-    out = module(x)                    # module内部的child modules或API不会被dump
+    out = module(x)                    # module内部的child modules或API将不会被dump
     module_dump_end()                  # 关闭模块级精度数据dump
     loss = out.sum()                   # module_dump_end和stop接口之间的数据正常dump
-    loss.backward()          
-
-    debugger.stop()                    # 关闭数据dump
+    loss.backward()
+    # 关闭数据dump
+    debugger.stop()  
 ```
 
 ## 3 dump 结果文件介绍
 
 训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。目录结构示例如下：
 
-```Python
+```lua
 ├── dump_path
 │   ├── step0
 │   |   ├── rank0
 │   |   │   ├── dump_tensor_data
 |   |   |   |    ├── Tensor.permute.1.forward.pt
-|   |   |   |    ├── MyModule.0.forward.input.pt        # 开启模块级精度数据dump时存在模块级的dump数据文件
+|   |   |   |    ├── 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}。因为同一模块的参数使用同一梯度进行更新，所以参数梯度文件名不包含调用次数。
 |   |   |   |    ...
-|   |   |   |    └── 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        # 分层分级结构
+|   |   |   |    └── 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个元素。
+│   |   |   ├── dump.json       
+│   |   |   ├── stack.json        
+│   |   |   └── construct.json        
 │   |   ├── rank1
 |   |   |   ├── dump_tensor_data
 |   |   |   |   └── ...
@@ -304,7 +333,13 @@ if __name__ == "__main__":
 │   ├── step1
 │   |   ├── ...
 │   ├── step2
-```
+```  
+* `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)。
+* `stack.json`：API/Module的调用栈信息。
+* `construct.json`：分层分级结构，level为L1时，construct.json内容为空。  
+
 
 dump 过程中，pt 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。
 
@@ -321,6 +356,3 @@ pt 文件保存的前缀和 PyTorch 对应关系如下：
 | VF          | torch._VF           |
 | Aten        | torch.ops.aten      |
 | Distributed | torch.distributed   |
-
-
-