mindstudio-probe 1.0.1__py3-none-any.whl

msprobe/pytorch/doc/parse_tool.md

@@ -0,0 +1,286 @@
+# **数据解析工具**
+
+数据解析工具（parse_tool）提供命令行交互式界面，提供更多的数据解析功能并且展示结果。
+
+使用场景：本工具主要用于精度比对前后两次NPU kernel层级dump数据的一致性。
+
+## 进入parse交互式界面
+
+安装msprobe工具后（详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节），可以通过使用命令 **msprobe -f pytorch parse** 进入交互式界面，如下所示：
+
+```bash
+msprobe -f pytorch parse
+Parse >>>
+```
+
+可在parse的界面中执行Shell命令，以及如下场景的相关解析命令：
+
+- 支持指定kernel层级算子数据比对。
+- 支持指定kernel层级算子数据转换及展示。
+- 支持交互式指定pkl文件中API对应dump数据查看。
+- 支持API进行可选层级比对和打印（统计级和像素级）。
+
+Ctrl+C可以退出parse交互式界面。不退出parse交互式界面若需要执行非该界面下的内置Shell命令，且命令与parse交互式界面命令冲突时，非该界面命令需要使用run命令，在相关命令前加上run前缀，如下示例：
+
+```bash
+msprobe -f pytorch parse
+Parse >>> run vim cli.py
+Parse >>> vim cli.py
+```
+
+以上各场景详细介绍请参见下文章节。
+
+## kernel层级算子数据批量转换
+
+本功能会将原有待比对dump数据目录下的dump数据按照算子名和时间戳进行梳理并分类，之后再将dump数据转为为npy文件。
+
+依赖：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)》。
+
+输入以下比对命令进行数据转换。
+
+```bash
+cad -m my_dump_path [-out output_path] [-asc msaccucmp_path]
+```
+
+| 参数名称 | 说明                                                         | 是否必选 |
+| -------- | ------------------------------------------------------------ | -------- |
+| -m       | 待转换kernel dump数据目录。需要指定到kernel dump数据的deviceid级目录。 | 是       |
+| -out     | 结果输出目录，须指定已存在的目录，默认为./parse_data/acl_batch_convert。未指定时保存在默认路径下，比对结束后会打印log提示输出结果存放路径。 | 否       |
+| -asc     | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py。 | 否       |
+
+**示例**
+
+```
+# 传入待比对数据目录
+Parse >>> cad -m /home/xxx/my_dump_path/20000124003856/0
+# 转换结果打印
+......
+╭──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+# 转换前的dump文件
+│ SrcFile: /home/xxx/my_dump_path/20000124003856/0/272/TransData.trans_TransData_22.112.21.948645536672764 │
+# 转换后的npy文件
+│ - TransData.trans_TransData_22.112.21.948645536672764.output.0.npy                                       │
+│ - TransData.trans_TransData_22.112.21.948645536672764.input.0.npy                                        │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+......
+[INFO] The comparison result have been written to "./parse_data/acl_batch_convert".
+```
+
+输出结果：
+
+原dump数据目录：
+
+```
+├── /home/xxx/my_dump_path/20000124003856/0/
+│   ├── 272
+│   │   ├── {op_type}.{op_name}.{task_id}.{stream_id}.{timestamp}
+│   │   ...
+│   ├── 512
+│   ...
+```
+
+转换后：
+
+```
+├── ./parse_data/acl_batch_convert/{timestamp}
+│   ├── {op_name1}
+│   │   ├── {timestamp1}
+│   │   |   ├── {op_type}.{op_name}.{task_id}.{stream_id}.{timestamp}.{input/output}.{参数序号}.npy
+│   │   |   │   ...
+│   │   ├── {timestamp2}
+│   │   |   ...
+│   ├── {op_name2}
+│   ├── ...
+```
+
+## kernel层级算子数据比对
+
+本功能主要用于比对前后两次NPU kernel层级dump数据的一致性。
+
+本功能支持批量比对，若需要进行批量比对，需要先将两份待比对的NPU kernel层级dump数据进行“**kernel层级算子数据批量转换**”，可以使两份数据更好的匹配；若直接进行dump数据的比对，建议只比对单个dump数据文件。
+
+输入以下比对命令进行数据比对。
+
+```bash
+vc -m my_dump_path -g golden_dump_path [-out output_path] [-cmp_path msaccucmp_path]
+```
+
+| 参数名称  | 说明                                                         | 是否必选 |
+| --------- | ------------------------------------------------------------ | -------- |
+| -m        | 待比对kernel dump数据目录。如果比对单个算子，需要指定到kernel dump数据的model_id级目录；如果批量比对，则指定到cad转换后的timestamp级目录。 | 是       |
+| -g        | 标杆kernel dump数据目录。如果比对单个算子，需要指定到kernel dump数据的model_id级目录；如果批量比对，则指定到cad转换后的timestamp级目录。 | 是       |
+| -out      | 结果输出目录，须指定已存在的目录，默认为./parse_data/acl_batch_comapre。未指定时保存在默认路径下，比对结束后会打印log提示输出结果存放路径。 | 否       |
+| -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否       |
+
+输出结果：batch_compare_{timestamp}.csv文件。
+
+**示例**
+
+```bash
+# 传入待比对数据目录以及标杆数据目录
+Parse >>> vc -m ./my_dump_path -g ./golden_data_path
+[INFO]Compare result is saved in : parse_data/acl_batch_comapre/batch_compare_1707271118.csv
+```
+
+## kernel算子数据的npy转换
+
+依赖：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)》。
+
+输入以下转换命令进行数据转换， 将kernel级别dump数据转为npy文件。
+
+```bash
+dc -n file_name/file_path [-f format] [-out output_path]
+```
+
+| 参数名称  | 说明                                                         | 是否必选 |
+| --------- | ------------------------------------------------------------ | -------- |
+| -n        | 需转换的dump数据文件或dump数据文件目录。                     | 是       |
+| -f        | 开启format转换，指定该参数时需要配置format格式。当前内置的Format转换支持如下类型： FRACTAL_NZ转换NCHW FRACTAL_NZ转换成NHWC FRACTAL_NZ转换ND HWCN转换FRACTAL_Z HWCN转换成NCHW HWCN转换成NHWC NC1HWC0转换成HWCN NC1HWC0转换成NCHW NC1HWC0转换成NHWC NCHW转换成FRACTAL_Z NCHW转换成NHWC NHWC转换成FRACTAL_Z NHWC转换成HWCN NHWC转换成NCHW NDC1HWC0转换成NCDHW | 否       |
+| -out      | 结果输出目录。                                               | 否       |
+| -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否       |
+
+- 输出结果：npy文件。
+
+- 若指定-out参数需要用户传入输出路径，并且路径需要已存在。
+
+- 若未指定输出目录， 则比对结束后将结果保存在默认目录 “./parse_data/convert_result”中，比对结束后会打印log提示输出结果存放路径及转换结果。
+
+- 输入以下命令，展示npy数据统计信息。
+
+  ```bash
+  pt -n file_path
+  ```
+
+  | 参数名称 | 说明          | 是否必选 |
+  | -------- | ------------- | -------- |
+  | -n       | npy文件路径。 | 是       |
+
+  打印统计信息：shape, dtype, max, min和mean。默认在npy文件路径下将该数据保存为txt文件。
+
+**示例1**
+
+```bash
+# 传入需转换的dump文件目录
+Parse >>> dc -n ./dump_data/
+......
+# 转换结果
+╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ SrcFile: ./dump_data/
+│  - Add.fp32_vars_add_2fp32_vars_Relu_9.31.5.1636595794731103.input.0.npy                             │
+│  - Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.output.0.npy                            │
+│  - Add.fp32_vars_add_2fp32_vars_Relu_9.31.5.1636595794731103.input.1.npy                             │
+│  - Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.1.npy                             │
+│  - Add.fp32_vars_add_3fp32_vars_Relu_12.40.5.1636595794846124.input.1.npy                            │
+│  - Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy                             │
+│  - Add.fp32_vars_add_3fp32_vars_Relu_12.40.5.1636595794846124.input.0.npy                            │
+│  - Add.fp32_vars_add_2fp32_vars_Relu_9.31.5.1636595794731103.output.0.npy                            │
+│  - Add.fp32_vars_add_3fp32_vars_Relu_12.40.5.1636595794846124.output.0.npy                           │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+**示例2**
+
+```bash
+# 查看某个dump数据块的数据信息
+# 默认会将数据中的tensor保存成 txt
+Parse >>> pt -n ./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.output.0.npy
+......
+# 打印统计信息
+[Shape: (1, 16, 56, 56, 16)] [Dtype: float16] [Max: 452.0] [Min: -408.5] [Mean: -3.809]
+Path: ./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy                           
+TextFile:./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy.txt
+```
+
+## dump.json文件中指定API的dump数据信息查看（暂不支持）
+
+输入以下命令，解析并输出dump.json文件中指定API的统计信息。
+
+```bash
+pk -f pkl_path -n api_name
+```
+
+| 参数名称 | 说明                    | 是否必选 |
+| -------- | ----------------------- | -------- |
+| -f       | 指定dump.json文件路径。 | 是       |
+| -n       | 指定API名称。           | 是       |
+
+- 输出结果：打印统计信息（shape, dtype, max和min mean）。
+- 若pkl文件中存在相应的堆栈信息，则会打印堆栈信息。
+
+**示例**
+
+```bash
+# 传入pkl文件及api名称
+Parse >>> pk -f ./torch_dump/xxx/rank0/dump.json -n Functional_conv2d_0_forward
+......
+# 打印统计信息及堆栈（pkl文件不包含堆栈则不会打印堆栈）
+
+Statistic Info:
+  [Functional_conv2d_0_forward_input.0][dtype: torch.float32][shape: [2, 1, 2, 2]][max: 1.576936960220337][min: -0.9757485389709473][mean: 0.4961632490158081]
+  [Functional_conv2d_0_forward_input.1][dtype: torch.float32][shape: [2, 1, 2, 2]][max: 0.20064473152160645][min: -0.47102075815200806][mean: -0.20796933770179749]
+  [Functional_conv2d_0_forward_input.2][dtype: torch.float32][shape: [2]][max: 0.17380613088607788][min: -0.16853803396224976][mean: 0.0026340484619140625]
+  [Functional_conv2d_0_forward_output][dtype: torch.float32][shape: [2, 2, 1, 1]][max: 0.02364911139011383][min: -1.762906551361084][mean: -0.6710853576660156]
+```
+
+## API可选层级比对
+
+输入以下命令, 进行统计级和像素级比对。
+
+```bash
+cn -m my_data*.npy -g gloden*.npy [-p num] [-al atol] [-rl rtol]
+```
+
+- 统计级比对：对tensor整体进行余弦值及相对误差的计算。
+- 像素级比对：对输入的两个npy文件进行逐元素比对。若两个tensor对应元素的相对误差或绝对误差大于**误差阈值**（-al和-rl配置）则被标记为错误数据。
+
+| 参数名称 | 说明                                            | 是否必选 |
+| -------- | ----------------------------------------------- | -------- |
+| -m       | 待比对数据。                                    | 是       |
+| -g       | 标杆数据。                                      | 是       |
+| -p       | 设置比对结束后打印错误元素的个数，默认值20。    | 否       |
+| -al      | 判定数据存在精度问题的绝对误差阈值，默认0.001。 | 否       |
+| -rl      | 判定数据存在精度问题的相对误差阈值，默认0.001。 | 否       |
+| -s       | 将npy文件保存成txt文件，用于查看，默认开启。    | 否       |
+
+输出结果：
+
+- 统计级比对结果。
+- 两个文件的统计信息（shape, dtype, max, min和mean）。
+- 错误数据打印表格。
+
+**示例**
+
+```bash
+# 对比两个tensor的数据
+Parse >>> cn -m Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.1619494134703053.output.0.npy -g InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.0.1619492699305998.npy -p 10 -s -al 0.002 -rl 0.005
+                  Error Item Table                                        Top Item Table
+┏━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓ ┏━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ Index ┃ Left          ┃ Right        ┃ Diff         ┃ ┃ Index ┃ Left        ┃ Right       ┃ Diff          ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩ ┡━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ 155   │ 0.024600908   │ 0.022271132  │ 0.002329776  │ │ 0     │ -0.9206961  │ -0.9222216  │ 0.0015255213  │
+│ 247   │ 0.015752593   │ 0.017937578  │ 0.0021849852 │ │ 1     │ -0.6416973  │ -0.64051837 │ 0.0011789203  │
+│ 282   │ -0.0101207765 │ -0.007852031 │ 0.0022687456 │ │ 2     │ -0.35383835 │ -0.35433492 │ 0.0004965663  │
+│ 292   │ 0.019581757   │ 0.02240482   │ 0.0028230622 │ │ 3     │ -0.18851271 │ -0.18883198 │ 0.00031927228 │
+│ 640   │ -0.06593232   │ -0.06874806  │ 0.0028157383 │ │ 4     │ -0.43508735 │ -0.43534422 │ 0.00025686622 │
+│ 1420  │ 0.09293677    │ 0.09586689   │ 0.0029301196 │ │ 5     │ 1.4447614   │ 1.4466647   │ 0.0019032955  │
+│ 1462  │ -0.085207745  │ -0.088047795 │ 0.0028400496 │ │ 6     │ -0.3455438  │ -0.3444429  │ 0.0011008978  │
+│ 1891  │ -0.03433288   │ -0.036525503 │ 0.002192624  │ │ 7     │ -0.6560242  │ -0.6564579  │ 0.0004336834  │
+│ 2033  │ 0.06828873    │ 0.07139922   │ 0.0031104907 │ │ 8     │ -2.6964858  │ -2.6975214  │ 0.0010356903  │
+│ 2246  │ -0.06376442   │ -0.06121233  │ 0.002552092  │ │ 9     │ -0.73746175 │ -0.73650354 │ 0.00095820427 │
+└───────┴───────────────┴──────────────┴──────────────┘ └───────┴─────────────┴─────────────┴───────────────┘
+╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Left:                                                                                                                                 |
+│  |- NpyFile: ./dump/temp/decode/Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.1619494134703053.output.0.npy                 |
+│  |- TxtFile: ./dump/temp/decode/Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.1619494134703053.output.0.npy.txt             |
+│  |- NpySpec: [Shape: (32, 8, 8, 320)] [Dtype: float32] [Max: 5.846897] [Min: -8.368301] [Mean: -0.72565556]                           |
+│ DstFile:                                                                                                                              │
+│  |- NpyFile: ./dump/cpu/InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.0.1619492699305998.npy                                        |
+│  |- TxtFile: ./dump/cpu/InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.0.1619492699305998.npy.txt                                    |
+│  |- NpySpec: [Shape: (32, 8, 8, 320)] [Dtype: float32] [Max: 5.8425903] [Min: -8.374472] [Mean: -0.7256237]                           │
+│ NumCnt:   655360                                                                                                                      │
+│ AllClose: False                                                                                                                       │
+│ CosSim:   0.99999493                                                                                                                  │
+│ ErrorPer: 0.023504638671875  (rl= 0.005, al= 0.002)                                                                                   │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+

