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

msprobe/docs/11.accuracy_compare_MindSpore.md

@@ -0,0 +1,202 @@
+# MindSpore 场景的精度比对
+
+## 1 简介
+
+msprobe精度比对工具主要用于如下场景：
+
+- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到API dump数据后，对这两个API dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在两个不同版本的MindSpore静态图环境下，输入相同的训练数据，在分别得到kernel dump数据后，对这两个kernel dump数据进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在两个不同版本的MindSpore动态图环境下，输入相同的训练数据，在分别得到cell dump数据后，对这两个cell模块进行全量自动比对，从而快速定位不同版本之间的精度问题。
+- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得API dump数据，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+- 通过对同一个网络模型，在整网环境下分别在MindSpore动态图和PyTorch环境下获得cell dump数据，由用户指定可以比对的cell list，以PyTorch数据作为标杆，进行自动比对，从而实现跨框架的精度对比。
+
+执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。
+
+## 2 命令行方式
+
+精度比对工具目前使用方式为命令行形式。
+
+### 2.1 命令格式说明
+
+```shell
+msprobe -f mindspore compare -i ./compare.json -o ./output -s
+```
+
+**完整参数说明**
+
+| 参数名              | 说明                                                         | 是否必选 |
+| ------------------- | ------------------------------------------------------------ | -------- |
+| -i或--input_path    | 指定比对文件。比对文件内容及示例请参见[比对文件](#31-比对文件)或[比对文件（kernel）](#32-比对文件（kernel）)（比对文件（kernel）仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
+| -o或--output_path   | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：<br>        `compare_result_{timestamp}.xlsx`<br/>        `compare_result_{rank_id}_{step_id}_{timestamp}.xlsx`（仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持）。 | 是       |
+| -s或--stack_mode    | 配置stack_mode的开关。仅当[比对文件](#31-比对文件)配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| -c或--compare_only  | 仅比对开关。该参数默认未配置，表示关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否       |
+| -f或--fuzzy_match   | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否       |
+| -am或--api_mapping  | 跨框架比对。配置该参数时表示开启跨框架API比对功能。仅[跨框架的API比对](#25-跨框架的API比对)场景支持。 | 否       |
+| -cm或--cell_mapping | 跨框架比对。配置该参数时表示开启跨框架cell模块比对功能，可以指定自定义映射文件*.yaml，不指定映射文件时按照msprobe定义的默认映射关系进行比对。自定义映射文件的格式请参见[自定义映射文件](#33-自定义映射文件)。仅[跨框架的cell模块比对](#26-跨框架的cell模块比对)场景支持。 | 否       |
+
+### 2.2 不同版本下的全量API比对
+
+1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的API dump数据。
+
+2. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+3. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s
+   ```
+
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.3 不同版本下的全量kernel比对
+
+1. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore静态图精度数据的采集，得到不同框架版本的kernel dump数据。
+
+2. 创建比对文件，文件内容及示例请参见[比对文件（kernel）](#32-比对文件（kernel）)。
+
+3. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output
+   ```
+
+4. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.4 不同版本下的cell模块比对
+
+1. 配置[config.json](../config.json)文件level配置为L0、task配置为tensor或statistics并指定需要dump的cell模块名。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》完成不同环境下MindSpore动态图精度数据的采集，得到不同框架版本的cell模块dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.5 跨框架的API比对
+
+1. 配置[config.json](../config.json)文件level配置为L1、task配置为tensor或statistics。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下API精度数据的采集，得到两个框架的API dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -am
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+### 2.6 跨框架的cell模块比对
+
+1. 配置[config.json](../config.json)文件level配置为L0、task配置为tensor或statistics并指定需要dump的cell模块名。
+
+2. 参见《[MindSpore 场景的精度数据采集](./06.data_dump_MindSpore.md)》和《[PyTorch 场景的精度数据采集](./05.data_dump_PyTorch.md)》完成不同环境下cell模块精度数据的采集，得到两个框架的cell模块dump数据。
+
+3. 创建比对文件，文件内容及示例请参见[比对文件](#31-比对文件)。
+
+4. 执行如下示例命令进行比对：
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm
+   ```
+
+   或
+
+   ```shell
+   msprobe -f mindspore compare -i ./compare.json -o ./output -s -cm cell_mapping.yaml
+   ```
+
+5. 查看比对结果，请详见PyTorch目录下的《[PyTorch 场景的精度比对-精度比对结果分析](./10.accuracy_compare_PyTorch.md#3-精度比对结果分析)]》章节。
+
+## 3 附录
+
+### 3.1 比对文件
+
+以在当前目录创建./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
+}
+  ```
+
+
+**参数说明**
+
+| 参数名               | 说明                                                         | 是否必选 |
+| -------------------- | ------------------------------------------------------------ | -------- |
+| npu_path             | 配置NPU环境下的dump.json文件（单卡场景）。跨框架场景指定为MindSpore的json文件。数据类型：str。 | 是       |
+| bench_path           | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）。 跨框架场景指定为PyTorch的json文件。数据类型：str。 | 是       |
+| stack_path           | 配置NPU dump目录下的stack.json文件。数据类型：str。          | 是       |
+| is_print_compare_log | 配置是否开启日志打屏。可取值true或false，默认为true。数据类型：bool | 否       |
+
+### 3.2 比对文件（kernel）
+
+仅[不同版本下的全量kernel比对](#23-不同版本下的全量kernel比对)场景支持。
+
+以在当前目录创建./compare.json为例，示例如下：
+
+- 单卡场景：
+
+  ```json
+  {
+  "npu_path": "./npu_dump",
+  "bench_path": "./bench_dump",
+  "rank_id": [1],
+  "step_id": []
+  }
+  ```
+
+- 多卡场景：
+
+  ```json
+  {
+  "npu_path": "./npu_dump",
+  "bench_path": "./bench_dump",
+  "rank_id": [],
+  "step_id": []
+  }
+  ```
+
+
+**参数说明**
+
+| 参数名     | 说明                                                         | 是否必选 |
+| ---------- | ------------------------------------------------------------ | -------- |
+| npu_path   | 配置NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
+| bench_path | 配置CPU、GPU或NPU环境下的dump.json文件目录（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是       |
+| rank_id    | 配置比对的Rank ID。npu_path和bench_path目录下的dump文件需要存在对应Rank的数据。默认为空，表示比对所有Rank。可配置一个或多个Rank，多个Rank ID用逗号隔开，例如："rank_id": [1,2,3]。数据类型：list[int]。 | 否       |
+| step_id    | 配置比对的Step ID。npu_path和bench_path目录下的dump文件需要存在对应Step的数据。默认为空，表示比对所有Sank。可配置一个或多个Sank，多个Sank ID用逗号隔开，例如："step_id": [1,2,3]。数据类型：list[int]。 | 否       |
+
+### 3.3 自定义映射文件
+
+文件名格式：\*.yaml，*为文件名，可自定义。
+
+文件内容格式：
+
+```yaml
+{cell_name}.{class_name}: {cell_name}.{class_name}
+```
+
+左侧为MindSpore框架cell模块的{cell_name}.{class_name}，右侧为PyTorch框架cell模块的{cell_name}.{class_name}。
+
+{cell_name}.{class_name}从dump cell模块级.npy文件名获取，命名格式为：`{Cell}_{cell_name}_{class_name}_{前向反向}.{index}.{input/output}.{参数序号}`
+
+文件内容示例：
+
+```yaml
+fc2.Dense: fc2.Linear
+conv1.Conv2d: conv3.Conv2d
+```

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 级别，对应 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 结果文件介绍**"章节。