mindstudio-probe 1.3.0__py3-none-any.whl → 8.1.1__py3-none-any.whl

msprobe/docs/08.accuracy_checker_online_PyTorch.md

@@ -3,7 +3,7 @@
 ## 1 简介
 
 为了应对大模型场景下，通过离线预检方式 dump API 输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行 NPU 训练操作的过程中，通过 TCP/IP 协议在 NPU
-Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择比对两方比对和三方比对。
+Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。针对偏差较大的算子，两方比对（NPU vs. GPU）的方法缺少裁判进行裁定。 参考离线预检，在线预检场景同时支持两方比对和三方比对方式，按照 api 的精度标准要求，选择两方比对或三方比对。
 
 ## 2 在线精度预检流程
 
@@ -37,7 +37,7 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | 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，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。 | 否    |
+| 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 侧在线预检配置说明
@@ -55,7 +55,7 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 | 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，str 类型，未配置该参数时默认取值当前路径。tls_path配置为空字符串时，采用TCP协议明文传输api数据；当配置为路径时，采用TLS1.2协议加密传输数据，加密传输时安全性较高，传输速率较低。 | 否    |
+| 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 局域网场景配置示例
@@ -63,15 +63,65 @@ Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据
 若采用 TLS1.2 协议加密传输 api 数据，需配置 SSL 证书，可参考如下生成自签名证书方法。
 
 以下秘钥生成方法仅为简单示例，客户应使用与自己需求相符的秘钥生成和存储机制并保证秘钥安全性与机密性，必要时可采用分层秘钥机制。
+以下示例中加密口令仅供参考，使用时请更换为复杂口令，并保护口令安全。
 ```shell
-# 创建私钥文件server.key
-openssl genrsa -out server.key 2048
+# 生成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
+)
 
-# 创建签名请求文件server.csr
-openssl req -new -key server.key -out server.csr
+```
+
+当需要吊销已创建的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
 
-# 自签名, 生成1年期公钥文件server.crt
-openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
 ```
 
 注意：配置TLS协议时，传输性能受机器环境和网络质量的影响，可能触发NPU超时中断模型训练，为避免训练和预检中断，丢弃长时间未传输的api数据，同时NPU侧配置HCCL环境变量，配置方式如下：
@@ -233,3 +283,13 @@ bash train.sh
 - 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/09.accuracy_checker_MindSpore.md

@@ -34,9 +34,18 @@ msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result
 | -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。            |  str      | 是      |
 | -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
 | -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。  |  str   | 否      |
+| -save_error_data                    | 保存(随机数据模式)精度未达标的 API 输入输出数据。                                                                                                                                                    | 空         | 否      |
 
 预检执行结果包括 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 两个文件。`accuracy_checking_result_{timestamp}.csv` 属于 API 级，标明每个 API 是否通过测试。建议用户先查看 `accuracy_checking_result_{timestamp}.csv` 文件，对于其中没有通过测试的或者特定感兴趣的 API，根据其 API Name 字段在 `accuracy_checking_details_{timestamp}.csv` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见 [4 预检结果](#4-预检结果)。
 
+随机数据模式下，如果需要保存比对不达标的输入和输出数据，可以在 run_ut 执行命令结尾添加 `-save_error_data`，例如：
+
+```bash
+msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result -save_error_data
+```
+
+数据默认会存盘到 '{out_path}/error_data' 路径下。
+
 ### 3.2 使用 multi_run_ut 执行多线程预检
 
 multi_run_ut 脚本，可以并行在多个Device执行 run_ut 操作，从而减少预检耗时。示例如下：
@@ -45,16 +54,19 @@ multi_run_ut 脚本，可以并行在多个Device执行 run_ut 操作，从而
 msprobe -f mindspore multi_run_ut -api_info ./dump.json -d 0 1 2 3
 ```
 
