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

msprobe/pytorch/doc/dump.md

@@ -1,260 +0,0 @@
-# **精度数据采集**
-
-msprobe工具主要通过在训练脚本内添加dump接口并启动训练的方式来采集精度数据。
-
-执行dump操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
-
-## dump接口介绍
-
-### PrecisionDebugger
-
-**功能说明**
-
-通过加载dump配置文件的方式来确定dump操作的详细配置。
-
-PrecisionDebugger接口可以在from msprobe.pytorch import PrecisionDebugger之后的位置添加。详细使用可参考“**示例代码**”或“**model配置代码示例**”。
-
-**原型**
-
-```Python
-PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, model=None, step=None)
-```
-
-说明：上述参数除config_path和model外，其他参数均在[config.json](../../config)文件中可配，此处的参数优先级高于[config.json](../../config)文件中的配置，而config.json文件可以配置更多参数，若需要进行更多场景的精度数据dump，建议配置[config.json](../../config)文件。config.json文件的配置可参考《[配置文件说明](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/config/README.md)》。
-
-**参数说明**
-
-| 参数名      | 说明                                                         | 是否必选 |
-| ----------- | ------------------------------------------------------------ | -------- |
-| config_path | 指定dump配置文件路径，String类型。参数示例："./config.json"。未配置该路径时，默认使用[config.json](../../config)文件的默认配置。 | 否       |
-| task        | dump的任务类型，String类型。可取值"statistics"（仅dump API统计信息）、"tensor"（dump API统计信息和完全复刻整网的API运行情况的真实数据）、"overflow_check"（溢出检测），默认未配置，取"statistics"，参数示例：task="tensor"。 | 否       |
-| dump_path   | 设置dump数据目录路径，String类型。参数示例：dump_path="./dump_path"。 | 否       |
-| level       | dump级别，根据不同级别dump不同数据，String类型。可取值：<br>        "L0"：dump module模块级精度数据，仅PyTorch场景支持”。<br/>        "L1"：dump API级精度数据，默认值。<br/>        "L2"：dump kernel级精度数据。<br/>        "mix"：dump module模块级和API级精度数据。<br/>配置示例：level="L1"。 | 否       |
-| model       | 指定具体的torch.nn.Module，默认未配置，level配置为"L0"或"mix"时必须配置该参数。配置示例参见“**model配置代码示例**”。 | 否       |
-| step        | 指定dump某个step的数据，list[int]类型。默认未配置，表示dump所有step数据。dump特定step时，须指定为训练脚本中存在的step。step为list格式，可配置逐个step，例如：step=[0,1,2]。 | 否       |
-
-#### model配置代码示例
-
-示例中定义了一个nn.Module类型的简单网络，在进行数据dump时使用原型函数PrecisionDebugger并传入config_path参数和model参数，其中model参数传入数据的类型为torch.nn.Module类型或torch.nn.Module子类型。
-
-```python
-#根据需要import包
-import os
-import torch
-import torch.nn as nn
-import torch_npu
-import torch.nn.functional as F
-from msprobe.pytorch import PrecisionDebugger
-
-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)
-
-	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()
-```
-
-### start函数
-
-**功能说明**
-
-dump启动函数。
-
-在模型初始化之后的位置添加。需要与stop函数一起添加在for循环内。
-
-**原型**
-
-```Python
-debugger.start()
-```
-
-该函数为类函数，可以使用debugger.start()也可以使用PrecisionDebugger.start()。
-
-### stop函数
-
-**功能说明**
-
-dump停止函数。
-
-在**start**函数之后的任意位置添加。若需要dump反向数据，则需要添加在反向计算代码（如loss.backward）之后。
-
-**原型**
-
-```Python
-debugger.stop()
-```
-
-该函数为类函数，可以使用debugger.stop()也可以使用PrecisionDebugger.stop()。
-
-### forward_backward_dump_end函数
-
-**功能说明**
-
-dump停止函数。用于dump指定代码的前反向数据。
-
-在**start**函数之后，反向计算代码（如loss.backward）之前的任意位置添加，可以dump **start**函数和该函数之间的前反向数据，可以通过调整**start**函数与该函数的位置，来指定需要dump的代码块。
-
-要求**stop**函数添加在反向计算代码（如loss.backward）之后，此时该函数与**stop**函数之间的代码不会被dump。
-
-使用示例参见“**示例代码 > 扩展示例**”。
-
-**原型**
-
-```Python
-forward_backward_dump_end()
-```
-
-该函数为类函数，可以使用debugger.forward_backward_dump_end()也可以使用PrecisionDebugger.forward_backward_dump_end()。
-
-### step函数
-
-**功能说明**
-
-结束标识。
-
-在最后一个**stop**函数后或一个step结束的位置添加。需要与start函数一起添加在for循环内。
-
-**原型**
-
-```Python
-debugger.step()
-```
-
-该函数为类函数，可以使用debugger.step()也可以使用PrecisionDebugger.step()。
-
-## 示例代码
-
-### 基础操作
-
-如下示例可dump完整代码的前反向数据。
-
-```Python
-from msprobe.pytorch import PrecisionDebugger
-
-# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
-debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
-
-# 模型、损失函数的定义及初始化等操作
-# ...
-
-# 数据集迭代的位置一般为模型训练开始的位置
-for data, label in data_loader:
-	debugger.start() # 开启数据dump
-
-	# 如下是模型每个step执行的逻辑
-    output = model(data)
-    #...
-    loss.backward()
-
-	debugger.stop() # 关闭数据dump
-	debugger.step() # 结束一个step的dump
-```
-
-### 扩展示例
-
-如下示例dump指定代码块前反向数据。
-
-```Python
-from msprobe.pytorch import PrecisionDebugger
-
-# 请勿将PrecisionDebugger的初始化流程插入到循环代码中
-debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path")
-
-# 模型、损失函数的定义及初始化等操作
-# ...
-
-# 数据集迭代的位置一般为模型训练开始的位置
-for data, label in data_loader:
-	debugger.start() # 开启数据dump
-
-	# 如下是模型每个step执行的逻辑
-    output = model(data)
-    debugger.forward_backward_dump_end() # 插入该函数到start函数之后，只dump start函数到该函数之间代码的前反向数据，本函数到stop函数之间的数据则不dump
-    #...
-    loss.backward()
-
-	debugger.stop() # 关闭数据dump
-	debugger.step() # 结束一个step的dump
-```
-
-## dump结果文件介绍
-
-训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。
-
-dump结果目录结构示例如下：
-
-```Python
-├── dump_path
-│   ├── step0
-│   |   ├── rank0
-│   |   │   ├── dump_tensor_data
-|   |   |   |    ├── Tensor.permute.1.forward.pt
-|   |   |   |    ├── MyModule.0.forward.input.pt        # 开启模块级精度数据dump时存在模块级的dump数据文件
-|   |   |   |    ...
-|   |   |   |    └── 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        # 分层分级结构
-│   |   ├── rank1
-|   |   |   ├── dump_tensor_data
-|   |   |   |   └── ...
-│   |   |   ├── dump.json
-│   |   |   ├── stack.json
-|   |   |   └── construct.json
-│   |   ├── ...
-│   |   |
-|   |   └── rank7
-│   ├── step1
-│   |   ├── ...
-│   ├── step2
-```
-
-dump过程中，pt文件在对应算子或者模块被执行后就会落盘，而json文件则需要在正常执行PrecisionDebugger.stop()后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关npy文件，可能会导致json文件中数据丢失。
-
-其中rank为设备上各卡的ID，每张卡上dump的数据会生成对应dump目录。非分布式场景下没有rank ID，目录名称为rank。
-
-pt文件保存的前缀和PyTorch对应关系如下：
-
-| 前缀        | Torch模块           |
-| ----------- | ------------------- |
-| Tensor      | torch.Tensor        |
-| Torch       | torch               |
-| Functional  | torch.nn.functional |
-| NPU         | NPU亲和算子         |
-| VF          | torch._VF           |
-| Aten        | torch.ops.aten      |
-| Distributed | torch.distributed   |
-
-## 工具支持的API列表
-
-msprobe工具维护固定的API支持列表，若需要删除或增加dump的API，可以在msprobe/pytorch/hook_module/support_wrap_ops.yaml文件内手动修改，如下示例：
-
-```Python
-functional:  # functional为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API
-  - conv1d
-  - conv2d
-  - conv3d
-```
-
-# FAQ
-
-[FAQ](./FAQ.md)

