mindstudio-probe 1.0.1__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/docs/17.grad_probe.md

@@ -0,0 +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 | 是 |
+   | 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 

msprobe/docs/FAQ_PyTorch.md

@@ -0,0 +1,177 @@
+# 1 精度预检工具
+
+1. 预检工具在 dump 和 run_ut 的过程中，是否需要同时开启或关闭 jit 编译（jit_compile）？
+
+   答：是。
+
+2. 预检工具对于 type_as 这类涉及数据类型转换操作的 API，是否具有参考性？
+
+   由于这类 API 在 CPU 侧存在精度先提升后下降的操作，因此这类 API 的有效性的参考价值有限。
+
+3. run ut 过程中出现报错：ERROR: Got unsupported ScalarType BFloat16。
+
+   答：请使用最新版本的工具。
+
+4. Dropout 算子，CPU 和 NPU 的随机应该不一样，为什么结果比对是一致的？
+
+   答：这个结果是正常的，工具对该算子有特殊处理，只判定位置为 0 的位置比例大约和设定 p 值相当。
+
+5. 为什么浮点型数据 bench 和 CPU 的 dtype 不一致？
+
+   答：对于 fp16 的数据，CPU 会上升一个精度 fp32 去计算，这是和算子那边对齐的精度结论，CPU 用更高精度去计算会更接近真实值。
+
+6. 添加预检工具后截取操作报错：`IndexError: too many indices for tensor of dimension x` 或 `TypeError: len() of a 0-d tensor`。
+
+   答：注释工具目录 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中 Tensor: 下的 `- __getitem__`，工具会跳过采集该 API。如果是需要 dump 关键位置 API 也可以考虑根据报错堆栈信息注释引发报错的类型检查。
+
+7. Tensor 魔法函数具体对应什么操作？
+
+   答：
+
+   | Tensor魔法函数  | 具体操作         |
+   | --------------- | ---------------- |
+   | `__add__`       | +                |
+   | `__and__`       | &                |
+   | `__bool__`      | 返回 Tensor 布尔值 |
+   | `__div__`       | /                |
+   | `__eq__`        | ==               |
+   | `__ge__`        | >=               |
+   | `__gt__`        | >                |
+   | `__iadd__`      | +=               |
+   | `__iand__`      | &=               |
+   | `__idiv__`      | /=               |
+   | `__ifloordiv__` | //=              |
+   | `__ilshift__`   | <<=              |
+   | `__imod__`      | %=               |
+   | `__imul__`      | *=               |
+   | `__ior__`       | \|=              |
+   | `__irshift__`   | >>=              |
+   | `__isub__`      | -=               |
+   | `__ixor__`      | ^=               |
+   | `__lshift__`    | <<               |
+   | `__matmul__`    | 矩阵乘法         |
+   | `__mod__`       | %                |
+   | `__mul__`       | *                |
+   | `__nonzero__`   | 同`__bool__`     |
+   | `__or__`        | \|               |
+   | `__radd__`      | +（反向）        |
+   | `__rmul__`      | *（反向）        |
+   | `__rshift__`    | >>               |
+   | `__sub__`       | -                |
+   | `__truediv__`   | 同`__div__`      |
+   | `__xor__`       | ^                |
+
+# 2 精度比对工具
+
+## 2.1 工具使用
+
+### 2.1.1 dump 指定融合算子
+
+数据采集当前支持融合算子的输入输出，需要在 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 中添加，比如以下代码段调用的 softmax 融合算子。
+
+```python
+def npu_forward_fused_softmax(self, input_, mask):
+    resl = torch_npu.npu_scaled_masked_softmax(input_, mask, self.scale, False)
+    return resl
+```
+
+如果需要 dump 其中调用的 npu_scaled_masked_softmax 算子的输入输出信息，需要在 `support_wrap_ops.yaml` 中的 `torch_npu: ` 中自行添加该融合算子：
+
+```yaml
+- npu_scaled_masked_softmax
+```
+
+（npu_scaled_masked_softmax 融合算子工具已支持 dump，本例仅供参考）。
+
+## 2.2 常见问题
+
+1. 在同一个目录多次执行 dump 会冲突吗？
+
+    答：会，同一个目录多次 dump，会覆盖上一次结果，可以使用 dump_path 参数修改 dump 目录。
+
+2. 如何 dump 算子级的数据？
+   
+   答：需要配置 level 为 L2 模式。
+
+3. 工具比对发现 NPU 和标杆数据的 API 无法完全对齐？
+
+    答：torch 版本和硬件差异属于正常情况。
+
+## 2.3 异常情况
+
+1. HCCL 报错： error code: EI0006。
+
+    **故障现象**：使用 msprobe 工具时，报错：error code: EI0006。
+
+    **故障原因**：CANN 软件版本较低导致不兼容。
+
+    **故障处理**：升级新版 CANN 软件版本。
+
+2. torch_npu._C._clear_overflow_npu() RuntimeError NPU error，error code is 107002。
+
+    如果运行溢出检测功能遇到这个报错，采取以下解决方法：
+
+    如果是单卡运行，添加如下代码，0 是卡号，选择自己空闲的卡号。
+
+    ```python
+    torch.npu.set_device('npu:0')
+    ```
+
+    如果多卡运行，请在代码中修改对应卡号，比如进程使用卡号为 {rank} 时可以添加如下代码：
+
+    ```python
+    torch.npu.set_device(f'npu:{rank}')
+    ```
+
+    如果运行精度比对功能遇到这个报错，尝试安装最新版本的 msprobe。
+
+3. dump 得到的 `VF_lstm_99_forward_input.1.0.npy`、`VF_lstm_99_forward_input.1.1.npy` 类似的数据是否正常？
+
+    带 1.0/1.1/1.2 后缀的 npy 是正常现象，例如，当输入数据为 [[tensor1, tensor2, tensor3]] 会生成这样的后缀。
+
+4. 进行 compare 报错：The current file contains stack information, please turn on the stack_mode。
+
+    在比对脚本中，设置 `stack_mode=True`，例如：
+
+    ```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)
+    ```
+
+5. dump 指定反向 API 的 kernel 级别的数据报错：NameError：name 'torch_npu' is not defined。
+
+   答：如果是 npu 环境，请安装 torch_npu；如果是 gpu 环境，暂不支持 dump 指定 API 的 kernel 级别的数据。
+
+6. 配置 dump_path 后，使用工具报错：[ERROR] The file path /home/xxx/dump contains special characters。
+
+   答：请检查你设置的 dump 绝对路径是否包含特殊字符，确保路径名只包含大小写字母、数字、下划线、斜杠、点和短横线；注意，如果执行脚本的路径为 /home/abc++/，设置的 dump_path="./dump"，工具实际校验的路径为绝对路径 /home/abc++/dump，++ 为特殊字符，会引发本条报错。
+
+7. 无法 dump matmul 权重的反向梯度数据。
+
+   答：matmul 期望的输入是二维，当输入不是二维时，会将输入通过 view 操作展成二维，再进行 matmul 运算，因此在反向求导时，backward_hook 能拿到的是 UnsafeViewBackward 这步操作里面数据的梯度信息，取不到 MmBackward 这步操作里面数据的梯度信息，即权重的反向梯度数据。典型的例子有，当 linear 的输入不是二维，且无 bias 时，会调用 output = input.matmul(weight.t())，因此拿不到 linear 层的 weight 的反向梯度数据。
+
+8. dump.json 文件中的某些 api 的 dtype 类型为 float16，但是读取此 api 的 npy 文件显示的 dtype 类型为 float32。
+
+    答：msprobe 工具在 dump 数据时需要将原始数据从 npu to cpu 上再转换为 numpy 类型，npu to cpu 的逻辑和 gpu to cpu 是保持一致的，都存在 dtype 可能从 float16 变为 float32 类型的情况，如果出现 dtype 不一致的问题，最终采集数据的 dtype 以 pkl 文件为准。
+
+9. 使用 dataloader 后 raise 异常 Exception("msprobe: exit after iteration {}". format(max(self.config.step)))。
+
+   答：正常现象，dataloader 通过 raise 结束程序，堆栈信息可忽略。
+
+10. 添加 msprobe 工具后截取操作报错：`IndexError: too many indices for tensor of dimension x` 或 `TypeError: len() of a 0-d tensor`。
+
+    答：注释工具目录 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中 `Tensor: ` 下的 `- __getitem__`，工具会跳过采集该 API。如果是需要采集关键位置 API 也可以考虑根据报错堆栈信息注释引发报错的类型检查。
+
+11. 添加 msprobe 工具后 F.gelu 触发 ValueError 报错：`activation_func must be F.gelu`等。
+
+    答：注释工具目录 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中 `functional: ` 下的 `-gelu`，工具会跳过采集该 API。如果需要采集关键位置 api 也可以考虑根据报错堆栈信息注释引发报错的类型检查。
+
+12. 添加 msprobe 工具后触发与 AsStrided 算子相关、或者编译相关的报错，如：`Failed to compile Op [AsStrided]`。
+
+    答：注释工具目录 `mstt/debug/accuracy_tools/msprobe/pytorch/hook_module/support_wrap_ops.yaml` 文件中 `Tensor: `下的 `-t` 和 `- transpose`。