-| 参数名称     | 说明                                                                                                                                                                              |参数类型    | 是否必选     |
-| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------- | ---------------------------------- |
-| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。                                   |  str      | 是      |
-| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              |   str   | 否      |
-| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 |  str   | 否      |
-| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0 ~ Device数量 - 1 ，例如 0 1 2 3 4。                                 |                                      List[int]  | 否      |
+| 参数名称     | 说明                                                                                                                                                                              | 参数类型      | 是否必选     |
+| ---------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| ---------------------------------- |
+| -api_info 或 --api_info_file   | 指定 API 信息文件 dump.json。对其中的mint api以及部分Tensor api进行预检，预检支持的Tensor api列表详见 [ 预检支持列表](../mindspore/api_accuracy_checker/checker_support_api.yaml)。                                 | str       | 是      |
+| -o 或 --out_path    | 指定预检结果存盘路径，默认“./”。                                                                                                                                                              | str       | 否      |
+| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | str       | 否      |
+| -d 或 --device                 | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0 ~ Device数量 - 1 ，例如 0 1 2 3 4。                                                                                                       | List[int] | 否      |
+| -save_error_data                    | 保存(随机数据模式)精度未达标的 API 输入输出数据。                                                                                                                                                    | 空         | 否      |
 
 在不同卡数下，使用38B语言大模型的预检耗时基线参考 [multi_run_ut耗时基线](accuracy_checker_MindSpore/accuracy_checker_MindSpore_baseline.md)
 
 
+数据默认会存盘到 './ut_error_data{timestamp}' 路径下
+
 ### 3.3 断点续检
 
 断点续检操作通过如下命令执行：

msprobe/docs/10.accuracy_compare_PyTorch.md

@@ -53,12 +53,12 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 | 参数名               | 说明                                                                                                                                                                                  | 是否必选 |
 |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