msprobe/pytorch/doc/ptdbg_ascend_compare.md

@@ -0,0 +1,176 @@
+# **精度比对工具**
+
+## CPU或GPU与NPU精度数据比对
+
+### 总体说明
+
+- 本节主要介绍CPU或GPU与NPU精度数据比对的函数以及示例，执行精度比对操作前需要先完成CPU或GPU与NPU的精度数据dump，详见《[精度数据采集](./dump.md)》。
+
+- 比对函数均通过单独创建精度比对脚本执行，可支持单卡和多卡场景的精度数据比对。
+
+- 工具性能：比对数据量较小时（参考值单份文件小于10GB），参考比对速度0.1GB/s；比对数据量较大时，参考比对速度0.3GB/s。 推荐环境配置：独占环境，CPU核心数192，固态硬盘（IO速度参考：固态硬盘 > 500MB/s，机械硬盘60 ~ 170MB/s）。
+
+  用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。比对速度的计算方式：两份比对文件大小/比对耗时。
+
+### 约束
+
+- NPU自研API，在CPU或GPU若没有对应的API，该API的dump数据不比对。
+- NPU与CPU或GPU的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个API因为输入的数据差异较大而无法比对的情况。
+- CPU或GPU与NPU中两个相同的API会因为调用次数不同导致无法比对或比对到错误的API，不影响整体运行，该API忽略。
+
+### compare_distributed
+
+**功能说明**
+
+将CPU或GPU与NPU的dump文件进行比对，支持单卡和多卡，可同时比对多卡的dump数据。多机场景需要每个设备单独执行比对操作。可自动检索和匹配对应卡和进程所dump的数据文件，再调用compare进行比对。单机单卡时与compare函数二选一。
+
+**函数原型**
+
+```Python
+compare_distributed(npu_dump_dir, bench_dump_dir, output_path, **kwargs)
+```
+
+**参数说明**
+
+| 参数名         | 说明                                                         | 是否必选 |
+| -------------- | ------------------------------------------------------------ | -------- |
+| npu_dump_dir   | 配置NPU环境下的dump目录。dump数据目录须指定到step级。参数示例：'./npu_dump/step0'。数据类型：str。 | 是       |
+| bench_dump_dir | 配置CPU、GPU或NPU环境下的dump目录。参数示例：'./gpu_dump/step0'。数据类型：str。 | 是       |
+| output_path    | 配置比对结果文件存盘目录。需要预先创建output_path目录。参数示例：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}-rank{cpu/gpu/npu_ID}_{timestamp}.xlsx`。数据类型：str。 | 是       |
+| **kwargs       | 支持compare的所有可选参数。                                  | 否       |
+
+**函数示例**
+
+创建比对脚本，例如compare_distributed.py，拷贝如下代码，具体参数请根据实际环境修改。
+
+```Python
+from msprobe.pytorch import *
+compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output')
+```
+
+dump数据目录须指定到step级。
+
+### compare
+
+**功能说明**
+
+将CPU或GPU与NPU的dump文件进行比对，仅支持单机单卡。
+
+**函数原型**
+
+```Python
+compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_match=False)
+```
+
+**参数说明**
+
+| 参数名       | 说明                                                         | 是否必选 |
+| ------------ | ------------------------------------------------------------ | -------- |
+| input_param  | 配置dump数据文件及目录。数据类型：dict。配置参数包括：<br>        "npu_json_path"：指定NPU dump目录下的dump.json文件。参数示例："npu_json_path": "./npu_dump/dump.json"。必选。<br/>        "bench_json_path"：指定CPU、GPU或NPU dump目录下的dump.json文件。参数示例："bench_json_path": "./gpu_dump/dump.json"。必选。<br/>        "stack_json_path"：指定NPU dump目录下的stack.json文件。参数示例："stack_json_path": "./npu_dump/stack.json"。可选。<br/>        "is_print_compare_log"：配置是否开启日志打屏。可取值True或False。可选。 | 是       |
+| output_path  | 配置比对结果文件存盘目录。参数示例：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。数据类型：str。 | 是       |
+| stack_mode   | 配置stack_mode的开关。仅当配置"stack_json_path"需要开启。可取值True或False，参数示例：stack_mode=True，默认为False。数据类型：bool。 | 否       |
+| auto_analyze | 自动精度分析，开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。可取值True或False，参数示例：auto_analyze=False，默认为True。数据类型：bool。 | 否       |
+| fuzzy_match  | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。可取值True或False，参数示例：fuzzy_match=True，默认为False。数据类型：bool。 | 否       |
+
+**函数示例**
+
+单机单卡场景下创建比对脚本，例如compare.py，拷贝如下代码，具体参数请根据实际环境修改。
+
+```Python
+from msprobe.pytorch import compare
+dump_result_param={
+"npu_json_path": "./npu_dump/dump.json",
+"bench_json_path": "./gpu_dump/dump.json",
+"stack_json_path": "./npu_dump/stack.json",
+"is_print_compare_log": True
+}
+compare(dump_result_param, output_path="./output", stack_mode=True)
+```
+
+### 统计量比对
+
+若使用**compare**或**compare_distributed**函数创建的比对脚本中，在[config.json](../../config/config.json)文件中配置"task": "statistics"方式dump时，可以进行统计量比对，此时比对dump.json文件中的统计信息，开启后的比对结果文件生成Max diff、Min diff、Mean diff和L2norm diff，表示NPU dump数据中API的输入或输出与标杆数据输入或输出的最大值、最小值、平均值以及L2范数的差。可以通过该值判断API是否存在精度问题：当某个API的输入和输出的Max diff、Min diff、Mean diff和L2norm diff均为0或无限趋于0，那么可以判断该API无精度问题，反之则可能存在精度问题。
+
+**比对脚本示例**
+
+以compare.py为例。
+
+```Python
+from msprobe.pytorch import compare
+dump_result_param={
+"npu_json_path": "./npu_dump/dump.json",
+"bench_json_path": "./gpu_dump/dump.json",
+"stack_json_path": "./npu_dump/stack.json",
+"is_print_compare_log": True
+}
+compare(dump_result_param, output_path="./output", stack_mode=True)
+```
+
+**比对结果**
+
+数据量比对同样生成`compare_result_{timestamp}.xlsx`和`advisor_{timestamp}.txt`文件。其中`advisor_{timestamp}.txt`主要对`compare_result_{timestamp}.xlsx`中可能存在精度问题（Result为Waring）的API提出定位建议；`compare_result_{timestamp}.xlsx`主要有如下两种情况：
+
+- "summary_mode": "statistics"时比对dump.json文件：
+
+  ![compare_result_pkl](img/compare_result_pkl.png)
+
+  上图是对dump.json文件中NPU及标杆API的统计信息进行比对，判断可能存在精度问题的API，文件中记录NPU及标杆API的基本信息和统计信息，其中需要关注Result列，包含结果：Waring（NPU与标杆统计信息的比对中存在相对误差大于0.5，则需要重点检查该API）；为空（相对误差小于等于0.5，可以不需要重点关注，但不代表不存在精度问题）；Nan（表示统计信息数据没有匹配上）。
+
+- "summary_mode": "md5"时比对dump.json文件：
+
+  ![compare_result_pkl_md5.png](img/compare_result_pkl_md5.png.png)
+
+  上图是对dump.json文件中NPU及标杆API的MD5信息进行比对，判断API数据的完整性，文件中记录NPU及标杆API的基本信息和MD5信息，其中需要关注Result列，包含结果：Pass（表示NPU与标杆的MD5值一致，即API数据完整）；Different（表示NPU与标杆的MD5值不一致，即API数据不完全一致，可以通过NPU_Stack_Info列API调用栈查询该API的详细信息）；Nan（表示MD5信息数据没有匹配上）。
+
+## 比对结果分析
+
+PyTorch精度比对是以CPU或GPU的计算结果为标杆，通过计算精度评价指标判断API在运行时是否存在精度问题。
+
+- `advisor_{timestamp}.txt`文件中给出了可能存在精度问题的API的专家建议，可直接打开查看。
+
+- `compare_result_{timestamp}.xlsx`文件列出了所有执行精度比对的API详细信息和比对结果，如下示例：
+
+  ![compare_result](https://gitee.com/cai-weiwei1989/att_ptdbg/raw/master/debug/accuracy_tools/ptdbg_ascend/doc/img/compare_result.png)
+
+  可以从该结果文件中进行“**判断计算精度达标情况**”、“**计算精度评价指标分析**”以及“**异常信息识别**”等分析动作。
+
+### **判断计算精度达标情况**
+
+精度比对结果`compare_result_{timestamp}.xlsx`文件中只需要通过Accuracy Reached or Not来判断计算精度是否达标，判断标准如下：
+
+1. Cosine < 0.99 且 MaxAbsError > 0.001时，精度不达标，标记为“No”。
+2. Cosine < 0.9，精度不达标，标记为“No”。
+3. MaxAbsError > 1，精度不达标，标记为“No”。
+4. 其余情况下记为精度达标，标记为“Yes”。
+
+### **计算精度评价指标分析**
+
+1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于1说明计算出的两个张量越相似，实际可接受阈值为大于0.99。在计算中可能会存在nan，主要由于可能会出现其中一个向量为0。
+
+2. MaxAbsErr：当最大绝对误差越接近0表示其计算的误差越小，实际可接受阈值为小于0.001。
+
+3. MaxRelativeErr：当最大相对误差越接近0表示其计算的误差越小。
+
+   当dump数据中存在0或Nan时，比对结果中最大相对误差则出现inf或Nan的情况，属于正常现象。
+
+4. One Thousandth Err Ratio（双千分之一）、Five Thousandths Err Ratio（双千分之五）精度指标：是指NPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差大于千分之一、千分之五的比例占总元素个数的比例小于千分之一、千分之五。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。
+
+### **异常信息识别**
+
+精度比对结果`compare_result_{timestamp}.xlsx`文件中对于存在异常信息的API会进行高亮处理：
+
+- 红色可能出现的情况有：
+  - NPU max或NPU min信息中存在nan/inf
+  - Max diff存在大于1e+10的值
+  - 统计数据中output的Max diff除以max(0.01, Bench max) > 0.5
+  - 真实数据中One Thousandth Err Ratio的input > 0.9同时output < 0.6
+- 黄色可能出现的情况有：
+  - Max diff的input与output都大于1，同时output比input大一个数量级以上
+  - 统计数据Max diff除以max(0.01, Bench max)的output > 0.1同时input < 0.01
+  - 真实数据One Thousandth Err Ratio的input - output > 0.1
+  - 真实数据Cosine的input - output > 0.1
+
+# FAQ
+
+[FAQ](./FAQ.md)
+

msprobe/pytorch/doc/ptdbg_ascend_overview.md

@@ -0,0 +1,68 @@
+# **精度比对工具**
+
+## 简介
+
+在PyTorch训练网络，对同一模型或API调试过程中，遇到API相关的计算精度问题，定位时费时费力。
+
+msprobe的精度比对工具，用来进行PyTorch整网API粒度的数据dump、精度比对和溢出检测，从而定位PyTorch训练场景下的精度问题。
+
+**使用场景**
+
+主要的使用场景包括：
+
+- 同一模型，从CPU或GPU移植到NPU中存在精度下降问题，对比NPU芯片中的API计算数值与CPU或GPU芯片中的API计算数值，进行问题定位。
+- 同一模型，进行迭代（模型、框架版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的API计算数值，进行问题定位。
+
+## 原理介绍
+
+精度对比工具，通过在PyTorch模型中注册hook，跟踪计算图中API的前向传播与反向传播时的输入与输出，排查存在计算精度误差，进行问题的精准定位。
+
+**精度比对流程**
+
+1. 当模型在CPU或GPU上进行正向和反向传播时，分别dump每一层的数值输入与输出。
+
+2. 当模型在NPU中进行计算时，采用相同的方式dump下相应的数据。
+
+3. 通过对比dump出的数值，计算余弦相似度和最大绝对误差的方式，定位和排查NPU API存在的计算精度问题。如下图所示。
+
+   精度比对逻辑图
+
+   ![module_compare](img/module_compare.png)
+
+**API匹配条件**
+
+进行精度比对时，需要判断CPU或GPU的API与NPU的API是否相同可比对，须满足以下匹配条件：
+
+- 两个API的名称相同，API命名规则：`{api_type}.{api_name}.{api调用次数}.{正反向}.{输入输出}.index`，如：Functional.conv2d.1.backward.input.0。
+- 两个API的输入输出Tensor数量和各个Tensor的Shape相同。
+
+通常满足以上两个条件，工具就认为是同一个API，成功进行API的匹配，后续进行相应的计算精度比对。
+
+## 精度比对总体流程
+
+1. 准备CPU或GPU训练工程。
+
+2. 在环境下安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
+
+3. 在训练脚本内添加msprobe工具dump接口PrecisionDebugger采集标杆数据。详见《[精度数据采集](./dump.md)》。
+
+4. 执行训练dump数据。
+
+5. 将CPU或GPU训练工程迁移为NPU训练工程。详见《[PyTorch模型迁移调优指南](https://www.hiascend.com/document/detail/zh/Pytorch/60RC1/ptmoddevg/trainingmigrguide/PT_LMTMOG_0003.html)》。
+
+6. 在NPU环境下安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
+
+7. 在NPU训练脚本内添加msprobe工具dump接口PrecisionDebugger采集标杆数据。详见《[精度数据采集](./dump.md)》。
+
+8. NPU环境下执行训练dump数据。
+
+9. 执行精度比对。
+
+   1. 创建并配置精度比对脚本，例如compare.py。
+
+   2. 执行CPU或GPU dump与NPU dump数据的精度比对。
+
+   3. 比对结果分析。
+
+      详见《[CPU或GPU与NPU精度数据比对](./ptdbg_ascend_compare.md)》。
+