msprobe/pytorch/doc/msprobe/321/207/342/226/223/342/225/233/321/205/342/225/221/320/266/321/205/342/225/226/320/265/321/205/320/225/342/225/226/321/206/320/245/342/226/221/321/206/320/235/320/276dump/321/206/320/260/320/227/321/205/320/227/320/226/321/206/320/220/320/267/321/210/320/223/342/225/234/321/205/320/257/342/225/221/321/207/342/225/221/342/224/220/321/206/320/232/320/265/321/205/320/241/320/232.md

@@ -1,182 +0,0 @@
-# msprobe精度工具标准性能基线报告
-
-## 环境信息
-
-NPU：Atlas A2 训练系列产品
-
-CPU：
-
-![输入图片说明](img/cpu_info.png)
-
-Torch：2.1.0
-
-CANN：8.0.T2
-
-除上述环境信息影响性能外，API的数量、种类以及Shape都会对性能产生影响，因此本次选取指定网络进行测试，为了避免算子编译耗时的影响，所有模型运行时都开启二进制，模型中添加torch.npu.set_compile_mode(jit_compile=False)，所有模型都dump第二个step的数据。
-
-## 模型信息和性能基线
-
-大模型在使用msprobe工具dump数据时，建议先简化模型层数，减少dump数据量。
-
-以下场景的性能基线测试数据均为多次测试后取平均值，因此实际运行时性能数据可能会根据环境状态稍有浮动。
-
-### 工具配置信息
-
-dump全部API级别输入输出数据以及相应堆栈信息，配置如下：
-
-```python
-debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="dump")
-debugger.configure_hook(mode="api_stack")
-```
-
-多卡指定rank0 dump，配置如下：
-
-```python
-debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="dump",rank=0)
-debugger.configure_hook(mode="api_stack")
-```
-
-dump保存API统计信息的pkl文件，配置如下：
-
-```python
-debugger = PrecisionDebugger(dump_path="./dump_path", hook_name="dump")
-debugger.configure_hook(mode="api_stack", summary_only=True)
-```
-
-### YOLOV5s
-
-单卡
-
-主要数据类型：FLOAT32
-
-启动命令参数：python3 train_ptdbg.py --data ./data/coco.yaml --cfg yolov5s.yaml --weights '' --epochs 1 --batch-size 8 --device 1
-
-dump保存API统计信息的pkl文件耗时：**7s**
-
-进行单卡dump全部API级别输入输出数据以及相应堆栈信息耗时：**11s**
-
-- dump存盘的API numpy文件大小：13G
-
-  ![输入图片说明](img/YOLOV5S_1.png)
-
-- api numpy文件数量：3009个
-
-  ![输入图片说明](img/YOLOV5S_2.png)
-
-
-
-
-### GPT-3
-
-#### NUM_LAYER：1
-
-8卡
-
-主要数据类型：FLOAT16
-
-启动命令参数：
-
-```
-python3 -m torch.distributed.launch $DISTRIBUTED_ARGS ../../pretrain_gpt_ptdbg.py --num-layers 1 --hidden-size 12288 --num-attention-heads 24 --micro-batch-size 2 --global-batch-size 2 --seq-length 1024 --max-position-embeddings 1024 --train-iters 10 --lr-decay-iters 320000 --save $CHECKPOINT_PATH --load $CHECKPOINT_PATH --data-path $DATA_PATH --tensor-model-parallel-size 8 --use-distributed-optimizer --pipeline-model-parallel-size 8 --vocab-file gpt2-vocab.json --merge-file gpt2-merges.txt --data-impl mmap --split 949,50,1 --distributed-backend nccl --lr 0.375e-5 --lr-decay-style cosine --min-lr 0.375e-6 --weight-decay 0.1 --clip-grad 1.0 --lr-warmup-fraction .01 --adam-beta1 0.9 --adam-beta2 0.95 --init-method-std 0.006
---recompute-granularity full --recompute-method uniform --no-gradient-accumulation-fusion --log-interval 1 --save-interval 10000 --eval-interval 1000 --eval-iters 10 --fp16
-```
-
-dump保存API统计信息的pkl文件耗时：**3.3s**
-
-进行8卡dump全部API级别输入输出数据以及相应堆栈信息耗时：**53s**
-
-- dump存盘的api numpy文件大小：145G
-
-  ![输入图片说明](img/GPT-3_1.png)
-
-- API numpy文件数量：5130个
-
-  ![输入图片说明](img/GPT-3_2.png)
-
-
-**经测试8卡同时写入磁盘已达到磁盘I/O上限，工具的dump速度取决于磁盘性能，本机环境多进程写入磁盘上限为3GB/秒左右，理论上保存145GB的数据需要50秒左右，如果dump的数据中包含许多的小文件，那么耗时将会更久。**
-
-指定rank0 dump耗时：**9s**
-
-- dump存盘的api numpy文件大小：19G
-
-  ![输入图片说明](img/GPT-3_3.png)
-
-- api numpy文件数量：643个
-
-  ![输入图片说明](img/GPT-3_4.png)
-
-
-#### NUM_LAYER：8
-
-8卡
-
-主要数据类型：FLOAT16
-
-启动命令参数：
-
-```
-python3 -m torch.distributed.launch $DISTRIBUTED_ARGS ../../pretrain_gpt_ptdbg.py --num-layers 8 --hidden-size 12288 --num-attention-heads 24 --micro-batch-size 2 --global-batch-size 2 --seq-length 1024 --max-position-embeddings 1024 --train-iters 10 --lr-decay-iters 320000 --save $CHECKPOINT_PATH --load $CHECKPOINT_PATH --data-path $DATA_PATH --tensor-model-parallel-size 8 --use-distributed-optimizer --pipeline-model-parallel-size 8 --vocab-file gpt2-vocab.json --merge-file gpt2-merges.txt --data-impl mmap --split 949,50,1 --distributed-backend nccl --lr 0.375e-5 --lr-decay-style cosine --min-lr 0.375e-6 --weight-decay 0.1 --clip-grad 1.0 --lr-warmup-fraction .01 --adam-beta1 0.9 --adam-beta2 0.95 --init-method-std 0.006 --recompute-granularity full --recompute-method uniform --no-gradient-accumulation-fusion --log-interval 1 --save-interval 10000 --eval-interval 1000 --eval-iters 10 --fp16
-```
-
-dump保存API统计信息的pkl文件耗时：**6.7s**
-
-进行8卡dump全部API级别输入输出数据以及相应堆栈信息耗时：**323s**
-
-- dump存盘的API numpy文件大小：878G
-
-  ![输入图片说明](img/GPT-3_5.png)
-
-- API numpy文件数量：24002个
-
-  ![输入图片说明](img/GPT-3_6.png)
-
-
-指定rank0 dump耗时：**47s**
-
-- dump存盘的API numpy文件大小：110G
-
-  ![输入图片说明](img/GPT-3_7.png)
-
-- API numpy文件数量：3002个
-
-  ![输入图片说明](img/GPT-3_8.png)
-
-
-### BLOOM-7B
-
-8卡
-
-NUM_LAYER：1
-
-主要数据类型：BFLOAT16
-
-启动命令参数：
-
-```
-python -m torch.distributed.launch $DISTRIBUTED_ARGS pretrain_llama.py --DDP-impl local --tensor-model-parallel-size 8 --pipeline-model-parallel-size 1 --sequence-parallel --num-layers 1 --hidden-size 12288 --position-embedding-type rope --normalization RMSNorm --ffn-hidden-size 11008 --num-attention-heads 24 --attention-dropout 0.0 --hidden-dropout 0.0 --init-method-std 0.01 --micro-batch-size 2 --global-batch-size 2 --seq-length 1024 --max-position-embeddings 1024 --data-path $DATA_PATH --tokenizer-name-or-path $TOKENIZER_PATH --tokenizer-not-use-fast --split 100,0,0 --distributed-backend nccl --lr 1.25e-5 --min-lr 1.25e-6 --lr-decay-style cosine --weight-decay 1e-1 --clip-grad 1.0 --initial-loss-scale 65536.0 --adam-beta1 0.9 --adam-beta2 0.95 --log-interval 1 --load ${LOAD_CHECKPOINT_PATH} --save ${SAVE_CHECKPOINT_PATH} --save-interval 10000 --eval-interval 10000 --eval-iters 0 --use-fused-rotary-pos-emb --no-masked-softmax-fusion --no-load-optim --no-load-rng --train-iters 20 --lr-warmup-fraction 0.01 --mlp-layer-fusion --use-flash-attn --use-fused-rmsnorm --bf16
-```
-
-dump保存API统计信息的pkl文件耗时：**3s**
-
-进行8卡dump全部API级别输入输出数据以及相应堆栈信息耗时：**61s**
-
-- dump存盘的API numpy文件大小：160G
-
-  ![输入图片说明](img/BLOOM-7B_1.png)
-
-- API numpy文件数量：4924个
-
-  ![输入图片说明](img/BLOOM-7B_2.png)
-
-
-指定rank0 dump耗时：**17s**
-
-- dump存盘的API numpy文件大小：20G
-
-  ![输入图片说明](img/BLOOM-7B_3.png)
-
-- API numpy文件数量：633个
-
-  ![输入图片说明](img/BLOOM-7B_4.png)
-

