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

msprobe/docs/12.overflow_check_PyTorch.md

@@ -0,0 +1,79 @@
+# **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 训练系列产品（如 910A），默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2 训练系列产品（如 910B），默认为 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 名称。

msprobe/docs/13.overflow_check_MindSpore.md

@@ -0,0 +1,31 @@
+# MindSpore 场景的溢出检测
+
+msprobe 工具提供静态图O2编译等级下的过程溢出检测与动态图场景下的结果溢出检测。其中前者检测对象为 kernel 级别，对应 config.json 配置中的 "L2" level，后者检测对象为 API 级别(支持的API类型为ops、Tensor、mint和mint.nn.functional，不支持Primitive和Jit类API)，对应 config.json 配置中的 "L1" level。
+
+需要注意，动态图场景下的溢出检测功能仅支持 INF/NAN 模式<sup>a</sup>。INF/NAN 模式的使能方式如下：
+
+```Shell
+# 使能 CANN 侧 INF/NAN 模式
+export INF_NAN_MODE_ENABLE=1
+# 使能 MindSpore 框架侧 INF/NAN 模式
+export MS_ASCEND_CHECK_OVERFLOW_MODE="INFNAN_MODE"
+```
+
+**a**：INF/NAN 模式遵循 IEEE 754 标准，根据定义输出 INF/NAN 的计算结果。与之对应的饱和模式在计算出现溢出时，饱和为浮点数极值（+-MAX）。对于 CANN 侧配置，Atlas 训练系列产品（如 910A），默认为饱和模式，且不建议使用 INF/NAN 模式；Atlas A2训练系列产品（如 910B），默认为 INF/NAN 模式，且不建议使用饱和模式。对于 MindSpore 框架侧配置，仅支持对 Atlas A2 训练系列产品进行设置，默认为 INF/NAN 模式。CANN 侧 与 MindSpore 框架侧配置须一致。
+
+溢出检测任务的配置示例见[MindSpore 静态图场景下 task 配置为 overflow_check](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#23-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-overflow_check)、[MindSpore 动态图场景下 task 配置为 overflow_check](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/docs/03.config_examples.md#33-task-%E9%85%8D%E7%BD%AE%E4%B8%BA-overflow_check)。
+
+
+## 1 接口介绍
+
+溢出检测功能提供的接口与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**1 接口介绍**"章节。
+
+需要注意，目前暂不支持动态图 "L1" level 下 primitive op 的溢出检测。
+
+## 2 示例代码
+
+溢出检测功能使用方式与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**2 示例代码**"章节。
+
+## 3 溢出检测结果文件介绍
+
+溢出检测结果文件目录结构与含义与数据采集任务一致，详见[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)中的"**3 dump 结果文件介绍**"章节。