# **PyTorch场景下的溢出检测**

msprobe 工具在 PyTorch 场景下提供溢出数据采集功能和溢出数据解析功能，详细介绍见下方章节。

## 1、溢出数据采集

溢出数据采集能 dump 所有溢出的 API 或者 Module 的信息，包括前反向输入输出的统计值和实际运行数据信息。

### 1.1 工具安装

工具安装详见《[msprobe 使用手册](../README.md)》的“安装”章节

### 1.2 接口介绍

溢出检测功能提供的接口与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**1 接口介绍**"章节。
其中 PrecisionDebugger 中的 task 或是 config.json 中的 task 需要指定为 **overflow_check**，详见[配置文件介绍](./02.config_introduction.md)中的
"**1.1 通用配置介绍**"和"**1.5 task 配置为 overflow_check**"章节。

### 1.3 示例代码

溢出检测功能使用方式与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**2 示例代码**"章节。

### 1.4 结果文件介绍

溢出检测结果文件目录结构与含义与数据采集任务一致，详见[ PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)中的"**3 dump 结果文件介绍**"章节。

### 1.5 其他说明

溢出数据采集功能在昇腾 NPU 上支持饱和模式和 INF/NAN 模式。INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品，默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品，默认为 INF/NAN 模式，且不建议使用饱和模式。

INF/NAN 模式的使能方式如下：

```Shell
# 使能 CANN 侧 INF/NAN 模式
export INF_NAN_MODE_ENABLE=1
```

## 2、溢出数据解析

注：溢出数据解析目前只支持分析前向 API 输入未溢出，但输出溢出的场景。

在第一步中采集到溢出数据后，可以使用溢出解析功能快速判断输入未溢出而输出溢出的 API 是正常溢出还是非正常溢出，从而帮您快速分析是否由 API 执行异常导致的溢出问题。
同一个 API 用相同的输入数据在 CPU 设备和昇腾 NPU 设备上执行，若 CPU 和 NPU 均出现溢出，则认为该溢出是**正常溢出**；若 NPU 有溢出, 而 CPU 没有溢出则认为该溢出是**非正常溢出**。

工具支持的 PyTorch 版本：1.11/2.0/2.1/2.2。

操作步骤如下：

1. 安装工具。

   详见《[msprobe 使用手册](../README.md)》的“安装”章节。

2. 执行溢出 API 解析操作。

   ```bash
   msprobe -f pytorch run_overflow_check -api_info ./dump.json
   ```
   
| 参数名称                   | 说明                                 | 是否必选 |
| -------------------------- |------------------------------------| -------- |
| -api_info或--api_info_file | 指定采集下来的 API 信息文件 dump.json。        | 是       |
| -j或--jit_compile          | 开启 jit 编译。                         | 否       |
| -d或--device               | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为0。 | 否       |

3. 结果说明。

   如果 API 是**正常溢出**，会打印以下信息：

    ```bash
   The {api_name} overflow is a normal overflow.
   ```

    **非正常溢出**则会打印以下信息：

    ```bash
   The {api_name} overflow is an abnormal overflow.
   ```

   其中 {api_name} 是对应溢出的 API 名称。