msprobe/pytorch/doc/ptdbg_ascend_compare.md

@@ -1,240 +0,0 @@
-# **精度比对工具**
-
-## 总体说明
-
-- 本节主要介绍通过命令行方式和比对函数方式进行CPU或GPU与NPU的精度数据比对，执行精度比对操作前需要先完成CPU或GPU与NPU的精度数据dump，参见《[精度数据采集](./dump.md)》。
-
-- 训练精度一体化工具msprobe，使用子命令compare进行比对，可支持单卡和多卡场景的精度数据比对。
-
-- 比对函数均通过单独创建精度比对脚本执行，可支持单卡和多卡场景的精度数据比对。
-
-- 工具性能：比对数据量较小时（参考值单份文件小于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忽略。
-
-## 命令行方式比对
-
-将CPU或GPU与NPU的dump文件进行比对，支持单卡和多卡，可同时比对多卡的dump数据。多机场景需要每个设备单独执行比对操作。
-
-请先参见《[精度数据采集](./dump.md)》完成CPU或GPU与NPU的精度数据dump。
-
-### 操作步骤
-
-1. 创建比对文件，文件内容及示例请参见“**比对文件**”。
-
-2. 执行如下示例命令进行比对：
-
-   ```shell
-   msprobe -f pytorch compare -i ./compare.json -o ./output -s
-   ```
-
-   **完整参数说明**
-
-   | 参数名               | 说明                                                                                                                                                                                                 | 是否必选 |
-   |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
-   | -i或--input_path   | 指定比对文件路径。比对文件内容及示例请参见“**比对文件**”。                                                                                                                                                                   | 是       |
-   | -o或--output_path  | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。                                                                                                                                  | 是       |
-   | -s或--stack_mode   | 配置stack_mode的开关。仅当**比对文件**配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                                                               | 否       |
-   | -c或--compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否       |
-   | -f或--fuzzy_match  | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。                                                                                                                                  | 否       |
-
-3. 查看比对结果，请参见“**比对结果分析**”。
-
-### 比对文件
-
-以在当前目录创建./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。          | 单卡必选，多卡不选 |
-| is_print_compare_log | 配置是否开启日志打屏。可取值True或False。数据类型：bool      | 否                 |
-
-## 比对函数方式比对
-
-### 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": "./bench_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
-input_param={
-"npu_json_path": "./npu_dump/dump.json",
-"bench_json_path": "./bench_dump/dump.json",
-"stack_json_path": "./npu_dump/stack.json",
-"is_print_compare_log": True
-}
-compare(input_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
-input_param={
-"npu_json_path": "./npu_dump/dump.json",
-"bench_json_path": "./bench_dump/dump.json",
-"stack_json_path": "./npu_dump/stack.json",
-"is_print_compare_log": True
-}
-compare(input_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)
-