-| -i 或 --input_path   | 指定[比对文件](#214-比对文件)，str 类型。                                                                                                                                                         | 是       |
+| -i 或 --input_path   | 指定[比对文件](#51-比对文件)，str 类型。                                                                                                                                                         | 是       |
 | -o 或 --output_path  | 配置比对结果文件存盘目录，str 类型，默认在当前目录创建output目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。<br>提示：output目录下与结果件同名文件将被删除覆盖。                                                           | 否       |
-| -s 或 --stack_mode   | 比对结果展示调用栈信息（NPU_Stack_Info）的开关，bool 类型。单卡场景开启时，根据[比对文件](#214-比对文件)的参数说明配置stack_path；多卡场景开启时，自动识别npu_dump目录下stack.json文件，如存在生成详细调用栈信息，否则不生成，此参数不生效。通过直接配置该参数开启，默认未配置，表示关闭。           | 否       |
+| -s 或 --stack_mode   | 比对结果展示调用栈信息（NPU_Stack_Info）的开关，bool 类型。单卡场景开启时，根据[比对文件](#51-比对文件)的参数说明配置stack_path；多卡场景开启时，自动识别npu_dump目录下stack.json文件，如存在生成详细调用栈信息，否则不生成，此参数不生效。通过直接配置该参数开启，默认未配置，表示关闭。           | 否       |
 | -c 或 --compare_only | 仅比对开关，bool 类型。该参数默认未配置，会启用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度可能不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。通过配置该参数取消自动精度分析，仅输出比对结果表格。 | 否       |
 | -f 或 --fuzzy_match  | 模糊匹配，bool 类型。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                                          | 否       |
-| -dm或--data_mapping | 自定义映射关系比对。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件](#215-自定义映射文件)。仅[API和模块无法自动匹配场景](#213-api和模块无法自动匹配场景)需要配置。仅支持逐卡比对，即使用[比对文件](#214-比对文件)的单卡场景示例。                                    | 否 |
+| -dm或--data_mapping | 自定义映射关系比对。需要指定自定义映射文件*.yaml。自定义映射文件的格式请参见[自定义映射文件](#52-自定义映射文件)。仅[API和模块无法自动匹配场景](#213-api和模块无法自动匹配场景)需要配置。仅支持逐卡比对，即使用[比对文件](#51-比对文件)的单卡场景示例。                                    | 否 |
 
 #### 2.1.2 整网比对场景
 
@@ -66,19 +66,17 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。
 
-1. 配置[config.json](../config.json)文件。
+1. 参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
 
-2. 参见 [PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
+2. 创建[比对文件](#51-比对文件)。
 
-3. 创建[比对文件](#214-比对文件)。
-
-4. 运行命令：
+3. 运行命令：
 
    ```shell
    msprobe -f pytorch compare -i ./compare.json -o ./output -s
    ```
 
-5. 查看比对结果，请参见 [3 精度比对结果分析](#3-精度比对结果分析)。
+4. 查看比对结果，请参见 [3 精度比对结果分析](#3-精度比对结果分析)。
 
 #### 2.1.3 API和模块无法自动匹配场景
 
@@ -88,7 +86,7 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
 
 2. 参见[PyTorch 场景下的数据采集](./05.data_dump_PyTorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。
 
-3. 创建[比对文件](#214-比对文件)（单卡场景示例）。
+3. 创建[比对文件](#51-比对文件)（单卡场景示例）。
 
 4. 运行命令：
 
@@ -96,75 +94,30 @@ msprobe -f pytorch compare -i ./compare.json -o ./output -s
    msprobe -f pytorch compare -i ./compare.json -o ./output -s -dm data_mapping.yaml
    ```
 
-   data_mapping.yaml文件配置请参见[自定义映射文件](#215-自定义映射文件)。
+   data_mapping.yaml文件配置请参见[自定义映射文件](#52-自定义映射文件)。
 
    该场景不支持-f模糊匹配。
 
 5. 查看比对结果，请参见 [3 精度比对结果分析](#3-精度比对结果分析)。
 
-#### 2.1.4 比对文件
-
-   以在当前目录创建 ./compare.json 为例。
 
-   - 单卡场景示例：
-
-     ```json
-     {
-     "npu_path": "./npu_dump/dump.json",
-     "bench_path": "./bench_dump/dump.json",
-     "stack_path": "./npu_dump/stack.json",
-     "is_print_compare_log": true
-     }
-     ```
-
-   - 多卡场景示例：
-
-     ```json
-     {
-     "npu_path": "./npu_dump/step0",
-     "bench_path": "./bench_dump/step0",
-     "is_print_compare_log": true
-     }
-     ```
-
-**参数说明**：
-
-| 参数名               | 说明                                                                                                                                                                                  | 是否必选 |
-| -------------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
-| npu_path             | 配置 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景），str 类型。                                                                                                                                 | 是    |
-| bench_path           | 配置 CPU、GPU 或 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景），str 类型。                                                                                                                       | 是    |
-| stack_path           | 配置 NPU dump 目录下的 stack.json 文件，str 类型。如果没有配置stack_path，命令行-s参数不生效，程序自动识别是否存在stack.json文件，如存在，则比对结果中呈现NPU_Stack_Info，如不存在，则不呈现。如果配置了stack_path，比对结果中是否呈现NPU_Stack_Info则通过命令行参数-s来控制。 | 否    |
-| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值 true 或 false，默认为 true。关闭后则只输出常规日志，bool 类型。                                                                                                                      | 否    |
-
-#### 2.1.5 自定义映射文件
-
-文件名格式：*.yaml，*为文件名，可自定义。
-
-文件内容格式：
+#### 2.1.4 单点数据比对场景
 
-```yaml
-# API
-{api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}: {api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}
-# 模块
-{Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}: {Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}
-```
+单点数据比对场景是指：CPU 或 GPU 与 NPU环境的网络中单点保存的数据比对。
 
-冒号左侧和右侧分别为PyTorch框架不同版本或不同芯片环境的API的名称和module模块名称。
+支持单卡和多卡，可同时比对多卡的单点数据。多机场景需要每个设备单独执行比对操作。
 
-API和模块名称请从《[PyTorch 场景的精度数据采集](05.data_dump_PyTorch.md)》中的dump.json文件获取。
+1. 参见 [单点保存工具](./28.debugger_save_instruction.md)章节完成 CPU 或 GPU 与 NPU 的单点数据采集。
 
-文件内容示例：
+2. 创建[比对文件（单点数据）](#53-比对文件单点数据)。
 
-```yaml
-# API
-NPU.npu_fusion_attention.4.forward.input.0: NPU.npu_fusion_attention.4.forward.input.0
-# 模块
-Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.forward.0.input.0: Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.forward.0.input.0
-```
+3. 运行命令：
 
-API和模块名称在dump.json文件中的“data_name”字段展示，如下图红框处所示：
+   ```shell
+   msprobe -f pytorch compare -i ./compare.json -o ./output
+   ```
 
-![pt_dump](./img/pt_dump.png)
+4. 查看比对结果，请参见 [3 精度比对结果分析](#3-精度比对结果分析)。
 
 ### 2.2 比对函数方式
 
@@ -219,7 +172,7 @@ compare_distributed(npu_dump_dir, bench_dump_dir, output_path, **kwargs)
 | -------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
 | npu_dump_dir   | 配置 NPU 环境下的 dump 目录。str 类型。dump 数据目录须指定到 step 级。<br/>**配置示例**：'./npu_dump/step0'。                                                                                                        | 是       |
 | bench_dump_dir | 配置 CPU、GPU 或 NPU 环境下的 dump 目录。str 类型。<br/>**配置示例**：'./gpu_dump/step0'。                                                                                                                   | 是       |
-| output_path    | 配置比对结果文件存盘目录。需要预先创建 output_path 目录。str 类型。<br/>**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}-rank{cpu/gpu/npu_ID}_{timestamp}.xlsx`。<br>提示：output目录下与结果件同名文件将被删除覆盖。 | 是       |
+| output_path    | 配置比对结果文件存盘目录。需要预先创建 output_path 目录。str 类型。<br/>**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}_{timestamp}.xlsx`。<br>提示：output目录下与结果件同名文件将被删除覆盖。 | 是       |
 | **kwargs       | 支持 compare 的所有可选参数。 其中，stack_mode不生效，自动识别是否存在stack.json，如存在，呈现NPU_Stack_Info，否则不呈现。                                                                                                      | 否       |
 
 **函数示例**：
@@ -315,7 +268,7 @@ MD5 模式：
 
 1. "Need double check api accuracy."：四个统计值中至少 1 个相对误差 > 0.5（统计数据模式）；
 2. "Fuzzy matching data, the comparison arruracy may be affected."：NPU 或 Bench 的真实数据名没有匹配上（真实数据模式）；
-3. "Dump file: {} not found."：NPU 真实数据不存在或者读取出错（真实数据模式）；
+3. "Dump file: {} not found or read failed."：NPU 或 Bench 的真实数据不存在或者读取出错（真实数据模式）；
 4. "No bench data matched."：Bench 的 API 没有匹配上、Bench 真实数据不存在或读取出错（真实数据模式）；
 5. "This is empty data, can not compare."：读取到的数据为空（真实数据模式）；
 6. "Shape of NPU and bench Tensor do not match. Skipped."：NPU 和 Bench 的数据结构不一致（真实数据模式）；
@@ -336,7 +289,7 @@ MD5 模式：
 
 4. MaxRelativeErr：当最大相对误差越接近 0 表示其计算的误差越小。
 
-   当 dump 数据中存在 0 或 Nan 时，比对结果中最大相对误差则出现 inf 或 Nan 的情况，属于正常现象。
+   当 dump 数据中存在 0 或 nan 时，比对结果中最大相对误差则出现 inf 或 nan 的情况，属于正常现象。
 
 5. One Thousandth Err Ratio（相对误差小于千分之一的元素比例）、Five Thousandths Err Ratio（相对误差小于千分之五的元素比例）精度指标：是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一、千分之五的比例占总元素个数的比例。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。
 
@@ -380,10 +333,10 @@ compare_index:
 - MeanRelativeErr
 ```
 
-| 参数名        | 说明                                                         |
-| ------------- | ------------------------------------------------------------ |
-| api           | 表示需要汇总的API或module名称。如果没有配置，工具会提示报错。<br>api名称配置格式为：`{api_type}.{api_name}.{API调用次数}.{前向反向}`<br>须按顺序配置以上四个字段，可按如下组合配置：<br/>        {api_type}<br/>        {api_type}.{api_name}<br/>        {api_type}.{api_name}.{API调用次数}<br/>        {api_type}.{api_name}.{API调用次数}.{前向反向}<br/>这里的api指代API或module。 |
-| compare_index | 表示需要汇总的比对指标。compare_index需为dump_mode对应比对指标的子集。如果没有配置，工具将根据比对结果自动提取dump_mode对应的全部比对指标进行汇总。<br>统计数据模式比对指标：Max diff、Min diff、Mean diff、Norm diff、MaxRelativeErr、MinRelativeErr、MeanRelativeErr、NormRelativeErr<br>真实数据模式比对指标：Cosine、MaxAbsErr、MaxRelativeErr、One Thousandth Err Ratio、Five Thousandths Err Ratio |
+| 参数名        | 说明                                                                                                                                                                                                                                                                                                                      |
+| ------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| api           | 表示需要汇总的API或module名称。如果没有配置，工具会提示报错。<br>api名称配置格式为：`{api_type}.{api_name}.{API调用次数}.{前向反向}`<br>须按顺序配置以上四个字段，可按如下组合配置：<br/>        {api_type}<br/>        {api_type}.{api_name}<br/>        {api_type}.{api_name}.{API调用次数}<br/>        {api_type}.{api_name}.{API调用次数}.{前向反向}<br/>这里的api指代API或module。                    |
+| compare_index | 表示需要汇总的比对指标。compare_index需为dump_mode对应比对指标的子集。如果没有配置，工具将根据比对结果自动提取dump_mode对应的全部比对指标进行汇总。<br>统计数据模式比对指标：Max diff、Min diff、Mean diff、L2norm diff、MaxRelativeErr、MinRelativeErr、MeanRelativeErr、NormRelativeErr<br>真实数据模式比对指标：Cosine、EucDist、MaxAbsErr、MaxRelativeErr、One Thousandth Err Ratio、Five Thousandths Err Ratio |
 
 **汇总结果件说明**
 
@@ -414,4 +367,189 @@ compare_index:
 6. Distributed.broadcast：输入为要广播的数据，输出为广播后的数据。
 7. Distributed.isend：点对点通信，输入为要发送的数据，输出为发送的数据。
 8. Distributed.irecv：点对点通信，输入为原数据，输出为接收的新数据。
-9. Distributed.all_to_all_single：输出数据为所有卡上的数据切分后合并的结果。
+9. Distributed.all_to_all_single：输出数据为所有卡上的数据切分后合并的结果。
+
+## 5 附录
+
+###  5.1 比对文件
+
+   以在当前目录创建 ./compare.json 为例。
+
+   - 单卡场景示例：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/dump.json",
+     "bench_path": "./bench_dump/dump.json",
+     "stack_path": "./npu_dump/stack.json",
+     "is_print_compare_log": true
+     }
+     ```
+
+   - 多卡场景示例：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/step0",  # 需填写到step层级（rank的上一层级）
+     "bench_path": "./bench_dump/step0",  # 需填写到step层级（rank的上一层级）
+     "is_print_compare_log": true
+     }
+     ```
+
+**参数说明**
+
+| 参数名               | 说明                                                                                                                                                                                | 是否必选 |
+| -------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
+| npu_path             | 配置NPU环境下的dump.json文件（单卡场景）或dump目录（多卡场景）。数据类型：str。                                                                                                                                 | 是    |
+| bench_path           | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）或dump目录（多卡场景）。数据类型：str。                                                                                                                         | 是    |
+| stack_path           | 配置NPU dump目录下的stack.json文件。数据类型：str。如果没有配置stack_path，命令行-s参数不生效，程序自动识别是否存在stack.json文件，如存在，则比对结果中呈现NPU_Stack_Info，如不存在，则不呈现。如果配置了stack_path，比对结果中是否呈现NPU_Stack_Info则通过命令行参数-s来控制。 | 否    |
+| is_print_compare_log | 配置是否开启单个算子的日志打屏。可取值true或false，默认为true。关闭后则只输出常规日志。数据类型：bool。                                                                                                                      | 否    |
+
+### 5.2 自定义映射文件
+
+文件名格式：*.yaml，*为文件名，可自定义。
+
+文件内容格式：
+
+```yaml
+# API
+{api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}: {api_type}.{api_name}.{API调用次数}.{前向反向}.{input/output}.{参数序号}
+# 模块
+{Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}: {Module}.{module_name}.{前向反向}.{index}.{input/output}.{参数序号}
+```
+
+冒号左侧和右侧分别为PyTorch框架不同版本或不同芯片环境的API的名称和module模块名称。
+
+API和模块名称请从《[PyTorch 场景的精度数据采集](05.data_dump_PyTorch.md)》中的dump.json文件获取。
+
+文件内容示例：
+
+```yaml
+# API
+NPU.npu_fusion_attention.4.forward.input.0: NPU.npu_fusion_attention.4.forward.input.0
+# 模块
+Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.forward.0.input.0: Module.module.language_model.embedding.word_embedding.VocabParallelEmbedding.forward.0.input.0
+```
+
+当dump.json文件中存在“data_name”字段时，API和模块名称为data_name字段去掉文件后缀，如下图红框处所示：
+
+![pt_dump](./img/pt_dump.png)
+
+当dump.json文件中不存在“data_name”字段时，名称的拼写规则如下：
+
+input_args、input_kwargs和output使用统一的命名规则，当值是list类型时，名称后面添加'.{index}'，当值类型是dict类型时，名称后面加'.{key}'，当值类型是具体Tensor或null或int或float或bool或空list/dict等时，命名结束。
+
+以下面api的dump文件为例：
+```yaml
+  "Functional.max_pool2d.0.forward": {
+   "input_args": [
+    {
+     "type": "torch.Tensor",
+     "dytpe": "torch_float32",
+     "shape": [
+      1,
+      64,
+      14,
+      14
+     ],
+     "Max": xxx,
+     "Min": xxx,
+     "Mean": xxx,
+     "Norm": xxx,
+     "requires_grad": true
+    },
+    {
+     "type": "int",
+     "value": 3
+    },
+    {
+     "type": "int",
+     "value": 2
+    },
+    {
+     "type": "int",
+     "value": 1
+    },
+    {
+     "type": "int",
+     "value": 1
+    }
+   ],
+   "input_kwargs": {
+    "ceil_mode": {
+     "type": "bool",
+     "value": false
+    },
+    "return_indices": {
+     "type": "bool",
+     "value": false
+    },
+   },
+   "output": [
+    {
+     "type": "torch.Tensor",
+     "dtype": "torch.float32",
+     "shape": [
+     1,
+     64,
+     7,
+     7
+     ],
+     "Max": xxx,
+     "Min": xxx,
+     "Mean": xxx,
+     "Norm": xxx,
+     "requires_grad": true
+    }
+   ]
+  }
+```
+
+初始名称为Functional.max_pool2d.0.forward，input_args是list，长度为5，第0项后面是Tensor，命名结束；第1-4项后面均是int，命名结束；按照顺序命名为
+```
+Functional.max_pool2d.0.forward.input.0
+Functional.max_pool2d.0.forward.input.1
+Functional.max_pool2d.0.forward.input.2
+Functional.max_pool2d.0.forward.input.3
+Functional.max_pool2d.0.forward.input.4
+```
+input_kwargs是dict，key是ceil_mode、return_indices，值均是bool，命名结束；命名为
+```
+Functional.max_pool2d.0.forward.input.ceil_mode
+Functional.max_pool2d.0.forward.input.return_indices
+```
+output是list，长度为1，第0项后面是Tensor，命名结束；按照顺序命名为
+```
+Functional.max_pool2d.0.forward.output.0
+```
+综上，生成的的op_name为
+```
+Functional.max_pool2d.0.forward.input.0
+Functional.max_pool2d.0.forward.input.1
+Functional.max_pool2d.0.forward.input.2
+Functional.max_pool2d.0.forward.input.3
+Functional.max_pool2d.0.forward.input.4
+Functional.max_pool2d.0.forward.input.ceil_mode
+Functional.max_pool2d.0.forward.input.return_indices
+Functional.max_pool2d.0.forward.output.0
+```
+
+### 5.3 比对文件（单点数据）
+
+   - 单卡场景示例：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/debug.json",
+     "bench_path": "./bench_dump/debug.json"
+     }
+     ```
+
+   - 多卡场景示例(step0目录下包含debug.json文件)：
+
+     ```json
+     {
+     "npu_path": "./npu_dump/step0",
+     "bench_path": "./bench_dump/step0"
+     }
+     ```