mindstudio-probe 8.2.0__py3-none-any.whl → 8.3.0__py3-none-any.whl

msprobe/docs/02.config_introduction.md

@@ -73,7 +73,14 @@
 | data_mode      | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同 | 否       |
 | file_format    | tensor 数据的保存格式，str 类型，仅支持 MindSpore 静态图场景的 L2 级别配置该字段，其他场景不生效。可选参数：<br/> "bin"：dump 的 tensor 文件为二进制格式；<br/>"npy"：dump 的 tensor 文件后缀为 .npy，默认值。 | 否       |
 | summary_mode  | 控制 dump 文件输出的模式，str 类型，支持 PyTorch、MSAdapter、MindSpore 动态图。可选参数：<br/> md5：dump 输出包含 CRC-32 值以及 API 统计信息的 dump.json 文件，用于验证数据的完整性；<br/> statistics：dump 仅输出包含 API 统计信息的 dump.json 文件，默认值。| 否 |
+| 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 参数，否则局域网场景不生效。| 否 |
 
+**说明**：
+
+1. online_run_ut、nfs_path、host、port 等字段仅在线预检场景 NPU 机器生效。
 
 **示例**：
  - [PyTorch场景](03.config_examples.md#12-task-配置为-tensor)
@@ -88,11 +95,17 @@
 | 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 时生效。 | 否    |
 
 **说明**：
 
 1. white_list 和 black_list 同时配置时，二者配置的 API 名单若无交集，则白名单生效，若 API 名单存在交集，则白名单排除的部分以及交集的 API 不进行 dump。
 
+2. is_online、nfs_path、host、port、rank_list 等字段仅在线预检场景 GPU 机器生效。
 
 **示例**：
 ```json
@@ -145,7 +158,7 @@ PyTorch、MSAdapter 以及 MindSpore 动态图场景下，"level"须为"L0"或"L
     <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"：反向。当 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"。pytorch场景下，当 fuzz_stage 为 "backward" 时， list 参数不能为空。<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>

msprobe/docs/04.kernel_dump_PyTorch.md

@@ -68,6 +68,6 @@ kernel dump 采集成功后，会在指定的 dump_path 目录下生成如下文
 
 2. 其次需要确认 API 是否运行在昇腾 NPU 上，如果是运行在其他设备上则不会存在 kernel 级数据。
 
-3. 如果排除上述两点仍然没有数据，您可以使用《[Ascend Extension for PyTorch 插件](https://gitee.com/ascend/pytorch)》提供的
+3. 如果排除上述两点仍然没有数据，您可以使用《[Ascend Extension for PyTorch 插件](https://gitcode.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/06.data_dump_MindSpore.md

@@ -88,7 +88,7 @@ PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, step=
 
 #### 6.1.1 start
 
-**功能说明**：启动精度数据采集。静态图场景下，必须在mindspore.communication.init 调用前添加。如果没有使用 [Model](https://gitee.com/link?target=https%3A%2F%2Fwww.mindspore.cn%2Ftutorials%2Fzh-CN%2Fr2.3.1%2Fadvanced%2Fmodel.html) 高阶 API 进行训练，则需要与 stop 函数一起添加在 for 循环内，否则只有需要传入model参数时，才使用该接口。
+**功能说明**：启动精度数据采集。静态图场景下，必须在mindspore.communication.init 调用前添加。如果没有使用 [Model](https://www.mindspore.cn/tutorials/zh-CN/r2.3.1/advanced/model.html) 高阶 API 进行训练，则需要与 stop 函数一起添加在 for 循环内，否则只有需要传入model参数时，才使用该接口。
 
 **原型**：
 

msprobe/docs/08.accuracy_checker_online_PyTorch.md

@@ -0,0 +1,295 @@
+# PyTorch 场景的在线精度预检
+
+## 1 简介
+
+为了应对大模型场景下，通过离线预检方式 dump API 输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行 NPU 训练操作的过程中，通过 TCP/IP 协议在 NPU
+Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择两方比对或三方比对。
+
+## 2 在线精度预检流程
+
+在线精度预检当前支持**局域网场景**和**共享存储场景**，请根据不同的场景选择对应的配置。
+
+在线精度预检操作流程如下：
+
+1. 准备 GPU 和 NPU 可正常运行的训练环境，PyTorch 版本大于等于2.0，并保证两台 Host 在同一局域网内可正常通信或能通过共享存储进行通信。
+2. GPU 和 NPU Host 设备上同时安装msprobe工具，详见[ msprobe 安装](./01.installation.md)章节，其中在线预检要安装 twisted、pyOpenSSL，这些包为 Python 模块。
+3. 分别配置 GPU 侧、NPU 侧的 config.json 文件。
+4. 在 GPU 侧运行 `msprobe -f pytorch run_ut -config ./config.json`。
+5. 在 NPU 侧配置训练脚本。
+6. 在 NPU 侧执行训练。
+
+## 3 在线精度预检操作指导
+
+### 3.1 配置 config.json 文件
+
+预检工具安装完成后，需要在 GPU 和 NPU 环境下分别配置 config.json。其中需要重点关注文件中的 is_online、is_benchmark_device、host 和 port 参数的配置，保障在线预检时 GPU 和 NPU 两台设备间的通信正常。
+
+#### 3.1.1 GPU 侧在线预检配置说明
+
+| 参数名称            | 说明           | 是否必选 |
+|-----------------|--------------|------|
+| task            | 任务名称，str 类型，配置为 run_ut 表示预检任务。通过其他字段 is_online 判断离线预检、在线预检任务。          | 是    |
+| white_list      | 预检的 API 白名单，list[str] 类型。<br/>**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置白名单，即预检全量 API 数据。       | 否    |
+| black_list      | 预检的 API 黑名单，list[str] 类型。<br/>**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置黑名单，即预检全量 API 数据。         | 否    |
+| error_data_path | 配置保存精度未达标的 API 输入输出数据路径，str 类型。在线预检模式下该参数不生效。         | 否    |
+| is_online       | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。              | 是    |
+| nfs_path        | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host、port 和 tls_path 不生效。   | 否    |
+| host            | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。            | 否    |
+| port            | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
+| rank_list       | 指定在线预检的 Rank ID，默认值为 [0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。 | 是    |
+| tls_path        | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥 server.key、证书 server.crt、自建CA证书 ca.crt、CRL吊销证书 crl.pem，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。其中 crl.pem 为非必需文件，仅当用户存在吊销记录时使用。 | 否    |
+
+
+#### 3.1.2 NPU 侧在线预检配置说明
+
+| 参数名称             | 说明           | 是否必选 |
+|------------------|-------------|------|
+| task             | 任务名称，str 类型，配置为 tensor 表示 dump API 统计信息和完全复刻整网的 API 运行情况的真实数据。通过字段 online_run_ut 判断是否使用在线预检功能。      | 是    |
+| dump_path        | dump 路径，str 类型，配置为合法路径即可，兼容 tensor 任务静态检查。       | 是    |
+| level            | dump 级别，str 类型，在线预检时配置为 L1，表示 dump API 级精度数据。在线预检可不配置，默认取值 L1。                                               | 是    |
+| rank             | 指定对某张卡上的数据进行 dump，list[int] 类型，默认未配置(表示 dump所有卡的数据)，需要与 GPU 侧配置项 rank_list 保持一致。   | 否    |
+| step             | 指定 dump 某个 step 的数据，list[int] 类型，默认未配置，表示 dump 所有 step 的数据。dump 特定 step 时，须指定为训练脚本中存在的 step。   | 否    |
+| scope            | dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。    | 否    |
+| list             | dump 范围，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。 | 否    |
+| online_run_ut    | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。        | 是    |
+| nfs_path         | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效。     | 否    |
+| host             | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。     | 否    |
+| port             | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。        | 否    |
+| tls_path         | 在线预检模式局域网场景 SSL 证书路径，该路径下包含私钥 client.key、证书 client.crt、自建CA证书 ca.crt、CRL吊销证书 crl.pem，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。其中 crl.pem 为非必需文件，仅当用户存在吊销记录时使用。 | 否    |
+| online_run_ut_recompute | 模型训练是否使用重计算机制，bool类型，默认为False，表示模型没有使用重计算。在线预检暂不支持重计算机制下反向算子的预检，当模型训练使用重计算时，跳过反向算子预检，默认模型关闭重计算。 | 否    |
+
+#### 3.1.3 局域网场景配置示例
+
+若采用 TLS1.2 协议加密传输 api 数据，需配置 SSL 证书，可参考如下生成自签名证书方法。
+
+以下秘钥生成方法仅为简单示例，客户应使用与自己需求相符的秘钥生成和存储机制并保证秘钥安全性与机密性，必要时可采用分层秘钥机制。
+以下示例中加密口令仅供参考，使用时请更换为复杂口令，并保护口令安全。
+```shell
+# 生成CA证书的根私钥和证书签名请求，其中ca_password为CA私钥加密口令，仅作演示，请更换使用
+openssl req -new -newkey rsa:3072 -passout pass:ca_password -subj "/CN=*ca.com/O=ca.Inc./C=CN/ST=Zhejiang/L=Hangzhou" -keyout ca.key -out ca.csr
+# 自签发根证书
+openssl x509 -req -days 365 -in ca.csr -signkey ca.key -passin pass:ca_password -out ca.crt -extensions v3_ca -extfile <(cat <<-EOF
+[v3_ca]
+basicConstraints = critical,CA:true
+keyUsage = critical, keyCertSign, cRLSign
+EOF
+)
+
+# 生成client公私钥，其中client_password为私钥加密口令，仅作演示，请更换使用
+openssl genrsa -aes256 -passout pass:client_password -out client.key 3072
+# 基于client公私钥生成签名请求
+openssl req -new -key client.key -passin pass:client_password -subj "/CN=*example.com/O=Test, Inc./C=CN/ST=Zhejiang/L=Hangzhou" -out client.csr
+# 利用自签发的根证书，签发client证书
+openssl x509 -req -days 180 -CA ca.crt -CAkey ca.key -passin pass:ca_password -in client.csr -out client.crt -CAcreateserial -extfile <(cat <<-EOF
+[v3_server]
+basicConstraints = CA:FALSE
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+EOF
+)
+
+# 生成server公私钥，其中server_password为私钥加密口令，仅作演示，请更换使用
+openssl genrsa -aes256 -passout pass:server_password -out server.key 3072
+# 基于server公私钥生成签名请求
+openssl req -new -key server.key -passin pass:server_password -subj "/CN=*example.com/O=Test, Inc./C=CN/ST=Zhejiang/L=Hangzhou" -out server.csr
+# 利用自签发的根证书，签发server证书
+openssl x509 -req -days 180 -CA ca.crt -CAkey ca.key -passin pass:ca_password -in server.csr -out server.crt -CAcreateserial -extfile <(cat <<-EOF
+[v3_server]
+basicConstraints = CA:FALSE
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+EOF
+)
+
+```
+
+当需要吊销已创建的SSL证书时，通过openssl命令生成CRL证书 crl.pem，示例如下：
+```shell
+# 创建证书信息的文本数据库，空文件即可
+touch index.txt
+
+# 创建ca配置文件ca.cnf，内容如下，用于吊销证书使用
+[ca]
+default_ca = CA_default
+[CA_default]
+database = ./index.txt
+default_md = sha256
+
+# 吊销证书 client.crt，其中ca_password为CA私钥加密口令，与CA创建时保持一致
+openssl ca -revoke client.crt -config ca.cnf -cert ca.crt -keyfile ca.key -passin pass:ca_password
+# 生成CRL文件
+openssl ca -gencrl -config ca.cnf -cert ca.crt -keyfile ca.key -passin pass:ca_password -out crl.pem -crldays 30
+# 查看生成的CRL文件内容：
+openssl工具的命令： openssl crl -inform PEM -in crl.pem -text
+
+```
+
+注意：配置TLS协议时，传输性能受机器环境和网络质量的影响，可能触发NPU超时中断模型训练，为避免训练和预检中断，丢弃长时间未传输的api数据，同时NPU侧配置HCCL环境变量，配置方式如下：
+
+a) 调整HCCL环境变量，关闭看门狗，避免WorkHCCL超时中断模型训练:
+```shell
+export HCCL_DESYNC_DEBUG=0
+export HCCL_ASYNC_ERROR_HANDLING=0
+```
+b) 调整通信算子超时设置（以1800s举例）：
+```shell
+export HCCL_CONNECT_TIMEOUT=1800
+export HCCL_EXEC_TIMEOUT=1800
+```
+
+GPU 侧：
+
+```json
+{
+  "task": "run_ut",
+  "run_ut": {
+    "white_list": [],
+    "black_list": [],
+    "error_data_path": "./",
+    "is_online": true,
+    "nfs_path": "",
+    "host": "127.0.0.1",
+    "port": 59208,
+    "rank_list": [0],
+    "tls_path": ""
+  }
+}
+```
+
+NPU 侧：
+
+```json
+{
+  "task": "tensor",
+  "dump_path": "./dump_path",
+  "rank": [0],
+  "step": [0],
+  "level": "L1",
+  "tensor": {
+    "scope": [],
+    "list": [],
+    "online_run_ut": true,
+    "nfs_path": "",
+    "host": "xx.xx.xx.x",
+    "port": 59208,
+    "tls_path": ""
+  }
+}
+```
+
+#### 3.1.4 共享存储场景配置示例
+
+GPU 侧：
+
+```json
+{
+  "task": "run_ut",
+  "run_ut": {
+    "white_list": [],
+    "black_list": [],
+    "error_data_path": "./",
+    "is_online": true,
+    "nfs_path": "/nfs/xxx/data",
+    "host": "",
+    "port": -1,
+    "rank_list": [0],
+    "tls_path": ""
+  }
+}
+```
+
+NPU 侧：
+
+```json
+{
+  "task": "tensor",
+  "dump_path": "./dump_path",
+  "rank": [0],
+  "step": [0],
+  "level": "L1",
+  "tensor": {
+    "scope": [],
+    "list": [],
+    "online_run_ut": true,
+    "nfs_path": "/nfs/xxx/data",
+    "host": "",
+    "port": -1,
+    "tls_path": ""
+  }
+}
+```
+
+### 3.2 在 GPU 侧运行 run_ut
+
+由于 GPU 侧为通信接收端，需先于 NPU 侧执行 run_ut 操作，命令如下：
+
+```bash
+msprobe -f pytorch run_ut -config ./config.json
+```
+
+GPU 侧配置好 config.json 文件后执行 run_ut 命令，此时 GPU 处于预检等待状态：
+
+- 局域网场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到 GPU 侧时，GPU 启动预检操作。
+- 共享存储场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到共享存储时，GPU 启动预检操作。
+
+### 3.3 在 NPU 侧配置训练脚本
+
+在 NPU 训练脚本中添加如下代码以获取 run_ut 操作的预检 API 输入和输出数据：
+
+```python
+from msprobe.pytorch import PrecisionDebugger
+
+debugger = PrecisionDebugger("config.json")
+...
+
+debugger.start()
+
+...
+
+debugger.stop()
+debugger.step()
+```
+
+### 3.4 在 NPU 侧执行训练脚本
+
+配置完 NPU 侧训练脚本后即可执行训练脚本，命令示例如下：
+
+```bash
+bash train.sh
+```
+
+训练脚本执行完毕后，在GPU侧dump_path目录下生成比对结果文件，`accuracy_checking_result_{timestamp}_rank{rank_id}.csv`和`accuracy_checking_details_{timestamp}_rank{rank_id}.csv`记录两方比对结果，`api_precision_compare_result_{timestamp}_rank{rank_id}.csv`和`api_precision_compare_details_{timestamp}_rank{rank_id}.csv`记录三方比对结果。详细介绍请参见[离线精度预检中的 **4 预检结果**](./07.accuracy_checker_PyTorch.md#4-预检结果)。
+
+## 4 支持的融合算子列表
+
+预检工具当前支持的融合算子如下：
+
+- npu_apply_adam_w
+
+- npu_confusion_transpose
+
+- fast_gelu
+
+- npu_layer_norm_eval
+
+- npu_linear
+
+- npu_fusion_attention（该算子在 GPU 上预检时，需要额外安装 flash_attn，请用户自行安装。）
+
+- npu_rms_norm
+
+- npu_rotary_mul
+
+- npu_scaled_masked_softmax
+
+- npu_swiglu
+
+- npu_apply_adam
+
+- npu_group_norm_silu
+
+- npu_mish
+
+- npu_moe_gating_top_k_softmax
+
+- npu_sort_v2

msprobe/docs/10.accuracy_compare_PyTorch.md

@@ -251,7 +251,48 @@ PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算
 
 上表中NPU_Stack_Info字段需要配置-s参数生成。
 
-### 3.2 颜色标记——真实数据模式、统计数据模式
+### 3.2 比对指标计算公式
+
+$N$: NPU侧tensor
+
+$B$: Bench侧tensor
+
+RE(Relative Error， 相对误差): $\vert\frac {N-B} {B}\vert$  
+
+真实数据模式：
+
+Cosine: $\frac {{N}\cdot{B}} {{\vert\vert{N}\vert\vert}_2{\vert\vert{B}\vert\vert}_2}$
+
+EucDist: ${\vert\vert{A-B}\vert\vert}_2$
+
+MaxAbsErr: $max(\vert{N-B}\vert)$
+
+MaxRelativeErr: $max(RE)$
+
+One Thousandth Err Ratio: $\frac {\sum\mathbb{I}(RE<0.001)} {size(RE)}$
+
+Five Thousandth Err Ratio: $\frac {\sum\mathbb{I}(RE<0.005)} {size(RE)}$
+
+统计数据模式：
+
+Max diff: $max(N)-max(B)$
+
+Min diff: $min(N)-min(B)$
+
+Mean diff: $mean(N)-mean(B)$
+
+L2 Norm diff: $l2norm(N)-l2norm(B)$
+
+MaxRelativeErr: $\vert\frac{max(N)-max(B)}{max(B)}\vert*100\%$
+
+MinRelativeErr: $\vert\frac{min(N)-min(B)}{min(B)}\vert*100\%$
+
+MeanRelativeErr: $\vert\frac{mean(N)-mean(B)}{mean(B)}\vert*100\%$
+
+NormRelativeErr: $\vert\frac{l2norm(N)-l2norm(B)}{l2norm(B)}\vert*100\%$
+
+
+### 3.3 颜色标记——真实数据模式、统计数据模式
 
 通过在命令行中配置-hl或--highlight开启，或者在比对函数中配置参数highlight=True开启，用于标记精度可疑API或模块。开启后，比对性能会有降低，建议比对较大dump.json文件时不配置此参数。
 颜色标记分为红色标记和黄色标记，红色标记优先级高于黄色标记。
@@ -270,7 +311,7 @@ PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算
 4. 一个 API 或模块的 Cosine 的 input/parameters - output > 0.1（真实数据模式）；
 5. 一个 API 或模块的 Requires_grad Consistent 为 False。
 
-### 3.3 比对结果（Result）——统计数据模式、MD5 模式
+### 3.4 比对结果（Result）——统计数据模式、MD5 模式
 
 统计数据模式：
 1. Warning 情况：4种统计值至少一种相对误差 > 0.5，要重点检查该 API；
@@ -282,7 +323,7 @@ MD5 模式：
 2. Different 情况：NPU 与标杆的 CRC-32 值不一致，即 API 数据不完全一致；
 3. N/A 情况：API 没有匹配上。
 
-### 3.4 判断计算精度达标情况（Accuracy Reached or Not）——真实数据模式
+### 3.5 判断计算精度达标情况（Accuracy Reached or Not）——真实数据模式
 
 标记为 `No`，表示精度不达标：
 1. Cosine < 0.99 且 MaxAbsError > 0.001；
@@ -300,7 +341,7 @@ MD5 模式：
 标记为 `Yes`，表示精度达标：
 1. 除以上情况外的其余情况。
 
-### 3.5 错误信息提示（Err_message）——真实数据模式、统计数据模式
+### 3.6 错误信息提示（Err_message）——真实数据模式、统计数据模式
 
 1. "Need double check api accuracy."：四个统计值中至少 1 个相对误差 > 0.5（统计数据模式）；
 2. "Fuzzy matching data, the comparison accuracy may be affected."：NPU 或 Bench 的真实数据名没有匹配上（真实数据模式）；
@@ -319,7 +360,7 @@ MD5 模式：
 
 除以上错误信息提示外，异常数据颜色高亮标记的原因叠加呈现于此列。
 
-### 3.6 计算精度评价指标分析
+### 3.7 计算精度评价指标分析
 
 1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于 1 说明计算出的两个张量越相似，实际可接受阈值为大于 0.99。在计算中可能会存在 nan，主要由于可能会出现其中一个向量为 0。
 

msprobe/docs/14.data_parse_PyTorch.md

@@ -6,7 +6,7 @@
 
 使用场景：本工具主要用于精度比对前后两次 NPU kernel 层级 dump 数据的一致性。
 
-依赖：CANN 包中的 msaccucmp 工具，需要安装 Ascend-CANN-toolkit，详见《[CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)》。
+依赖：CANN 包中的 msaccucmp 工具，需要安装 Ascend-CANN-toolkit，详见《[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/canncommercial/700/envdeployment/instg/instg_0001.html)》。
 
 ## 2 数据解析操作指导
 

msprobe/docs/15.free_benchmarking_PyTorch.md

@@ -87,7 +87,7 @@ D-->config.json配置
     <tr><td>scope</td><td>否</td><td>自定义</td><td>需要通过指定算子名来限制算子插桩范围 如：["Torch.matmul.0.forward", "Tensor.pow.4.forward"]。</td></tr>
     <tr><td>list</td><td>否</td><td>自定义</td><td>需要通过指定算子类型来限制算子插桩范围 如：["relu"] 会匹配所有算子名中包含relu的算子。</td></tr>
     <tr><td rowspan="2">fuzz_stage</td><td rowspan="2">否</td><td>"forward"（默认）</td><td>需要进行算子<b>前向</b>计算的精度问题排查或<b>验证可疑算子。</b></td></tr>
-    <tr><td>"backward"</td><td>需要进行算子<b>反向</b>计算的精度问题排查，不支持仅反向验证，前向验证包括反向。</td><td></td></tr>
+    <tr><td>"backward"</td><td>需要进行算子<b>反向</b>计算的精度问题排查，不支持仅反向验证，前向验证包括反向。必须设置list参数指定需要检测的算子（详见3.2 config.json配置章节）, 指定的算子会暂存前向激活值，增加内存的占用。</td><td></td></tr>
 </table>
 
 #### 3.2.2 选择扰动因子

msprobe/docs/19.monitor.md

@@ -62,6 +62,8 @@ monitor.set_monitor(
 ) 
 ```
 
+*注意*：若框架为FSDP1，请先保证model包裹FSDP时设置use_orig_params=True。
+
 *注意*：补充deepspeed下常用框架的使能位置。
 
 deepspeed与accelerate、transformers同时使用时，optimizer传值方式为`optimizer=optimizer.optimizer`，若未使用deepspeed，单独使用accelerate、transformers，optimizer传值方式为`optimizer=optimizer`。