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

msprobe/docs/01.installation.md

@@ -0,0 +1,99 @@
+# 安装
+
+推荐使用 [miniconda](https://docs.anaconda.com/miniconda/) 管理环境依赖。
+
+```bash
+conda create -n msprobe python
+conda activate msprobe
+```
+
+## 1 从 PyPI 安装
+```shell
+pip install mindstudio-probe
+```
+
+## 2 下载 whl 包安装
+
+|版本|发布日期|支持 PyTorch 版本|支持 MindSpore 版本|下载链接|校验码|
+|:--:|:--:|:--:|:--:|:--:|:--:|
+|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 |
+| 1.0.1 | 2024.07.25 | 2.0/2.1/2.2 | 2.4.0 | [mindstudio_probe-1.0.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.1-py3-none-any.whl) | b699e224e4d4e3bcf9412c54fa858a1ee370f0d7a2bc69cb3f1273ac14a6dc82 |
+
+
+```bash
+sha256sum {name}.whl # 验证whl包，若校验码一致，则whl包在下载中没有受损
+```
+
+```bash
+pip install ./mindstudio_probe-{version}-py3-none-any.whl # 安装whl包
+```
+
+若覆盖安装，请在命令行末尾添加 `--force-reinstall` 参数。
+
+## 3 从源码安装
+
+```shell
+git clone https://gitee.com/ascend/mstt.git
+cd mstt/debug/accuracy_tools
+
+pip install setuptools wheel
+
+python setup.py bdist_wheel
+cd ./dist
+pip install ./mindstudio_probe*.whl
+```
+
+# 历史版本特性
+
+<table>
+    <tr><th>版本</th><th>特性</th></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 工具信息
+
+```bash
+pip show mindstudio-probe
+```
+
+示例如下：
+
+```bash
+Name: mindstudio-probe
+Version: 1.0.x
+Summary: Pytorch Ascend Probe Utils
+Home-page: https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe
+Author: Ascend Team
+Author-email: pmail_mindstudio@huawei.com
+License: Apache License 2.0
+Location: /home/xxx/miniconda3/envs/xxx/lib/python3.x/site-packages/mindstudio_probe-1.0.x-py3.x.egg
+Requires: einops, matplotlib, numpy, openpyxl, pandas, pyOpenSSL, pyyaml, rich, tqdm, twisted, wheel
+Required-by: 
+```
+
+# Ascend 生态链接
+
+## 1 安装 CANN 包
+
+1.1 根据 CPU 架构和 NPU 型号选择 toolkit 和 kernel，可以参考 [CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)和[昇腾社区](https://www.hiascend.cn/developer/download/community/result?module=cann)。
+
+1.2 运行示例
+```bash
+Ascend-cann-toolkit_x.x.x_linux-xxxx.run --full --install-path={cann_path}
+Ascend-cann-kernels_x.x.x_linux.run --install --install-path={cann_path}
+```
+
+1.3 配置环境变量
+```bash
+source {cann_path}/ascend-toolkit/set_env.sh
+```
+## 2 安装 PyTorch_NPU 
+
+链接：[https://gitee.com/ascend/pytorch](https://gitee.com/ascend/pytorch)。
+
+## 3 安装 ModelLink
+
+链接：[https://gitee.com/ascend/ModelLink](https://gitee.com/ascend/ModelLink)。

msprobe/docs/02.config_introduction.md

@@ -0,0 +1,137 @@
+# 配置文件介绍
+
+- 当调用 **PrecisionDebugger** 接口执行 dump 或其他操作时，需要使用 [config.json](../config.json) 文件；当未指定 config.json 时，将使用默认配置。
+- msprobe 成功安装后，config.json 一般位于如下目录：
+```
+/home/xxx/miniconda3/envs/xxx/lib/python3.xx/site-packages/msprobe/
+```
+
+## 1 参数介绍
+
+### 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 不全问题。 | 否       |
+
+#### 1.1.1 模块级精度数据 dump 说明
+
+仅 PyTorch 与 MindSpore 动态图场景支持。
+
+大模型场景下，通常不是简单的利用自动迁移能力实现从 GPU 到 NPU 的训练脚本迁移，而是会对 NPU 网络进行一系列针对性的适配，因此，常常会造成迁移后的 NPU 模型存在部分子结构不能与 GPU 原始模型完全对应。模型结构不一致导致 API 调用类型及数量不一致，若直接按照 API 粒度进行精度数据 dump 和比对，则无法完全比对所有的 API。
+
+本小节介绍的功能是对模型中的大粒度模块进行数据 dump，使其比对时，对于无法以 API 粒度比对的模块可以直接以模块粒度进行比对。
+
+模块指的是继承 nn.Module 类（PyTorch场景）或 nn.Cell 类（MindSpore场景）的子类，通常情况下这类模块就是一个小模型，可以被视为一个整体，dump 数据时以模块为粒度进行 dump。
+
+### 1.2 task 配置为 statistics
+
+<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 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>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>
+</table>
+
+
+
+
+### 1.3 task 配置为 tensor
+
+| 参数         | 解释         | 是否必选 |
+| -------------- | ---------------------- | -------- |
+| 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 表示开启在线预检。| 否 |
+| 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 参数，否则局域网场景不生效。 | 否 |
+| port<sup>a</sup> | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。仅在 online_run_ut 字段配置为 true 时生效，局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。| 否 |
+
+**a**：online_run_ut、nfs_path、host、port 等字段仅在线预检场景 NPU 机器生效。
+
+### 1.4 task 配置为 run_ut
+
+| 参数        | 解释                   | 是否必选 |
+| --------------- | ------------------------ | ------------ |
+| white_list<sup>a</sup>      | API dump 白名单，仅对指定的 API 进行 dump。<br/>**配置示例**："white_list": ["conv1d", "conv2d"]。默认未配置白名单，即 dump 全量 API 数据。 | 否       |
+| black_list<sup>a</sup>      | API dump 黑名单，被指定的 API 不进行 dump。<br/>**配置示例**："black_list": ["conv1d", "conv2d"]。默认未配置黑名单，即 dump 全量 API 数据。 | 否       |
+| error_data_path | 配置保存精度未达标的 API 输入输出数据路径，默认为当前路径。<br/>**配置示例**："error_data_path": "./"。 | 否       |
+| is_online<sup>b</sup>       | 在线预检模式开关，bool 类型，可选参数 true（开启）、false（关闭），默认关闭。 | 否 |
+| nfs_path<sup>b</sup>        | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效，仅在 is_online 字段配置为 true 时生效。 | 否    |
+| host<sup>b</sup>            | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。仅在 is_online 字段配置为 true 时生效。 | 否 |
+| port<sup>b</sup>            | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。仅在 is_online 字段配置为 true 时生效。| 否 |
+| rank_list<sup>b</sup>       | 指定在线预检的 Rank ID，默认值为 [0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。仅在 is_online 字段配置为 true 时生效。 | 否    |
+
+**a**：white_list 和 black_list 同时配置时，二者配置的 API 名单若无交集，则白名单生效，若 API 名单存在交集，则白名单排除的部分以及交集的 API 不进行 dump。
+
+**b**：is_online、nfs_path、host、port、rank_list 等字段仅在线预检场景 GPU 机器生效。
+
+### 1.5 task 配置为 overflow_check
+
+PyTorch 与 MindSpore 动态图场景下，"level"须为"L1"；MindSpore 静态图场景下，"level"须为"L2"，且模型编译优化等级（jit_level）须为"O2"。
+
+| 参数        | 解释                 | 是否必选 |
+| ------------- | ---------------------- | -------- |
+| overflow_nums | 最大溢出次数，int 类型，默认为 1，仅 PyTorch 与 MindSpore 动态图场景支持。表示第 N 次溢出后，不再进行溢出检测。过程中检测到溢出 API 对应的 输入输出 数据均 dump。<br/>**配置示例**："overflow_nums": 3。配置为 -1 时，表示持续检测溢出直到训练结束。 | 否       |
+| check_mode    | 溢出类型，str 类型，仅 MindSpore 场景支持，可选参数：<br/>"aicore"：开启 AI Core 的溢出检测，不支持 MindSpore v2.3.0 以上版本；<br/>"atomic"：开启 Atomic 的溢出检测，不支持 MindSpore v2.3.0 以上版本；<br/>"all"：开启算子的溢出检测，默认值。<br/>**配置示例**："check_mode": "all"。 | 否       |
+
+### 1.6 task 配置为 free_benchmark
+
+仅 PyTorch 场景与 MindSpore 动态图场景支持，且"level"为"L1"。
+
+- task 配置为 free_benchmark 时，开启**无标杆比对**，在 NPU 环境下通过对当前模型 API 的输入添加扰动因子，二次执行，将得到的输出与未添加扰动因子前的输出进行比对，从而**得出该模型中可能存在因迁移等变化导致精度降低的 API**。
+
+- 无标杆比对优势在于省去了从 CPU/GPU 环境获取标杆数据的步骤，也省去了在 NPU 环境执行 dump 的操作，降低了精度比对的操作难度。
+
+- 建议配置白名单（配置 scope 或 list）控制少量 API 进行无标杆比对，一次对过多 API 执行无标杆比对可能导致显存溢出或性能膨胀。
+
+<table>
+    <tr><th>参数</th><th>解释</th><th>是否必选</th></tr>
+    <tr><td>scope</td><td>自定义检测 API 列表（仅 PyTorch 场景支持），list[str] 类型，默认值为空列表，当 list 也为空列表时，表示检测所有 API。需要在 [ ] 内配置具体 API 名（在 dump 的结果中查看）。与 list 参数不能同时配置。<br/><b>配置示例</b>："scope": ["Torch.matmul.0.forward", "Tensor.pow.4.forward"]。</td><td>否</td></tr>
+    <tr><td rowspan="3">list</td><td>自定义检测 API 类型或 API 名称，list[str] 类型，默认值为空列表，表示检测所有 API（PyTorch 场景下还需 scope 也为空列表）。与 scope 参数不能同时配置。</td><td rowspan="3">否</td></tr>
+    <tr><td>PyTorch 场景：指定某一类 API，对某一类的 API 进行无标杆比对。<br/><b>配置示例</b>："list": ["relu"]。</td></tr>
+    <tr><td>MindSpore 场景：指定 API 名称，对列表中的 API 进行检测。<br/><b>配置示例</b>："list": ["mindspore.mint.div", "mindspore.ops.bmm", "mindspore.Tensor.__add__"]。</td></tr>
+    <tr><td>fuzz_device</td><td>标杆设备，str 类型。可选参数：<br/>        "npu"：无标杆，通过添加扰动因子进行比对，默认值；<br/>        "cpu"：以 CPU 为标杆，pert_mode 须配置为"to_cpu"（仅 PyTorch 场景支持）。<br/><b>配置示例</b>："fuzz_device": "npu"。</td><td>否</td></tr>
+    <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>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>
+</table>
+
+#### 1.6.1 无标杆比对数据存盘格式
+
+无标杆比对在 dump_path 目录下输出结果文件 `free_benchmark.csv`，如下示例：
+
+![free_benchmark](./img/free_benchmark.png)
+
+| 字段         | 解释                                                         |
+| ------------ | --------------------- |
+| rank         | Rank ID，int 类型。                                           |
+| pert_mode    | 扰动因子的类型，string 类型。                                 |
+| stage        | 前向或反向，string 类型。                                     |
+| step         | 迭代数，int 类型。                                            |
+| api_name     | API 名称，string 类型。                                        |
+| max_rel      | 输出对比最大相对误差，float 类型。                            |
+| dtype        | 输入的 dtype，string 类型。                                    |
+| shape        | 输入的 shape，tuple 类型。                                     |
+| output_index | 如果输出为列表或元组，其中一个元素检测不一致，则会有该元素的 index，否则为空，int 类型。 |

msprobe/docs/03.config_examples.md

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

msprobe/docs/04.acl_config_examples.md

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