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

msprobe/docs/15.free_benchmarking_PyTorch.md

@@ -0,0 +1,164 @@
+# PyTorch 场景的无标杆比对
+
+## 1 简介
+* 本工具的目标是在不依赖标杆数据的情况下、检测模型训练中可能存在的精度问题API级别算子，并提供升精度和tocpu接口快速验证；
+* 工具基于**数值病态分析理论**：对算子的输入增加很小的扰动、从而放大输出值异常现象；检测算子原始输出和扰动后输出间误差是否符合精度标准；
+
+* 该工具的**特点**有：
+    * 不依赖标杆模型、不需要离线对比
+    * 提供接口，对可疑算子升精度、tocpu进行快速验证
+* 推荐使用场景（针对**算子精度问题**）：
+    * **暂无标杆数据**，模型Loss异常，要做精度问题算子排查
+    * **验证可疑算子**，要做进一步确认、验证是否对模型Loss有影响
+    * 低精度模型效果不如高精度，要做精度问题算子排查
+* 该工具的约束
+    * 仅支持Pytorch2.x场景
+    * 推荐限定算子范围使用（白名单、或脚本中工具启用范围）、算子范围越大、性能和显存损耗越大；详情见[无标杆工具场景验证和性能基线报告(待补充)](./S02.report_free_benchmarking_validation_performance_baseline.md)
+
+## 2 工具实现原理
+1. **扰动算子白名单**：根据算子名识别需要插桩算子范围
+2. **扰动因子**：基于torch.nn.Module的hook机制、在注册的hook函数中对算子输入进行特定类型扰动
+3. **误差分析**：
+    * **check**: 在hook函数中二次执行算子得到扰动后的算子输出、计算扰动后输出与原始输出的相对误差，查看是否符合精度标准
+    * **fix**: 需要做验证时、可以选择将特定扰动类型（升精度、to cpu）的输出替换原始输出、观察对模型Loss是否有影响
+4. **精度风险算子**：不达标精度标准的，最终会在输出件中展示
+
+![alt text](./img/free_benchmark_framework.png)
+
+
+## 3 操作指导
+
+```mermaid
+flowchart LR
+A0[安装msprobe工具]
+subgraph config.json配置
+A1[确定插桩范围]
+A2[选择扰动因子]
+A3[选择处理方式]
+A1-->A2
+A2-->A3
+end
+B(在模型脚本中开启工具)
+C(启动模型训练)
+D(查看精度风险算子\n观察模型loss曲线)
+
+A0-->
+config.json配置-->B
+B-->C
+C-->D
+D-->config.json配置
+```
+工具的推荐使用思路是：
+
+1. 配置config.json开启精度风险算子的排查
+2. 根据精度风险算子输出件、修改config.json开启验证功能、观察模型loss曲线是否改善 
+
+### 3.1 安装msprobe工具
+参照[msprobe安装](./docs/01.installation.md)
+### 3.2 config.json配置
+修改[config.json](../config.json) 的task类型为"**free_benchmark**"开启无标杆功能。支持的配置项详见[配置文件介绍](./02.config_introduction.md)，默认配置如下：
+```json
+{
+    "task": "free_benchmark",
+    "dump_path": "./dump_path", 
+    "rank": [],  
+    "step": [],  
+    "level": "L1", 
+    "seed": 1234,
+    "is_deterministic": false, 
+
+    "free_benchmark": {
+        "scope": [], 
+        "list": [],
+        "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
+    }
+}
+```
+用户需根据自己的使用场景、对<a herf="2 工具实现原理">工具实现原理</a>中几个关键步骤进行配置
+####  3.2.1 扰动算子白名单（确定插桩范围）：
+
+| 相关参数名 | 是否必选 | 可配置项          | 适用场景                                                                                    |
+| ---------- | -------- | ----------------- | ------------------------------------------------------------------------------------------- |
+| scope      | 可选     |                   | 需要通过指定算子名来限制算子插桩范围 如：["Torch.matmul.0.forward", "Tensor.pow.4.forward"] |
+| list       | 可选     |                   | 需要通过指定算子类型来限制算子插桩范围 如：\["relu"\] 会匹配所有算子名中包含relu的算子      |
+| fuzz_stage | 可选     | "forward"（默认） | 需要进行算子**前向**计算的精度问题排查或**验证可疑算子**                                    |
+|            |          | "backward"        | 需要进行算子**反向**计算的精度问题排查，不支持仅反向验证，前向验证包括反向                  |
+
+####  3.2.2. 选择扰动因子：
+
+| 相关参数    | 是否必选 | 可配置项                     | 适用场景                                                                                                 |
+| ----------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| pert_mode   | 可选     | "improve_precision" （默认） | （常用）(可做验证) 插桩算子可能在**低精度**下有精度问题，扰动因子会将输入的低精度向量升精度              |
+|             |          | "bit_noise"                  | （常用）插桩算子可能在**轻微扰动**下暴露精度问题，扰动因子会将输入向量最后一个比特位翻转                 |
+|             |          | "add_noise"                  | 插桩算子可能在**轻微扰动**下暴露精度问题，扰动因子会为输入向量增加一个极小值                             |
+|             |          | "change_value"               | 插桩算子可能存在**大数吃小数**问题，扰动因子会交换输入向量的首尾值                                       |
+|             |          | "no_change"                  | 插桩算子可能存在**数值稳定性**精度问题，扰动因子会复制原始输入                                           |
+|             |          | "to_cpu"                     | (可做验证) 插桩算子可能在**同cpu**精度表现不一致，扰动因子会将输入转至cpu，需要配合fuzz_device="cpu"使用 |
+| fuzz_device | 可选     | "npu" （默认）                 | 扰动因子不需要to cpu操作                                                                                 |
+|             |          | "cpu"                        | 扰动因子需要to cpu操作，目前仅"to cpu"扰动因子                                                           |
+
+####  3.2.3. 选择处理方式:
+| 相关参数名   | 是否必选 | 可配置项          | 适用场景                                                                                  |
+| ------------ | -------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| handler_type | 可选     | "check"  （默认） | 要做精度问题算子排查，输出扰动前后不符合精度标准的算子，支持所有扰动因子                  |
+|              |          | "fix"             | 要做可疑算子验证，用扰动后输出替换原始输出，支持"improve_precision"、"to_cpu"两种扰动因子 |
+
+### 3.3 在模型脚本中开启工具
+
+通过PrecisionDebugger统一入口开启工具，示例如下：
+
+```python
+from msprobe.pytorch import PrecisionDebugger  
+
+debugger = PrecisionDebugger(config_path='./config.json')
+...
+debugger.start() # 一般在训练循环开头启动工具
+... # 循环体
+debugger.stop() # 一般在训练循环末尾结束工具
+debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要
+```
+
+### 3.4 启动模型训练
+训练过程中出现可以通过一下日志检查工具是否正常使用
+| 日志级别 | 日志内容                                                                                                              | 检查说明                                                                   |
+| -------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| INFO     | \[msprobe\] Free Benchmark: Perturbation is {扰动因子} of {算子名}.                                                   | 扰动因子与配置相符、算子名在插桩范围内                                     |
+| INFO     | \[msprobe\] Free Benchmark: For {算子名},{原因}. Cancel perturbation.                                                 | 算子名在插桩范围内，但当前算子由于{原因}不支持添加扰动                     |
+| INFO     | \[msprobe\] Free benchmark: preheat sample in step {step} api_name {算子名} curr_called_seq: {当前采样数}/{总采样数}" | 仅开启预热、算子名在插桩范围内，在当前step的采样情况                       |
+| WARNING  | \[msprobe\] Free benchmark: 无标杆工具不支持当前算子的输入类型 {算子名}.                                              | 算子名在插桩范围内，但当前算子没有可操作的输入（不存在Tensor、list类型等） |
+
+其余日志均说明当前算子未能正常添加扰动、请检查日志信息判断是否更换扰动因子或不考虑当前算子结果。
+
+
+### 3.5 查看精度风险算子
+
+check模式下，无标杆比对在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 类型。 |
+
+无标杆根据参照的精度标准如下：
+| 输出dtype      | 相对误差阈值 |
+| -------------- | ------------ |
+| torch.float16  | 0.002        |
+| torch.bfloat16 | 0.004        |
+| torch.float32  | 0.0002       |
+| 其他           | 0.0002       |

msprobe/{doc/grad_probe/grad_probe.md → docs/17.grad_probe.md}

@@ -1,207 +1,207 @@
-# Ascend模型梯度状态监测工具
-
-梯度状态监测工具提供了两种能力：
-
-- 将模型权重的梯度数据导出。这种功能可以将模型权重的梯度值以统计量的形式采集出来，用以分析问题。
-- 将两份梯度数据进行相似度对比。在有标杆问题中，可以确认训练过程中精度问题出现的step，以及抓取反向过程中的问题。
-
-工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。
-
-## 工具特性
-
-- 使用便捷，无需在训练流程里插入代码
-- 可以精准定位问题出现的step
-
-## 使用方式
-
-### 梯度数据导出
-
-1. 创建配置文件config.json，样例如下：
-
-   ```json
-   {
-    "task": "grad_probe",
-    "dump_path": "./dump_path", 
-    "rank": [],  
-    "step": [],  
-    "grad_probe": {
-        "grad_level": "L1",
-        "param_list": [],
-        "bounds": [-1, 0, 1]
-    }
-   }
-   ```
-   > step指的是优化器被调用的次数（并非模型跑的step，某些step，例如loss为nan时，不会调用优化器）
-
-   **参数说明**
-
-   | 参数                       | 说明                          | 输入类型                     | 是否必选 |
-   |--------------------------------|-----------------------------------|-----------------|----------|
-   | task            | 填为"grad_probe"。 |  str | 是 |
-   | grad_level                  | 输出级别。决定导出数据的详细程度，级别越大导出数据越详细。可取值：L0, L1, L2|str  | 是     |
-   | param_list             | 权重名称列表，表示需要监控的权重。列表为空就表示监控所有权重。 | List[str] | 是       |
-   | rank                   | rank id列表，在多卡场景下，表示需要导出梯度数据的进程的rank id。列表为空就表示导出所有rank的数据。（MindSpore静态图模式下，当前暂不支持指定rank功能） | List[int] | 是       |
-   | step                   | step列表，表示需要导出数据的step列表。列表为空就表示导出所有step的数据。（MindSpore静态图模式下，当前暂不支持指定step功能） | List[int] | 是 |
-   | bounds                 | 区间列表，用来划分区间以统计数值的分布。需要保证由数据小到大排列。可以使用默认值[-1, 0, 1] | List[float] | 是  |
-   | dump_path            | 输出目录。如果不存在就会创建一个新目录。 |  str | 是 |
-
-   **不同级别的level的导出数据**
-
-
-   | 级别 | 特征数据表头                                                 | 是否有方向数据 |
-   | ---- | ------------------------------------------------------------ | -------------- |
-   | L0   | ("param_name", "MD5", "max", "min", "norm", "shape")         | 否             |
-   | L1   | ("param_name", "max", "min", "norm", "shape")         | 是             |
-   | L2   | ("param_name", *intervals, "=0", "max", "min", "norm", "shape") | 是             |
-   
-   intervals就是根据值分布bounds划分出的区间。
-   MindSpore静态图模式下，L0级别中暂不支持"MD5"
-   
-   **方向数据解释**
-   
-   因为模型的参数往往非常大，所以存储真实数据是不可接受的，这里折衷一下，只存储梯度数据的正负号（一个布尔值），也就是方向。
-   
-   **bounds和值分布解释**
-   
-   + 值分布：梯度数据落在各个区间的元素个数占总元素个数的比例。
-   + bounds：一个列表，用来划分出区间以统计值分布。例如传入bounds = [-10, 0, 10]，此时有一个 grad_value: Tensor = [9.3 , 5.4, -1.0, -12.3]，依据 bounds 划分出 (-inf, -10]、(-10, 0]、(0, 10]、(10, inf) 四个区间，然后统计grad_value里的数据落在每个区间内的个数，得到 1、1、2、0。如下图所示：   
-   ![Alt text](img/image-1.png)
-
-2. 插入代码。示例代码如下：
-
-- PyTorch框架：模型构造完成后，传入config.json的路径实例化一个GradientMonitor对象，然后调用gm.monitor并将`模型`作为参数传入。
-```python
-from msprobe.pytorch import PrecisionDebugger
-debugger = PrecisionDebugger("config_json_path")
-debugger.monitor(model)
-```
-- MindSpore框架：优化器构造完成后，传入config.json的路径实例化一个GradientMonitor对象，然后调用gm.monitor并将`优化器`作为参数传入。
-```python
-from msprobe.mindspore import PrecisionDebugger
-debugger = PrecisionDebugger("config_json_path")
-debugger.monitor(optimizer)
-```
-
-3. 结束监控（MindSpore静态图模式下需要）
-
-   在训练结束之后，调用stop接口
-
-```python
-gm.stop()
-```
-
-### 输出结果
-**输出目录结构**（以level配置L2为例）
-
-```bash
-{dump_path}
-      ├── rank{rank_id}
-      │        ├── grad_summary_{step}.csv
-      │        ├── step{step}
-      │        │        ├── {param_name}.npy
-```
-+ {timestamp}：梯度工具导出数据的时候会在output_path下生成一个时间戳目录，然后在这个时间戳目录下输出结果。
-+ rank_{rank_id}：在分布式场景下，会记录卡的rank_id。非分布式场景下，如果是CPU则记录进程号，如果是CPU或GPU则记录卡号
-+ grad_summary_{step}.csv：会分step记录每一步的梯度数据统计值。
-+ step_{step}：这个目录下会存放该step的梯度的方向数据。
-+ {param_name}.pt(npy)：模型参数的梯度方向数据，PyTorch保存的是pt文件，MindSpore是npy文件。
-
-**grad_summary_{step}.csv**
-
-样例如下：
-
-![Alt text](img/image.png)
-
-| 字段                  | 含义                                                         |
-| --------------------- | ------------------------------------------------------------|
-| Param_name            | 模型参数名称。                                                |
-| MD5                   | 梯度数据的MD5值。                                            |
-| (-inf, -0.01]...[0.01, inf) | 梯度值落在区间内的元素个数占总元素的比例。               |
-| =0                    | 梯度为0的元素个数占总元素的比例。                             |
-| Max                   | 最大值。                                                      |
-| Min                   | 最小值。                                                      |
-| Norm                  | L2norm值。                                                    |
-| Shape                 | 形状。                                                        |
-
-### 梯度相似度比对
-
-会根据所导出的权重，分step比对梯度相似度，输出每个权重的梯度相似度和总的梯度相似度。单个权重的梯度相似度为两份方向数据的重合度，总的梯度相似度为每个权重的梯度相似度按元素个数加权。
-
-#### 前提条件
-
-- 相同配置下，以Level为L1或L2分别采集npu和gpu环境下的梯度数据。
-- 将两份梯度数据传到同一环境下。
-
-#### 使用方式
-
-
-新建如下Python脚本，传入npu和gpu的dump_path以及输出目录，比对结果输出目录不存在的话会新建：
-
-```python
-from msprobe import *
-GradComparator.compare_distributed("配置文件里写的dump_path",
-                                    "配置文件里写的dump_path",
-                                    "比对结果输出目录")
-```
-   
-
-### 比对结果
-
-**输出目录结构**
-
-如下为多卡比对结果，单卡则没有rank_{rank_id}这一级目录。
-
-```bash
-比对结果输出目录
-      ├── rank{rank_id}
-      │         ├── similarities.csv
-      │         └── similarities_picture
-      │                     ├── {param_name}.png
-      │                     └── summary_similarities.png
-```
-
-**问题界定**
-
-原则：对于任意权重，第0步的梯度相似度低于0.97，或者某一步的梯度相似度下降超过0.03，认为这一步存在精度问题。例子如下：
-
-- 第0步相似度低于0.97
-
-![Alt text](img/image-3.png)
-
-- 第3步相似度下降超过0.03
-
-![Alt text](img/image-4.png)
-
-- 正常情况
-
-![Alt text](img/image-2.png)
-
-这个原则是一个经验性的指标，并不是严格的标注，还需要结合实际情况具体分析。
-
-## 公开接口
-
-**接口说明**
-
-```python
-PrecisionDebugger.monitor(module)
-```
-
-| 参数  | 说明                 | 是否必选 |
-| ----- | -------------------- | -------- |
-| module |Pytorch框架下传入模型，必须是torch.nn.Module；MindSpore框架下传入优化器。 | 是       |
-
-
-**接口说明**
-
-```python
-GradComparator.compare_distributed(dump_path1, dump_path2, output_path)
-```
-
-| 参数  | 说明                 | 是否必选 |
-| ----- | -------------------- | -------- |
-| dump_path1 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path。 | 是       |
-| dump_path2 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path，与dump_path1可以互换。 | 是       |
-| output_path |输出结果目录，不存在会新建。 | 是       |
-
-
-# FAQ 
+# Ascend模型梯度状态监测工具
+
+梯度状态监测工具提供了两种能力：
+
+- 将模型权重的梯度数据导出。这种功能可以将模型权重的梯度值以统计量的形式采集出来，用以分析问题。
+- 将两份梯度数据进行相似度对比。在有标杆问题中，可以确认训练过程中精度问题出现的step，以及抓取反向过程中的问题。
+
+工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。
+
+## 工具特性
+
+- 使用便捷，无需在训练流程里插入代码
+- 可以精准定位问题出现的step
+
+## 使用方式
+
+### 梯度数据导出
+
+1. 创建配置文件config.json，样例如下：
+
+   ```json
+   {
+    "task": "grad_probe",
+    "dump_path": "./dump_path", 
+    "rank": [],  
+    "step": [],  
+    "grad_probe": {
+        "grad_level": "L1",
+        "param_list": [],
+        "bounds": [-1, 0, 1]
+    }
+   }
+   ```
+   > step指的是优化器被调用的次数（并非模型跑的step，某些step，例如loss为nan时，不会调用优化器）
+
+   **参数说明**
+
+   | 参数                       | 说明                          | 输入类型                     | 是否必选 |
+   |--------------------------------|-----------------------------------|-----------------|----------|
+   | task            | 填为"grad_probe"。 |  str | 是 |
+   | dump_path            | 输出目录。如果不存在就会创建一个新目录。 |  str | 是 |
+   | rank                   | rank id列表，在多卡场景下，表示需要导出梯度数据的进程的rank id。列表为空就表示导出所有rank的数据。默认为空。（MindSpore静态图模式下，当前暂不支持指定rank功能） | List[int] | 否       |
+   | step                   | step列表，表示需要导出数据的step列表。列表为空就表示导出所有step的数据。默认为空。（MindSpore静态图模式下，当前暂不支持指定step功能） | List[int] | 否 |
+   | grad_level                  | 输出级别。决定导出数据的详细程度，级别越大导出数据越详细。可取值：L0, L1, L2。默认L1。|str  | 否     |
+   | param_list             | 权重名称列表，表示需要监控的权重。列表为空就表示监控所有权重。默认为空。 | List[str] | 否       |
+   | bounds                 | 区间列表，用来划分区间以统计数值的分布。需要保证由数据小到大排列。可以使用默认值[-1, 0, 1]。 | List[float, int] | 否  |
+
+   **不同级别的level的导出数据**
+
+
+   | 级别 | 特征数据表头                                                 | 是否有方向数据 |
+   | ---- | ------------------------------------------------------------ | -------------- |
+   | L0   | ("param_name", "MD5", "max", "min", "norm", "shape")         | 否             |
+   | L1   | ("param_name", "max", "min", "norm", "shape")         | 是             |
+   | L2   | ("param_name", *intervals, "=0", "max", "min", "norm", "shape") | 是             |
+   
+   intervals就是根据值分布bounds划分出的区间。
+   MindSpore静态图模式下，L0级别中暂不支持"MD5"
+   
+   **方向数据解释**
+   
+   因为模型的参数往往非常大，所以存储真实数据是不可接受的，这里折衷一下，只存储梯度数据的正负号（一个布尔值），也就是方向。
+   
+   **bounds和值分布解释**
+   
+   + 值分布：梯度数据落在各个区间的元素个数占总元素个数的比例。
+   + bounds：一个列表，用来划分出区间以统计值分布。例如传入bounds = [-10, 0, 10]，此时有一个 grad_value: Tensor = [9.3 , 5.4, -1.0, -12.3]，依据 bounds 划分出 (-inf, -10]、(-10, 0]、(0, 10]、(10, inf) 四个区间，然后统计grad_value里的数据落在每个区间内的个数，得到 1、1、2、0。如下图所示：   
+   ![Alt text](./img/grad_probe_image-1.png)
+
+2. 插入代码。示例代码如下：
+
+- PyTorch框架：模型构造完成后，传入config.json的路径实例化一个GradientMonitor对象，然后调用gm.monitor并将`模型`作为参数传入。
+```python
+from msprobe.pytorch import PrecisionDebugger
+debugger = PrecisionDebugger("config_json_path")
+debugger.monitor(model)
+```
+- MindSpore框架：优化器构造完成后，传入config.json的路径实例化一个GradientMonitor对象，然后调用gm.monitor并将`优化器`作为参数传入。
+```python
+from msprobe.mindspore import PrecisionDebugger
+debugger = PrecisionDebugger("config_json_path")
+debugger.monitor(optimizer)
+```
+
+3. 结束监控（MindSpore静态图模式下需要）
+
+   在训练结束之后，调用stop接口
+
+```python
+debugger.stop()
+```
+
+### 输出结果
+**输出目录结构**（以level配置L2为例）
+
+```bash
+{dump_path}
+      ├── rank{rank_id}
+      │        ├── grad_summary_{step}.csv
+      │        ├── step{step}
+      │        │        ├── {param_name}.npy
+```
++ {timestamp}：梯度工具导出数据的时候会在output_path下生成一个时间戳目录，然后在这个时间戳目录下输出结果。
++ rank_{rank_id}：在分布式场景下，会记录卡的rank_id。非分布式场景下，如果是CPU则记录进程号，如果是CPU或GPU则记录卡号
++ grad_summary_{step}.csv：会分step记录每一步的梯度数据统计值。
++ step_{step}：这个目录下会存放该step的梯度的方向数据。
++ {param_name}.pt(npy)：模型参数的梯度方向数据，PyTorch保存的是pt文件，MindSpore是npy文件。
+
+**grad_summary_{step}.csv**
+
+样例如下：
+
+![Alt text](./img/grad_probe_image.png)
+
+| 字段                  | 含义                                                         |
+| --------------------- | ------------------------------------------------------------|
+| Param_name            | 模型参数名称。                                                |
+| MD5                   | 梯度数据的MD5值。                                            |
+| (-inf, -0.01]...[0.01, inf) | 梯度值落在区间内的元素个数占总元素的比例。               |
+| =0                    | 梯度为0的元素个数占总元素的比例。                             |
+| Max                   | 最大值。                                                      |
+| Min                   | 最小值。                                                      |
+| Norm                  | L2norm值。                                                    |
+| Shape                 | 形状。                                                        |
+
+### 梯度相似度比对
+
+会根据所导出的权重，分step比对梯度相似度，输出每个权重的梯度相似度和总的梯度相似度。单个权重的梯度相似度为两份方向数据的重合度，总的梯度相似度为每个权重的梯度相似度按元素个数加权。
+
+#### 前提条件
+
+- 相同配置下，以Level为L1或L2分别采集npu和gpu环境下的梯度数据。
+- 将两份梯度数据传到同一环境下。
+
+#### 使用方式
+
+
+新建如下Python脚本，传入npu和gpu的dump_path以及输出目录，比对结果输出目录不存在的话会新建：
+
+```python
+from msprobe import *
+GradComparator.compare_distributed("配置文件里写的dump_path",
+                                    "配置文件里写的dump_path",
+                                    "比对结果输出目录")
+```
+   
+
+### 比对结果
+
+**输出目录结构**
+
+如下为多卡比对结果，单卡则没有rank_{rank_id}这一级目录。
+
+```bash
+比对结果输出目录
+      ├── rank{rank_id}
+      │         ├── similarities.csv
+      │         └── similarities_picture
+      │                     ├── {param_name}.png
+      │                     └── summary_similarities.png
+```
+
+**问题界定**
+
+原则：对于任意权重，第0步的梯度相似度低于0.97，或者某一步的梯度相似度下降超过0.03，认为这一步存在精度问题。例子如下：
+
+- 第0步相似度低于0.97
+
+![Alt text](./img/grad_probe_image-3.png)
+
+- 第3步相似度下降超过0.03
+
+![Alt text](./img/grad_probe_image-4.png)
+
+- 正常情况
+
+![Alt text](./img/grad_probe_image-2.png)
+
+这个原则是一个经验性的指标，并不是严格的标注，还需要结合实际情况具体分析。
+
+## 公开接口
+
+**接口说明**
+
+```python
+PrecisionDebugger.monitor(module)
+```
+
+| 参数  | 说明                 | 是否必选 |
+| ----- | -------------------- | -------- |
+| module |Pytorch框架下传入模型，必须是torch.nn.Module；MindSpore框架下传入优化器。 | 是       |
+
+
+**接口说明**
+
+```python
+GradComparator.compare_distributed(dump_path1, dump_path2, output_path)
+```
+
+| 参数  | 说明                 | 数据类型 | 是否必选 |
+| ----- | -------------------- | -------- | ----- |
+| dump_path1 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path。 | str | 是       |
+| dump_path2 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path，与dump_path1可以互换。 | str | 是       |
+| output_path |输出结果目录，不存在会新建。 | str | 是       |
+
+
+# FAQ