diff --git a/README.md b/README.md index 601deec66865dd8734eca30f74b67372c721150d..6a9b221a187e964be1da1595b02c6dd52488a3b1 100644 --- a/README.md +++ b/README.md @@ -1,107 +1,80 @@ -# 变更通知 +# 🚨 重要通知 +**1. Ascend Training Tools 更名为 MindStudio Training Tools (mstt)。** +**2. 本代码仓 URL 变更为 [https://gitee.com/ascend/mstt](https://gitee.com/ascend/mstt)，原 URL 仍然可用（2024.07.04 ）。** -原Ascend Training Tools工具更名为MindStudio Training Tools，MindStudio训练工具链。变更计划如下： +**3. 不再维护：[api_accuracy_checker](./debug/accuracy_tools/api_accuracy_checker/) （2024.09.30下线）和[ ptdbg_ascend](./debug/accuracy_tools/ptdbg_ascend/) +（2024.09.30下线）** -1. 2024.06.25本代码仓名称变更为mstt。 -2. 2024.07.04 URL变更为[https://gitee.com/ascend/mstt](https://gitee.com/ascend/mstt)，原始URL仍然可用，但建议使用新URL。 +**相关目录 mstt/debug/accuracy_tools/api_accuracy_checker 和 mstt/debug/accuracy_tools/ptdbg_ascend 将于 2024.09.30 删除。新版本的预检和 ptdbg 已经合到 mstt/debug/accuracy_tools/msprobe 目录下。** -# MindStudio Training Tools +--- -MindStudio Training Tools，MindStudio训练工具链。针对训练&大模型场景，提供端到端命令行&可视化调试调优工具，帮助用户快速提高模型开发效率。 +# 🧰 MindStudio Training Tools -## 模型训练迁移全流程 -![输入图片说明](debug/resources/model_training_migration_process.png) +![Build Status](https://img.shields.io/badge/build-passing-brightgreen) +![Commit Activity](https://img.shields.io/badge/commit%20activity-high-red) +![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue) -## 使用说明 - -### [分析迁移工具](https://gitee.com/ascend/mstt/wikis/工具介绍/分析迁移工具/分析迁移工具介绍) +## [分析迁移工具](https://gitee.com/ascend/mstt/wikis/工具介绍/分析迁移工具/分析迁移工具介绍) 1. [脚本分析工具](https://gitee.com/ascend/mstt/wikis/%E5%B7%A5%E5%85%B7%E4%BB%8B%E7%BB%8D/%E5%88%86%E6%9E%90%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7/%E5%88%86%E6%9E%90%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%8C%87%E5%AF%BC) - 脚本分析工具提供分析脚本，帮助用户在执行迁移操作前，分析基于GPU平台的PyTorch训练脚本中算子、三方库套件、亲和API分析以及动态shape的支持情况。 + 脚本分析工具可以帮助用户在执行迁移操作前，分析基于 GPU 平台的 PyTorch 训练脚本中算子、三方库套件、API 亲和性以及动态 shape 的支持情况。 2. [（推荐）自动迁移工具](https://gitee.com/ascend/mstt/wikis/%E5%B7%A5%E5%85%B7%E4%BB%8B%E7%BB%8D/%E5%88%86%E6%9E%90%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7/%E8%87%AA%E5%8A%A8%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%8C%87%E5%AF%BC) - 自动迁移只需在训练脚本中导入库代码即可完成模型脚本迁移，使用方式较简单，且修改内容最少。 + 自动迁移工具只需在训练脚本中导入库代码即可完成模型脚本的迁移，使用方式简单，且修改内容少。 3. [脚本迁移工具](https://gitee.com/ascend/mstt/wikis/%E5%B7%A5%E5%85%B7%E4%BB%8B%E7%BB%8D/%E5%88%86%E6%9E%90%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7/%E8%84%9A%E6%9C%AC%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%8C%87%E5%AF%BC) - 脚本迁移工具提供后端命令行用于将GPU上训练的PyTorch脚本迁移至NPU上，得到新的训练脚本用于训练。 + 脚本迁移工具通过后端命令行，将 GPU 上训练的 PyTorch 脚本迁移至 NPU 上，得到新的训练脚本用于训练。 4. [训推一体权重转换工具](https://gitee.com/Ascend/mstt/wikis/%E5%B7%A5%E5%85%B7%E4%BB%8B%E7%BB%8D/%E5%88%86%E6%9E%90%E8%BF%81%E7%A7%BB%E5%B7%A5%E5%85%B7/%E8%AE%AD%E6%8E%A8%E4%B8%80%E4%BD%93%E6%9D%83%E9%87%8D%E8%BD%AC%E6%8D%A2%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E6%8C%87%E5%AF%BC) - 训推一体权重转换工具，支持在GPU和NPU上训练好的模型转成加速推理支持的格式。 - -### [精度工具](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools) - -1. [MindStudio Probe（ MindStudio精度调试工具）](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe)。 - - MindStudio Training Tools工具链下精度调试部分的工具包，主要包括精度预检和精度比对等子工具。 - -2. [api_accuracy_checker（Ascend模型精度预检工具）](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/api_accuracy_checker) - - 2024.09.30下线 - - 在昇腾NPU上扫描用户训练模型中所有API，进行API复现，给出精度情况的诊断和分析。 + 训推一体权重转换工具，支持在 GPU 和 NPU 上训练好的模型转成加速推理支持的格式。 -3. [ptdbg_ascend（PyTorch精度工具）](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/ptdbg_ascend) +## [精度工具](./debug/accuracy_tools/) - 2024.09.30下线 +[MindStudio Probe（msprobe，MindStudio 精度调试工具）](./debug/accuracy_tools/msprobe)。 - 进行PyTorch整网API粒度的数据dump、精度比对和溢出检测，从而定位PyTorch训练场景下的精度问题。 +## [性能工具](./profiler) -### [性能工具](https://gitee.com/ascend/mstt/tree/master/profiler) +1. [compare_tools（性能比对工具）](./profiler/compare_tools) -1. [compare_tools（性能比对工具）](https://gitee.com/ascend/mstt/tree/master/profiler/compare_tools) + 提供 NPU 与 GPU 性能拆解功能以及算子、通信、内存性能的比对功能。 - 提供NPU与GPU性能拆解功能以及算子、通信、内存性能的比对功能。 +2. [cluster_analyse（集群分析工具）](./profiler/cluster_analyse) -2. [cluster_analyse（集群分析工具）](https://gitee.com/ascend/mstt/tree/master/profiler/cluster_analyse) + 提供多机多卡的集群分析能力（基于通信域的通信分析和迭代耗时分析）, 当前需要配合 MindStudio Insight 的集群分析功能使用。 - 提供多机多卡的集群分析能力（基于通信域的通信分析和迭代耗时分析）, 当前需要配合MindStudio Insight的集群分析功能使用。 +3. [advisor](./profiler/advisor) -3. [advisor](https://gitee.com/ascend/mstt/blob/master/profiler/advisor) + 将 Ascend PyTorch Profiler 或者 msprof 采集的 PyThon 场景性能数据进行分析，并输出性能调优建议。 - 将Ascend PyTorch Profiler或者msprof采集的PyThon场景性能数据进行分析，并输出性能调优建议。 +## [Tensorboard](./plugins/tensorboard-plugins/tb_plugin) +Tensorboard 支持 NPU 性能数据可视化插件 PyTorch Profiler TensorBoard NPU Plugin。 -### [Tensorboard](https://gitee.com/ascend/mstt/tree/master/plugins/tensorboard-plugins/tb_plugin) - -Tensorboard支持NPU性能数据可视化插件PyTorch Profiler TensorBoard NPU Plugin。 - -支持将Ascend平台采集、解析的Pytorch Profiling数据可视化呈现，也兼容GPU数据采集、解析可视化。 +支持将 Ascend 平台采集、解析的 PyTorch Profiling 数据可视化呈现，也兼容 GPU 数据采集、解析可视化。 ## 分支维护策略 -MindStudio Training Tools工具版本分支的维护阶段如下： - -| **状态** | **时间** | **说明** | -| ------------------- | -------- | ------------------------------------------------ | -| 计划 | 1~3 个月 | 计划特性 | -| 开发 | 3个月 | 开发特性 | -| 维护 | 6~12个月 | 合入所有已解决的问题并发布版本 | -| 无维护 | 0~3 个月 | 合入所有已解决的问题，无专职维护人员，无版本发布 | -| 生命周期终止（EOL） | N/A | 分支不再接受任何修改 | - -## 现有分支的维护状态 - -MindStudio Training Tools分支版本号命名规则如下： - -mstt仓每年发布4个版本，每个版本都将对应一个分支；以v6.0为例，其将对应v6.0.RC1、v6.0.RC2、v6.0.RC3以及v6.0.0四个版本，在仓库中将存在与之对应的分支。 - -| **分支** | **状态** | **发布日期** | **后续状态** | **EOL日期** | -| ------------- | -------- | ------------ | ------------------------ | ----------- | -| **v6.0.0** | 维护 | 2023/12/12 | 预计2024/12/12起无维护 | | +1. MindStudio Training Tools 工具版本分支的维护阶段如下： -## 参与贡献 + | **状态** | **时间** | **说明** | + | ------------------- | -------- | ------------------------------------------------ | + | 计划 | 1—3 个月 | 计划特性 | + | 开发 | 3个月 | 开发特性 | + | 维护 | 6—12个月 | 合入所有已解决的问题并发布版本 | + | 无维护 | 0—3 个月 | 合入所有已解决的问题，无专职维护人员，无版本发布 | + | 生命周期终止（EOL） | N/A | 分支不再接受任何修改 | -1. Fork 本仓库 -2. 新建 xxx 分支 -3. 提交代码 -4. 新建 Pull Request +2. MindStudio Training Tools 分支版本号命名规则如下： -## 版本过渡提示 + mstt 仓每年发布 4 个版本，每个版本都将对应一个分支；以 v6.0 为例，其将对应 v6.0.RC1、v6.0.RC2、v6.0.RC3 以及 v6.0.0 四个版本，在仓库中将存在与之对应的分支。 -当前版本预检和ptdbg维护到2024/09/30，准备于2024/09/30下线，相关目录mstt/debug/accuracy_tools/api_accuracy_checker和mstt/debug/accuracy_tools/ptdbg_ascend将于2024/09/30删除。新版本的预检和ptdbg已经合到mstt/debug/accuracy_tools/atat目录下。 + | **分支** | **状态** | **发布日期** | **后续状态** | **EOL日期** | + | ------------- | -------- | ------------ | ------------------------ | ----------- | + | **v6.0.0** | 维护 | 2023.12.12 | 预计 2024.12.12 起无维护 | | diff --git a/debug/accuracy_tools/msprobe/README.md b/debug/accuracy_tools/msprobe/README.md index f5e457efa7811b2f034c8b27bdb8df947c831856..83340fc6ab293f31e5c1cb279169d2cc081c9efa 100644 --- a/debug/accuracy_tools/msprobe/README.md +++ b/debug/accuracy_tools/msprobe/README.md @@ -1,238 +1,102 @@ -# MindStudio精度调试工具 +# 📖 msprobe 使用手册 -MindStudio精度调试工具（MindStudio Probe），简称msprobe，是MindStudio Training Tools工具链下精度调试部分的工具包。主要包括精度预检和精度比对等子工具，当前适配场景包括PyTorch和MindSpore。 +![version](https://img.shields.io/badge/version-1.0.3-blueviolet) +![python](https://img.shields.io/badge/python-3.8|3.9|3.10-blue) +![platform](https://img.shields.io/badge/platform-Linux-yellow) -## 工具安装 +[**msprobe**](./) 是 MindStudio Training Tools 工具链下精度调试部分的工具包。主要包括精度预检、溢出检测和精度比对等功能，目前适配 [PyTorch](https://pytorch.org/) 和 [MindSpore](https://www.mindspore.cn/) 框架。这些子工具侧重不同的训练场景，可以定位模型训练中的精度问题。 -精度工具合一软件包名称：`mindstudio_probe-{version}-py3-none-any.whl` +为方便使用，本工具提供了一个统一、简易的程序接口，**PrecisionDebugger**，通过以下示例模板和 **config.json** 可轻松使用各种功能。 -### pip安装 - ```shell - pip install mindstudio-probe - ``` -使用`pip install mindstudio-probe==版本号`可安装指定版本的包。 +```python +from msprobe.pytorch import PrecisionDebugger +# from msprobe.mindspore import PrecisionDebugger -pip命令会自动安装最新的包及其配套依赖。 - -提示如下信息则表示安装成功。 - -```bash -Successfully installed mindstudio_probe-{version} +debugger = PrecisionDebugger(config_path='./config.json') +... +debugger.start() # 一般在训练循环开头启动工具 +... # 循环体 +debugger.stop() # 一般在训练循环末尾结束工具 +debugger.step() # 在训练循环的最后需要重置工具，非循环场景不需要 ``` -### 下载whl包安装 -1. 使用pip命令安装依赖： - - 1. 根据实际环境安装torch或mindspore - - 2. 安装numpy、openpyxl、pandas、PyYAML、rich、tqdm、einops、matplotlib、pyOpenSSL、twisted - - - 若环境中已安装部分依赖，不需要重复安装。 - -2. whl包获取。 - - 请通过下表链接下载工具whl包。 - - | 版本 | 发布日期 | 支持PyTorch版本 | 支持MindSpore版本 | 下载链接 | 校验码 | - | ----- | ---------- | ---------------- | ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | - | 1.0.3 | 2024-08-23 | 1.11/2.0/2.1/2.2 | 2.3.1 | [mindstudio_probe-1.0.3-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.3-py3-none-any.whl) | 7060cc141a5b98ef770cd9220995d299393f32a61938261e632c7e8b5160bef2 | - | 1.0.2 | 2024-08-09 | 1.11/2.0/2.1/2.2 | 2.3.1 | [mindstudio_probe-1.0.2-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.2-py3-none-any.whl) | e4a980e5d98c426ce5ce9842520d9bc031d3b3de621c74b3d59414cc6e238e0e | - | 1.0.1 | 2024-07-25 | 2.0/2.1/2.2 | 2.3.1 | [mindstudio_probe-1.0.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.1-py3-none-any.whl) | b699e224e4d4e3bcf9412c54fa858a1ee370f0d7a2bc69cb3f1273ac14a6dc82 | - | 1.0 | 2024-07-09 | 2.0/2.1/2.2 | 2.3.0 | [ascend_training_accuracy_tools-1.0-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/1.0/ascend_training_accuracy_tools-1.0-py3-none-any.whl) | 5016dfe886c5d340ec6f60a959673355855f313c91f100680da814efb49f8e81 | - | 0.0.3 | 2024-06-11 | 2.0/2.1/2.2 | 2.3.0 | [ascend_training_accuracy_tools-0.0.3-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/0.0/ascend_training_accuracy_tools-0.0.3-py3-none-any.whl) | f46d9714704859e2d67861a65bbb3c76b0a250cf6e238b978b5b959ab1fe125a | - | 0.0.2 | 2024-05-23 | 2.0/2.1/2.2 | 2.3.0 | [ascend_training_accuracy_tools-0.0.2-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/0.0/ascend_training_accuracy_tools-0.0.2-py3-none-any.whl) | 2e35809bde559e9c4d2f16a02ccde779ed9e436bb65fded0b7ebaf6ac2c88d93 | - | 0.0.1 | 2024-03-15 | 2.0/2.1 | - | [ascend_training_accuracy_tools-0.0.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/0.0/ascend_training_accuracy_tools-0.0.1-py3-none-any.whl) | 5801510d4e827e4859bc9a5aca021e4d30c2ea42d60a4c8ad0c2baab1b7782c9 | - -3. whl包校验。 - - 1. 根据以上下载链接下载whl包到Linux安装环境。 +除了在训练脚本中调用接口函数，还可以通过命令行使用 **msprobe** 的其他功能，具体的使用规则和 **config.json** 的配置要求详见以下章节。 - 2. 进入whl包所在目录，执行如下命令。 +## ⚙️ [安装](./docs/01.installation.md) - ```bash - sha256sum {name}.whl - ``` +## 🛠️ config.json [介绍](./docs/02.config_introduction.md) 和 [示例](./docs/03.config_examples.md) - {name}为whl包名称。 +## 🧰 主要功能 - 若回显呈现对应版本whl包一致的**校验码**，则表示下载了正确的ptdbg_ascend精度工具whl安装包。示例如下： +### 1 数据采集 - ```bash - sha256sum ascend_training_accuracy_tools-0.0.1-py3-none-any.whl - 5801510d4e827e4859bc9a5aca021e4d30c2ea42d60a4c8ad0c2baab1b7782c9 *ascend_training_accuracy_tools-0.0.1-py3-none-any.whl - ``` +msprobe 通过在训练脚本中添加 PrecisionDebugger 接口的方式对 API 执行精度数据 dump 操作，对应 config.json 中的 task 为 statistics 或 tensor。 -4. 执行如下命令进行安装。 +[PyTorch 场景下的数据采集](./docs/05.data_dump_PyTorch.md) - ```bash - pip3 install ./mindstudio_probe-{version}-py3-none-any.whl - ``` - - 若为覆盖安装，请在命令行末尾增加“--force-reinstall”参数强制安装，例如： - - ```bash - pip3 install ./mindstudio_probe-{version}-py3-none-any.whl --force-reinstall - ``` - - 提示如下信息则表示安装成功。 - - ```bash - Successfully installed mindstudio_probe-{version} - ``` - -### 从源码安装 -1. 克隆或者下载项目源代码 - - ```shell - git clone https://gitee.com/ascend/mstt.git - cd debug/accuracy_tools - ``` - -2. 安装setuptools和wheel - - ```shell - pip install setuptools wheel - ``` - -3. 安装msprobe - - ```shell - python setup.py bdist_wheel - cd dist - pip install mindstudio_probe*.whl - ``` - 提示出现如下信息则表示源码安装成功。 - ```shell - Successfully installed ... mindstudio_probe-{version} ... - ``` - -### 查看msprobe工具信息 - -执行如下命令查看msprobe工具信息。 - -```bash -pip show mindstudio-probe -``` - -输出结果如下示例： - -```bash -Name: mindstudio-probe -Version: 1.0 -Summary: This is a pytorch precision comparison tools -Home-page: -Author: -Author-email: -License: -Location: /home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages -Requires: numpy, openpyxl, pandas, pyyaml, rich, tqdm, wheel -Required-by: -``` +[MindSpore 场景下的数据采集](./docs/06.data_dump_MindSpore.md) -关键字段含义： +### 2 精度预检 -- Name：工具名称。 -- Version：工具版本号。 -- Summary：工具概述。 -- Location：工具安装路径。 -- Requires：工具依赖。 +精度预检旨在昇腾 NPU 上扫描训练模型中的所有 API 进行 API 复现，给出精度情况的诊断和分析。对应 config.json 中的 task 为 run_ut。 -## 工具使用 +PyTorch 场景的[离线预检](./docs/07.accuracy_checker_PyTorch.md)和[在线预检](./docs/08.accuracy_checker_online_PyTorch.md) -安装msprobe工具后，可以按照如下思路选择合适的子工具进行精度调试： +MindSpore 动态图场景的[离线预检](./docs/09.accuracy_checker_MindSpore.md) -1. 判断框架场景。 +### 3 精度比对 - 当前支持PyTorch和MindSpore场景。 +该功能进行 PyTorch 整网 API 粒度的数据 dump、精度比对，进而定位训练场景下的精度问题。 -2. 执行数据采集。 +[PyTorch 场景的精度比对](./docs/11.accuracy_compare_PyTorch.md) - 工具通过在训练脚本中添加PrecisionDebugger接口的方式对API执行精度数据dump操作。 +[MindSpore 场景的精度比对](./docs/12.accuracy_compare_MindSpore.md) - PyTorch场景：详见[PyTorch_精度数据采集](./pytorch/doc/dump.md)。 +### 4 溢出检测与解析 - MindSpore场景：详见[MindSpore_精度数据采集](./mindspore/doc/dump.md)。 +溢出检测与解析是在执行精度数据 dump 时，判断是否存在输入正常但输出存在溢出的 API，从而判断是否为正常溢出。对应 config.json 中的 overflow_check。 -3. 执行精度预检。 +[PyTorch 场景的溢出检测与解析](./docs/13.overflow_check_PyTorch.md)（更新中） - 在昇腾NPU上扫描用户训练模型中所有API，进行API复现，给出精度情况的诊断和分析。 +[MindSpore 场景的溢出检测与解析](./docs/14.overflow_check_MindSpore.md)（更新中） - PyTorch场景：详见[PyTorch_精度预检工具](./pytorch/doc/api_accuracy_checker.md)。 +### 5 数据解析 - MindSpore场景：暂不支持。 +该功能用于比对前后两次 NPU ACL 层级 dump 数据的一致性。 -4. 执行精度比对。 +[PyTorch 场景的数据解析](./docs/15.data_parse_PyTorch.md) - 进行PyTorch整网API粒度的数据dump、精度比对和溢出检测，从而定位训练场景下的精度问题。 +### 6 无标杆比对 - PyTorch场景：详见[PyTorch_精度比对工具](./pytorch/doc/ptdbg_ascend_compare.md)。 +[PyTorch 场景的无标杆比对](./docs/17.free_benchmarking_PyTorch.md)（更新中） - MindSpore场景：详见[MindSpore_精度比对工具](./mindspore/doc/compare.md)。 +[MindSpore 场景的无标杆比对](./docs/18.overflow_check_MindSpore.md)（更新中） -5. 执行溢出解析。 +### 7 梯度状态监测 - 溢出解析是在执行精度数据dump时，配置了溢出检测dump，那么对于输入正常但输出存在溢出的API，可以判断是否为正常溢出。 +本功能用于采集梯度数据并进行梯度相似度比对，可以精准定位出现问题的 step。 - PyTorch场景：详见[PyTorch_溢出解析工具](./pytorch/doc/run_overflow_check.md)。 +[兼容 PyTorch 和 MindSpore 框架的梯度监测](./docs/19.grad_probe.md) - MindSpore场景：暂不支持。 +## 🌟 新版本特性 -6. 执行数据解析。 +【精度预检】 +- 落盘数据小。 +- 支持随机生成模式和真实数据模式。 +- 单 API 测试，排除整网中的累计误差问题。 - 用于比对前后两次NPU ACL层级dump数据的一致性。 +【梯度检测】 +- 使用便捷，无需在训练流程里插入代码。 +- 可以精准定位问题出现的 step。 - PyTorch场景：详见[PyTorch_数据解析工具](./pytorch/doc/parse_tool.md)。 +## 📑 补充材料 - MindSpore场景：暂不支持。 +[msprobe 精度工具标准性能基线报告](./docs/S01.report_msprobe_dump_standard_performance_baseline.md) -6. 执行梯度采集和比对。 - - 用于采集梯度数据并进行梯度相似度比对。可以精准定位问题出现的step。 - - 详见[梯度状态监测工具](./doc/grad_probe/grad_probe.md)。 - - - -上述流程中的工具均为msprobe工具的子工具，使用相同的命令行，格式如下： - -精度预检工具 - -```bash -msprobe -f run_ut [-h] -``` - -```bash -msprobe -f multi_run_ut [-h] -``` - -```bash -msprobe -f api_precision_compare [-h] -``` - -精度比对工具 - -```bash -msprobe -f compare [-h] -``` - -溢出解析工具 - -```bash -msprobe -f run_overflow_check [-h] -``` - -数据解析工具 - -```bash -msprobe -f parse [-h] -``` +[无标杆工具场景验证和性能基线报告](./docs/S02.report_free_benchmarking_validation_performance_baseline.md) -| 参数 | 说明 | -| ---- | ------------------------------------------------------------ | -| -f | 框架，请按所使用框架配置，当前支持配置为：pytorch、mindspore。 | -| -h | 帮助信息。 | +## ❓ FAQ -## 贡献 +[FAQ for PyTorch](./docs/FAQ_PyTorch.md) -push代码前，请务必保证已经完成了基础功能测试和网络测试。 +FAQ for MindSpore diff --git a/debug/accuracy_tools/msprobe/config/config.json b/debug/accuracy_tools/msprobe/config.json similarity index 100% rename from debug/accuracy_tools/msprobe/config/config.json rename to debug/accuracy_tools/msprobe/config.json diff --git a/debug/accuracy_tools/msprobe/config/README.md b/debug/accuracy_tools/msprobe/config/README.md deleted file mode 100644 index 7720ddbdf9246f0556833a3329c9c42ee8620bd5..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/config/README.md +++ /dev/null @@ -1,539 +0,0 @@ -# 配置文件说明 - -当前配置文件主要为PrecisionDebugger接口执行dump或无标杆比对操作时调用的配置，当PrecisionDebugger接口未指定该配置文件时，使用该文件的默认配置。配置文件详见[config.json](./config.json)。 - -当在环境上安装msprobe工具后，config.json文件位置可通过如下方式查找： - -查找msprobe工具安装路径。 - -``` -pip show mindstudio-probe -``` - -输出结果如下示例： - -``` -Name: mindstudio-probe -Version: 1.0 -Summary: This is a pytorch precision comparison tools -Home-page: -Author: -Author-email: -License: -Location: /home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages -Requires: numpy, openpyxl, pandas, pyyaml, rich, tqdm, wheel -Required-by: -``` - -Location字段为msprobe工具的安装路径，那么config.json文件位置为/home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages/msprobe/config - -## 参数说明 - -### **通用配置参数** - -| 参数名 | 说明 | 是否必选 | -| ----------------- | ------------------------------------------------------------ | -------- | -| task | dump的任务类型，str类型。可取值：
"free_benchmark"（无标杆比对）。
"statistics"（仅dump张量的统计信息，默认值）。
"tensor"（dump张量的统计信息和完整张量数据，MindSpore静态图场景仅dump完整张量数据）。
"overflow_check"（溢出检测）。
"run_ut"（精度预检配置）。
配置示例："task": "tensor"。
根据task参数取值的不同，可以配置不同场景参数，详见：“**task配置为free_benchmark**”，“**task配置为statistics**”，“**task配置为tensor**”，“**task配置为overflow_check**”，“**task配置为run_ut**”。 | 否 | -| dump_path | 设置dump数据目录路径，str类型。配置示例："dump_path": "./dump_path"。MindSpore静态图场景仅支持绝对路径。 | 是 | -| rank | 指定对某张卡上的数据进行dump，list[int]类型，默认未配置（表示dump所有卡的数据），应配置为大于等于0的整数，且须配置实际可用的Rank ID。配置示例："rank": [1]。
对于PyTorch场景，Rank ID从0开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的Rank ID，则dump数据为空，比如当前环境Rank ID为0到7，实际训练运行0到3卡，此时若配置Rank ID为4或不存在的10等其他值，此时dump数据为空。
对于MindSpore场景，所有节点的Rank ID均从0开始计数，最大取值为每个节点可用卡总数-1，config.json配置一次rank参数对所有节点同时生效。 | 否 | -| step | 指定dump某个step的数据，list[int]类型。默认未配置，表示dump所有step数据。dump特定step时，须指定为训练脚本中存在的step。step为list格式，可配置逐个step，例如："step": [0,1,2]。 | 否 | -| level | dump级别，str类型，根据不同级别dump不同数据。可取值：
"L0"（dump module模块级精度数据，仅PyTorch场景支持，使用背景详见“**模块级精度数据dump说明**”）。
"L1"（dump API级精度数据，默认值，仅MindSpore动态图和PyTorch场景支持）。
"L2"（dump kernel级精度数据，仅MindSpore静态图和PyTorch场景支持，且PyTorch场景须配置acl_config参数）。
"mix"（dump module模块级和API级精度数据，即"L0"+"L1"，仅PyTorch场景支持）。
配置示例："level": "L1"。MindSpore动态图场景仅支持"L1"。 | 否 | -| acl_config | kernel dump的配置文件，str类型。level取"L2"时，该参数必选；level为其他值时，该参数不选。参数示例：acl_config='./acl_config.json'。acl_config.json配置文件详细介绍请参见“**acl_config.json配置文件说明**”。 | 否 | -| seed | 随机种子数，int类型，默认值为：1234，仅PyTorch场景支持。通过固定随机数保证模型的输入或输出一致，可固定的随机数详见“**固定随机数范围**”。配置示例："seed": 1234。 | 否 | -| is_deterministic | 确定性计算模式，bool类型，仅PyTorch场景支持。可取值true（开启）或false（关闭），默认关闭。配置示例："is_deterministic": true。
即使在相同的硬件和输入下，API多次执行的结果也可能不同，开启确定性计算是为了保证在相同的硬件和输入下，API多次执行的结果相同。
确定性计算会导致API执行性能降低，建议在发现模型多次执行结果不同的情况下开启。
rnn类算子、ReduceSum、ReduceMean等算子可能与确定性计算存在冲突，若开启确定性计算后多次执行的结果不相同，则考虑存在这些算子。 | 否 | -| enable_dataloader | 自动控制开关，bool类型，仅PyTorch场景支持。可取值true（开启）或false（关闭），默认为false。配置为True后自动识别step参数指定的迭代，并在该迭代执行完成后退出训练，此时start、stop和step函数可不配置，开启该开关要求训练脚本是通过torch.utils.data.dataloader方式加载数据。仅支持PyTorch单卡训练使用，分布式训练场景下存在数据dump不全问题，**下个版本即将废弃该功能**。 | 否 | - -### task配置为free_benchmark - -仅PyTorch场景与MindSpore动态图场景支持，且"level"需为"L1"。 - -task配置为free_benchmark时，开启**无标杆比对**，在NPU环境下通过对当前模型API的输入添加扰动因子，二次执行，将得到的输出与未添加扰动因子前的输出进行比对，从而**得出该模型中可能因迁移等变化导致精度降低的API**。 - -无标杆比对优势在于省去了从CPU/GPU环境获取标杆数据的步骤，也省去了在NPU环境执行dump的操作，降低了精度比对的操作难度。 - -建议配置白名单（配置scope或list）控制少量API进行无标杆比对，一次对过多API执行无标杆比对可能导致显存溢出或性能膨胀。 - -| 参数名 | 说明 | 是否必选 | -| ------------ | ------------------------------------------------------------ | -------- | -| scope | 自定义检测API列表（仅PyTorch场景支持），list[str]类型，默认值为空列表，当list也为空列表时，表示检测所有API。需要在[]内配置具体API名（在工具dump结果中查看）。配置示例："scope": ["Torch.matmul.0", "Tensor.pow.4"]。与list参数不能同时配置。 | 否 | -| list | 自定义检测API类型或API名称，list[str]类型，默认值为空列表，表示检测所有API（PyTorch场景下还需scope也为空列表）。包含如下配置方法：
PyTorch场景下，指定某一类API，对某一类的API进行无标杆比对。配置示例："list": ["relu"]。
MindSpore场景下，指定API名称，对列表中的API进行检测。配置示例："list": ["mindspore.mint.div", "mindspore.ops.bmm", "mindspore.Tensor.\_\_add\_\_"]。
与scope参数不能同时配置。 | 否 | -| fuzz_device | 标杆设备，str类型。可取值：
"npu"：无标杆，通过添加扰动因子进行比对，默认值。
"cpu"：以CPU为标杆，pert_mode须配置为"to_cpu"（仅PyTorch场景支持）。
配置示例："fuzz_device": "npu"。 | 否 | -| pert_mode | 无标杆扰动因子，str类型。可取值：
"improve_precision"：对输入做升精度，默认值。
"add_noise"：对输入增加噪声。
"no_change"：不加扰动直接二次执行。
"bit_noise"：输入的末位比特翻转。
"change_value"：输入的张量首尾值调换（仅PyTorch场景支持）。
"to_cpu"：在CPU等价执行（仅PyTorch场景支持）。
配置示例："pert_mode": "improve_precision"。 | 否 | -| handler_type | 处理类型，可取值："check"（进行无标杆比对检查，默认值）、"fix"（将扰动后的API输出结果覆盖原始API输出结果，尝试将Loss曲线恢复正常，该模式下不支持预热if_preheat与反向过程）。配置示例："handler_type": "fix"。 | 否 | -| fuzz_level | 无标杆数据dump级别，即选择比对结果文件应输出的表头属性，当前仅支持取值为："L1"（默认值）。输出结果详见“**无标杆比对数据存盘格式**”。 | 否 | -| fuzz_stage | 前反向，选择对API前向或反向进行无标杆比对，可取值："forward"（前向，默认值）、"backward"（反向，仅PyTorch场景支持）。配置示例："fuzz_stage": "forward"。 | 否 | -| if_preheat | 预热功能（仅PyTorch场景支持），开启功能后工具可以根据每次迭代的输出调整精度算法的阈值，从而更准确找出存在精度问题的API，bool类型。可取值true（开启）或false（关闭），默认关闭。配置示例："if_preheat": "true"。"handler_type": "fix"不支持预热。 | 否 | -| preheat_step | 开启预热的迭代数量（仅PyTorch场景支持），int类型，默认值为15。须配置"if_preheat": "true"。 | 否 | -| max_sample | 每个算子预热的采样次数的最大阈值（仅PyTorch场景支持），int类型，默认值为20。须配置"if_preheat": "true"。 | 否 | - -#### 无标杆比对数据存盘格式 - -无标杆比对在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类型。 | - -### task配置为statistics - -| 参数名 | 说明 | 是否必选 | -| ------------ | ------------------------------------------------------------ | -------- | -| scope | PyTorch和MindSpore动态图场景dump范围，list[str]类型，默认未配置（list也未配置时表示dump所有API的数据）。需要在[]内配置两个模块名或API名，用于锁定区间，dump该范围内的数据。配置示例："scope": ["MyModuleOP1", "MyModuleOP2"]。与level参数取值相关，level为L0和mix级别时，可配置模块名；level为L1级别时，可配置API名。MindSpore动态图场景当前仅支持配置为API名。 | 否 | -| list | 自定义dump范围，list[str]类型，默认未配置（scope也未配置时表示dump所有API的数据）。包含如下配置方法：
PyTorch和MindSpore动态图场景配置具体的API全称，dump该API数据。配置示例："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。
PyTorch和MindSpore动态图场景指定某一类API，dump某一类的API级别输入输出数据。配置示例："list": ["relu"]。
MindSpore静态图场景配置kernel_name，可以是算子的名称列表，也可以指定算子类型（"level": "L2"时不支持），还可以配置算子名称的正则表达式（当字符串符合”name-regex(xxx)”格式时，后台则会将其作为正则表达式。例如，”name-regex(Default/.+)”可匹配算子名称以”Default/”开头的所有算子）。 | 否 | -| data_mode | dump数据过滤，str类型。可取值"all"、"forward"、"backward"、"input"和"output"，表示仅保存dump的数据中文件名包含"forward"、"backward"、"input"和"output"的前向、反向、输入或输出的dump文件。配置示例"data_mode": ["backward"]或"data_mode": ["forward", "backward"]。默认为["all"]，即保存所有dump的数据。除了all参数只能单独配置外，其他参数可以自由组合。
MindSpore静态图场景仅支持"all"、"input"和"output"参数，且各参数只能单独配置，不支持自由组合。 | 否 | -| summary_mode | 控制dump文件输出的模式，str类型，仅PyTorch和MindSpore动态图场景支持，可取值md5（dump输出包含md5值以及API统计信息的dump.json文件，用于验证数据的完整性）、statistics（dump仅输出包含API统计信息的dump.json文件，默认值）。配置示例："summary_mode": "md5"。 | 否 | - -### task配置为tensor - -MindSpore静态图场景仅dump完整张量数据。 - -| 参数名 | 说明 | 是否必选 | -| -------------- | ------------------------------------------------------------ | -------- | -| scope | PyTorch和MindSpore动态图场景dump范围，list[str]类型，默认未配置（list也未配置时表示dump所有API的数据）。需要在[]内配置两个模块名或API名，用于锁定区间，dump该范围内的数据。配置示例："scope": ["MyModuleOP1", "MyModuleOP2"]。与level参数取值相关，level为L0和mix级别时，可配置模块名；level为L1级别时，可配置API名。 | 否 | -| list | 自定义dump范围，list[str]类型，默认未配置（scope也未配置时表示dump所有API的数据）。包含如下配置方法：
PyTorch和MindSpore动态图场景配置具体的API全称，dump该API数据。配置示例："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。
PyTorch和MindSpore动态图场景指定某一类API，dump某一类的API级别输入输出数据。配置示例："list": ["relu"]。
PyTorch和MindSpore动态图场景配置kernel_api，dump前向和反向API的kernel_api级别数据，其中dump反向API时需要配置**backward_input**参数。前向API配置示例："list": ["Tensor.permute.1.forward"]；反API配置示例："list": ["Tensor.permute.1.forward"], "backward.input": "./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"]。
MindSpore静态图场景配置kernel_name，可以是算子的名称列表，也可以指定算子类型（"level": "L2"时不支持），还可以配置算子名称的正则表达式（当字符串符合”name-regex(xxx)”格式时，后台则会将其作为正则表达式。例如，”name-regex(Default/.+)”可匹配算子名称以”Default/”开头的所有算子）。 | 否 | -| backward_input | 该输入文件为首次运行训练dump得到反向API输入的dump文件，str类型，仅PyTorch场景支持，默认未配置。例如若需要dump Functional.conv2d.1 API的反向过程的输入输出，则需要在dump目录下查找命名包含Functional.conv2d.1、backward和input字段的dump文件。配置示例："backward_input": "./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"] | 否 | -| data_mode | dump数据过滤，str类型。可取值"all"、"forward"、"backward"、"input"和"output"，表示仅保存dump的数据中文件名包含"forward"、"backward"、"input"和"output"的前向、反向、输入或输出的dump文件。配置示例"data_mode": ["backward"]或"data_mode": ["forward", "backward"]。默认为["all"]，即保存所有dump的数据。除了all参数只能单独配置外，其他参数可以自由组合。
MindSpore静态图场景仅支持"all"、"input"和"output"参数，且各参数只能单独配置，不支持自由组合。 | 否 | -| file_format | MindSpore静态图场景真实tensor数据的保存格式，str类型，可取值"bin"（dump的tensor文件为二进制格式，"level": "L1"时不支持）、"npy"（dump的tensor文件后缀为.npy，默认值）。 | 否 | -| online_run_ut | 在线预检模式开关，bool类型，可取值true（开启）、false（关闭），默认未配置，表示关闭。配置为true表示开启在线预检。 | 否 | -| nfs_path | 在线预检模式共享存储目录路径，str类型，用于GPU设备和NPU设备间进行通信。仅在online_run_ut字段配置为true时生效，未配置该参数后host和port不生效。 | 否 | -| host | 在线预检模式局域网场景信息接收端IP，str类型，用于GPU设备和NPU设备间进行通信，NPU侧须配置为GPU侧的局域网IP地址。仅在online_run_ut字段配置为true时生效，局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | -| port | 在线预检模式局域网场景信息接收端端口号，int类型，用于GPU设备和NPU设备间进行通信，NPU侧须配置为GPU侧的端口号。仅在online_run_ut字段配置为true时生效，局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | - -说明： online_run_ut、nfs_path、host、port参数仅在线预检场景NPU环境生效，详细说明请参见[《在线精度预检》](../pytorch/doc/api_accuracy_checker_online.md)。 - -### task配置为overflow_check - -MindSpore静态图场景的jit_level为O0/O1时，不支持该功能，须配置jit_level为O2。请参见[mindspore.set_context](https://www.mindspore.cn/docs/zh-CN/r2.3.0/api_python/mindspore/mindspore.JitConfig.html#mindspore-jitconfig)配置jit_config。 - -| 参数名 | 说明 | 是否必选 | -| ------------- | ------------------------------------------------------------ | -------- | -| overflow_nums | 控制溢出次数，int类型，仅MindSpore动态图和PyTorch场景支持，表示第N次溢出时，停止训练，过程中检测到溢出API对应kernel数据均dump。配置示例："overflow_nums": 3。默认为1，即检测到1次溢出，训练停止，配置为-1时，表示持续检测溢出直到训练结束。 | 否 | -| check_mode | MindSpore静态图场景kernel级别的溢出检测，str类型，可取值"aicore"（开启AI Core的溢出检测）、"atomic"（开启Atomic的溢出检测）、"all"（开启AI Core和Atomic的溢出检测，默认值）。配置示例"check_mode": "aicore"。 | 否 | - -### task配置为run_ut - -仅PyTorch场景支持。 - -| 参数名称 | 说明 | 是否必选 | -|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------| -| white_list | API dump白名单，仅对指定的API进行dump。配置示例："white_list": ["conv1d", "conv2d"]。默认未配置白名单，即dump全量API数据。 | 否 | -| black_list | API dump黑名单，被指定的API不进行dump。配置示例："black_list": ["conv1d", "conv2d"]。默认未配置黑名单，即dump全量API数据。 | 否 | -| error_data_path | 配置保存精度未达标的API输入输出数据路径，默认为当前路径。配置示例"error_data_path": "./"。 | 否 | -| is_online | 在线预检模式开关，bool类型，可取值true（开启）、false（关闭），默认关闭。 | 否 | -| nfs_path | 在线预检模式共享存储目录路径，str类型，用于GPU设备和NPU设备间进行通信。配置该参数后host和port不生效，仅在is_online字段配置为true时生效。 | 否 | -| host | 在线预检模式局域网场景信息接收端IP，str类型，用于GPU设备和NPU设备间进行通信，GPU侧配置为本机地址127.0.0.1或本机局域网IP。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。仅在is_online字段配置为true时生效。 | 否 | -| port | 在线预检模式局域网场景信息接收端端口号，int类型，用于GPU设备和NPU设备间进行通信，GPU侧配置为本机可用端口。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。仅在is_online字段配置为true时生效。 | 否 | -| rank_list | 指定在线预检的Rank ID，默认值为[0]，list[int]类型，应配置为大于等于0的整数，且须根据实际卡的Rank ID配置，若所配置的值大于实际训练所运行的卡的Rank ID，则在线预检输出数据为空。GPU和NPU须配置一致。仅在is_online字段配置为true时生效。 | 否 | - -说明： -
（1）white_list和black_list同时配置时，二者配置的API名单若无交集，则白名单生效，若API名单存在交集，则白名单排除的部分以及交集的API不进行dump。 -
（2）is_online、nfs_path、host、port、rank_list等字段仅在线预检场景GPU机器生效，详细说明见[《在线精度预检》](../pytorch/doc/api_accuracy_checker_online.md) - -## 配置示例 - -以下示例包含当前支持的所有场景可配置的完整参数。 - -### PyTorch场景task配置为free_benchmark - -```json -{ - "task": "free_benchmark", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - "enable_dataloader": false, - - "free_benchmark": { - "scope": [], - "list": ["conv2d"], - "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 - } -} -``` - -### PyTorch场景task配置为statistics - -```json -{ - "task": "statistics", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - "enable_dataloader": false, - - "statistics": { - "scope": [], - "list": [], - "data_mode": ["all"], - "summary_mode": "statistics" - } -} -``` - -### PyTorch场景task配置为tensor - -```json -{ - "task": "tensor", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - "enable_dataloader": false, - - "tensor": { - "scope": [], - "list":[], - "data_mode": ["all"], - "backward_input": "" - } -} -``` - -### PyTorch场景task配置为overflow_check - -```json -{ - "task": "overflow_check", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - "enable_dataloader": false, - - "overflow_check": { - "overflow_nums": 1 - } -} -``` - -### PyTorch场景task配置为run_ut - -```json -{ - "task": "run_ut", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - "enable_dataloader": false, - - "run_ut": { - "white_list": [], - "black_list": [], - "error_data_path": "./" - } -} -``` - -### MindSpore静态图场景task配置为statistics - -```json -{ - "task": "statistics", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L2", - - "statistics": { - "list": [], - "data_mode": ["all"], - "summary_mode": "statistics" - } -} -``` - -### MindSpore静态图场景task配置为tensor - -```json -{ - "task": "tensor", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L2", - - "tensor": { - "list":[], - "data_mode": ["all"], - "backward_input": "" - } -} -``` - -### MindSpore静态图场景task配置为overflow_check - -```json -{ - "task": "overflow_check", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L2", - - "overflow_check": { - "check_mode": "all" - } -} -``` - -### MindSpore动态图场景task配置为free_benchmark - -```json -{ - "task": "free_benchmark", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - - "free_benchmark": { - "list": ["mindspore.ops.add"], - "fuzz_device": "npu", - "pert_mode": "improve_precision", - "handler_type": "check", - "fuzz_level": "L1", - "fuzz_stage": "forward" - } -} -``` - -### MindSpore动态图场景task配置为statistics - -```json -{ - "task": "statistics", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - - "statistics": { - "scope": [], - "list": [], - "data_mode": ["all"], - "summary_mode": "statistics" - } -} -``` - -### MindSpore动态图场景task配置为tensor - -```json -{ - "task": "tensor", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - - "tensor": { - "scope": [], - "list":[], - "data_mode": ["all"], - } -} -``` - -### MindSpore动态图场景task配置为overflow_check - -```json -{ - "task": "overflow_check", - "dump_path": "/home/data_dump", - "rank": [], - "step": [], - "level": "L1", - - "overflow_check": { - "overflow_nums": 1 - } -} -``` - -## 附录 - -### 模块级精度数据dump说明 - -仅PyTorch场景支持。 - -大模型场景下，通常不是简单的利用自动迁移能力实现GPU到NPU的训练脚本迁移，而是会对NPU网络进行一系列针对性的适配，因此，常常会造成迁移后的NPU模型存在部分子结构不能与GPU原始模型完全对应。模型结构不一致导致API调用类型及数量不一致，若直接按照API粒度进行精度数据dump和比对，则无法完全比对所有的API。 - -本节介绍的功能是对模型中的大粒度模块进行数据dump，使其比对时，对于无法以API粒度比对的模块可以直接以模块粒度进行比对。 - -模块指的是继承自nn.Module类模块，通常情况下这类模块就是一个小模型，可以被视为一个整体，dump数据时以模块为粒度进行dump。 - -### acl_config.json配置文件说明 - -#### [config.json](./config.json)配置示例 - -当PyTorch场景level取"L2"时，须配置acl_config参数，并指定acl_config.json文件（用于指定L2 kernel级dump的配置），此时config.json文件配置示例如下： - -- 前向kernel dump配置示例： - - "scope"配置为前向API名称，仅支持配置一个API。 - - ```json - { - "task": "tensor", - "dump_path": "/home/data_dump", - "level": "L2", - "rank": [0], - "step": [0], - "is_deterministic": false, - "tensor": { - "scope": ["Tensor.__mul__.10.forward"], - "list":[], - "data_mode": ["all"], - "backward_input": [""], - "file_format": "npy" - }, - "acl_config": "acl_config.json" - } - ``` - -- 反向kernel dump配置示例： - - 执行反向kernel dump前需要先使用工具dump该API的反向输入，保存pt文件，在"backward_input"参数中传入该pt文件路径。 - - "scope"配置为反向API名称，仅支持配置一个API。 - - ```json - { - "task": "tensor", - "dump_path": "/home/data_dump", - "level": "L2", - "rank": [0], - "step": [0], - "is_deterministic": false, - "tensor": { - "scope": ["Tensor.__mul__.10.backward"], - "list":[], - "data_mode": ["all"], - "backward_input": ["Tensor.__mul__.10.backward.input.0.pt"], - "file_format": "npy" - }, - "acl_config": "acl_config.json" - } - ``` - -#### acl_config.json配置示例 - -acl_config.json文件须自行创建，配置示例如下： - -``` -{ - "dump": - { - "dump_list":[], - "dump_path":"./dump/output", - "dump_mode":"all", - "dump_op_switch":"on" - } -} -``` - -**acl_config.json参数说明** - -| 字段名 | 说明 | -| -------------- | ------------------------------------------------------------ | -| dump_list | 待dump数据的API模型。为空，无需配置。 | -| dump_path | dump数据文件存储到运行环境的目录，主要配置的是kernel级数据的存放路径。支持配置绝对路径或相对路径。dump_path须为已存在目录。 | -| dump_mode | dump数据模式，配置如下： output：dump API的输出数据。默认值。 input：dump API的输入数据。 all：dump API的输入、输出数据。 | -| dump_op_switch | 单API模型dump数据开关，配置如下：
off：关闭单API模型dump，默认值。
on：开启单API模型dump。 | - -**dump目录说明** - -配置acl_config.json后，采集的kernel级数据会在{dump_path}/{time}/{deviceid}/{model_id}目录下生成，例如“/home/HwHiAiUser/output/20200808163566/0/0” - -``` -├── 20230131172437 -│ └── 1 -│ ├── 0 -│ │ ├── Add.Add.45.0.1675157077183551 -│ │ ├── Cast.trans_Cast_0.31.0.1675157077159449 -│ │ ├── Cast.trans_Cast_5.43.0.1675157077180129 -│ │ ├── MatMul.MatMul.39.0.1675157077172961 -│ │ ├── Mul.Mul.29.0.1675157077155731 -│ │ ├── NPUAllocFloatStatus.NPUAllocFloatStatus.24.0.1675157077145262 -│ │ ├── TransData.trans_TransData_1.33.0.1675157077162791 -│ │ └── TransData.trans_TransData_4.41.0.1675157077176648 -│ ├── 1701737061 -│ │ └── Cast.trans_Cast_2.35.0.1675157077166214 -│ ├── 25 -│ │ └── NPUClearFloatStatus.NPUClearFloatStatus.26.0.1675157077150342 -│ └── 68 -│ └── TransData.trans_TransData_3.37.0.1675157077169473 -``` - -### 固定随机数范围 - -仅PyTorch场景支持。 - -seed_all函数可固定随机数的范围如下表。 - -| API | 固定随机数 | -| ---------------------------------------- | --------------------------- | -| os.environ['PYTHONHASHSEED'] = str(seed) | 禁止Python中的hash随机化 | -| random.seed(seed) | 设置random随机生成器的种子 | -| np.random.seed(seed) | 设置numpy中随机生成器的种子 | -| torch.manual_seed(seed) | 设置当前CPU的随机种子 | -| torch.cuda.manual_seed(seed) | 设置当前GPU的随机种子 | -| torch.cuda.manual_seed_all(seed) | 设置所有GPU的随机种子 | -| torch_npu.npu.manual_seed(seed) | 设置当前NPU的随机种子 | -| torch_npu.npu.manual_seed_all(seed) | 设置所有NPU的随机种子 | -| torch.backends.cudnn.enable=False | 关闭cuDNN | -| torch.backends.cudnn.benchmark=False | cuDNN确定性地选择算法 | -| torch.backends.cudnn.deterministic=True | cuDNN仅使用确定性的卷积算法 | - -需要保证CPU或GPU以及NPU的模型输入完全一致，dump数据的比对才有意义，seed_all并不能保证模型输入完全一致，如下表所示场景需要保证输入的一致性。 - -| 场景 | 固定方法 | -| --------------- | ------------- | -| 数据集的shuffle | 关闭shuffle。 | -| dropout | 关闭dropout。 | - -关闭shuffle示例： - -```Python -train_loader = torch.utils.data.DataLoader( - train_dataset, - batch_size = batch_size, - shuffle = False, - num_workers = num_workers -) -``` - -关闭dropout： - -在使用from msprobe.pytorch import PrecisionDebugger后，工具会自动将torch.nn.functional.dropout、torch.nn.functional.dropout2d、torch.nn.functional.dropout3d、torch.nn.Dropout、torch.nn.Dropout2d、torch.nn.Dropout3d的接口参数p置为0。 diff --git a/debug/accuracy_tools/msprobe/docs/01.installation.md b/debug/accuracy_tools/msprobe/docs/01.installation.md new file mode 100644 index 0000000000000000000000000000000000000000..7463ee2a5ad3a6159666115b6f867763a7f22f56 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/01.installation.md @@ -0,0 +1,91 @@ +# 安装 + +推荐使用 [miniconda](https://docs.anaconda.com/miniconda/) 管理环境依赖。 + +```bash +conda create -n msprobe python=3.8 +conda activate msprobe +``` + +## 1. 从 PyPI 安装 +```shell +pip install mindstudio-probe[==版本号] +``` + +## 2. 下载 whl 包安装 + +|版本|发布日期|支持 PyTorch 版本|支持 MindSpore 版本|下载链接|校验码| +|:--:|:--:|:--:|:--:|:--:|:--:| +| 1.0.3 | 2024.08.23 | 1.11/2.0/2.1/2.2 | 2.3.1/2.4 | [mindstudio_probe-1.0.3-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.3-py3-none-any.whl) | 7060cc141a5b98ef770cd9220995d299393f32a61938261e632c7e8b5160bef2 | +| 1.0.2 | 2024.08.09 | 1.11/2.0/2.1/2.2 | 2.3.1 | [mindstudio_probe-1.0.2-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.2-py3-none-any.whl) | e4a980e5d98c426ce5ce9842520d9bc031d3b3de621c74b3d59414cc6e238e0e | +| 1.0.1 | 2024.07.25 | 2.0/2.1/2.2 | 2.3.1 | [mindstudio_probe-1.0.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/msprobe/1.0/mindstudio_probe-1.0.1-py3-none-any.whl) | b699e224e4d4e3bcf9412c54fa858a1ee370f0d7a2bc69cb3f1273ac14a6dc82 | +| 0.0.3 | 2024.06.11 | 2.0/2.1/2.2 | 2.3.0 | [ascend_training_accuracy_tools-1.0-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/1.0/ascend_training_accuracy_tools-1.0-py3-none-any.whl) | 5016dfe886c5d340ec6f60a959673355855f313c91f100680da814efb49f8e81 | +| 0.0.2 | 2024.05.23 | 2.0/2.1/2.2 | 2.3.0 | [ascend_training_accuracy_tools-0.0.2-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/0.0/ascend_training_accuracy_tools-0.0.2-py3-none-any.whl) | 2e35809bde559e9c4d2f16a02ccde779ed9e436bb65fded0b7ebaf6ac2c88d93 | +| 0.0.1 | 2024.03.15 | 2.0/2.1 | - | [ascend_training_accuracy_tools-0.0.1-py3-none-any.whl](https://ptdbg.obs.myhuaweicloud.com/att/0.0/ascend_training_accuracy_tools-0.0.1-py3-none-any.whl) | 5801510d4e827e4859bc9a5aca021e4d30c2ea42d60a4c8ad0c2baab1b7782c9 | + +```bash +sha256sum {name}.whl # 验证whl包，若校验码一致，则whl包在下载中没有受损 +``` + +```bash +pip install ./mindstudio_probe-{version}-py3-none-any.whl # 安装whl包 +``` + +若覆盖安装，请在命令行末尾添加`--force-reinstall`参数。 + +## 3. 从源码安装 + +```shell +git clone https://gitee.com/ascend/mstt.git +cd debug/accuracy_tools + +pip install setuptools wheel + +python setup.py bdist_wheel +pip install ./dist/mindstudio_probe*.whl +``` + +# 查看 msprobe 工具信息 + +```bash +pip show mindstudio-probe +``` + +示例如下： + +```bash +Name: mindstudio-probe +Version: 1.0.* +Summary: Pytorch Ascend Probe Utils +Home-page: https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe +Author: Ascend Team +Author-email: pmail_mindstudio@huawei.com +License: Apache License 2.0 +Location: /home/***/miniconda3/envs/***/lib/python3.8/site-packages/mindstudio_probe-1.0.0-py3.8.egg +Requires: einops, matplotlib, numpy, openpyxl, pandas, pyOpenSSL, pyyaml, rich, tqdm, twisted, wheel +Required-by: +``` + +# Ascend 生态链接 + +## 1 安装 CANN 包 + +1.1 根据 CPU 架构和 NPU 型号选择 toolkit 和 kernal 包，可以参考 [CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)和[昇腾社区](https://www.hiascend.cn/developer/download/community/result?module=cann)。 + +1.2 运行示例 +```bash +Ascend-cann-toolkit_x.x.x_linux-aarch64.run --full --install-path={cann_path} +Ascend-cann-kernels_x.x.x_linux.run --install --install-path={cann_path} +``` + +1.3 配置环境变量 +```bash +source {cann_path}/ascend-toolkit/set_env.sh +``` +## 2 安装 PyTorch_NPU + +链接：[https://gitee.com/ascend/pytorch](https://gitee.com/ascend/pytorch)。 + +## 3 安装 ModelLink + +链接：[https://gitee.com/ascend/ModelLink](https://gitee.com/ascend/ModelLink)。 diff --git a/debug/accuracy_tools/msprobe/docs/02.config_introduction.md b/debug/accuracy_tools/msprobe/docs/02.config_introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..4f7c503fb285dacb53c5412e6a63f203782c8773 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/02.config_introduction.md @@ -0,0 +1,165 @@ +# 配置文件介绍 + +- 当调用 **PrecisionDebugger** 接口执行 dump 或其他操作时，需要使用 [config.json](../config.json) 文件；当未指定 config.json 时，将使用默认配置。 +- msprobe 成功安装后，config.json 一般位于如下目录： +``` +/home/***/miniconda3/envs/***/lib/python3.8/site-packages/msprobe/ +``` + +## 1 参数介绍 + +### 1.1 通用配置 + +| 参数名 | 解释 | 是否必选 | +| ----------------- | ---------------- | -------- | +| task | dump 的任务类型，str 类型。可取值，
"statistics"：仅 dump API 统计信息，默认值；
"tensor"：dump API 统计信息和完全复刻整网的 API 运行情况的真实数据；
"run_ut"：精度预检，仅 PyTorch 场景支持。
"overflow_check"：溢出检测，仅 PyTorch 和 MindSpore 静态图场景支持；
"free_benchmark"：无标杆比对，仅 PyTorch 场景支持；
根据 task 参数取值的不同，可以配置不同场景参数，详见：
[1.2 task 配置为 statistics](#12-task-配置为-statistics)，
[1.3 task 配置为 tensor](#13-task-配置为-tensor)，
[1.4 task 配置为 run_ut](#14-task-配置为-run_ut)，
[1.5 task 配置为 overflow_check](#15-task-配置为-overflow_check)，
[1.6 task 配置为 free_benchmark](#16-task-配置为-free_benchmark)。
**配置示例**："task": "tensor"。 | 否 | +| dump_path | 设置 dump 数据目录路径，str 类型。
**配置示例**："dump_path": "./dump_path"。MindSpore 场景仅支持绝对路径。 | 是 | +| rank | 指定对某张卡上的数据进行 dump，list[int] 类型，默认未配置（表示 dump 所有卡的数据），应配置为 ≥0 的整数，且须配置实际可用的 Rank ID。
对于 PyTorch 场景，Rank ID 从 0 开始计数，最大取值为所有节点可用卡总数-1，若所配置的值大于实际训练所运行的卡的 Rank ID，则 dump 数据为空，比如当前环境 Rank ID 为 0 到 7，实际训练运行 0 到 3 卡，此时若配置 Rank ID 为 4 或不存在的 10 等其他值，此时 dump 数据为空。
对于 MindSpore 场景，所有节点的 Rank ID 均从 0 开始计数，最大取值为每个节点可用卡总数-1，config.json 配置一次 rank 参数对所有节点同时生效。
**配置示例**："rank": [1]。 | 否 | +| step | 指定 dump 某个 step 的数据，list[int] 类型。默认未配置，表示 dump 所有 step 数据。dump 特定 step 时，须指定为训练脚本中存在的 step。step 为 list 格式，可配置逐个 step。
**配置示例**："step": [0,1,2]。 | 否 | +| level | dump 级别，str 类型，根据不同级别 dump 不同数据。可取值，
"L0"：dump module 模块级精度数据，仅 PyTorch 场景支持，使用背景详见**\*1**；
"L1"：dump API 级精度数据，默认值；
"L2"：dump kernel 级精度数据，须配置 acl_config 参数；
"mix"：dump module 模块级和 API 级精度数据，即"L0"+"L1"，仅 PyTorch 场景支持。
**配置示例**："level": "L1"。 | 否 | +| acl_config | kernel dump 的配置文件，str 类型。level 取"L2"时，该参数必要；level 为其他值时，该参数不选。
**配置示例**：acl_config="./acl_config.json"。具体配置见[ acl_config 示例](./04.acl_config_examples.md)。 | 否 | +| seed | 随机种子数，int 类型，默认值为：1234，仅 PyTorch 场景支持。通过固定随机数保证模型的输入或输出一致，可固定的随机数详见**\*2**。
**配置示例**："seed": 1234。 | 否 | +| is_deterministic | 确定性计算模式，bool 类型，仅 PyTorch 场景支持。可取值 true（开启）或 false（关闭），默认关闭。
即使在相同的硬件和输入下，API 多次执行的结果也可能不同，开启确定性计算是为了保证在相同的硬件和输入下，API 多次执行的结果相同。
确定性计算会导致 API 执行性能降低，建议在发现模型多次执行结果不同的情况下开启。
rnn 类算子、ReduceSum、ReduceMean 等算子可能与确定性计算存在冲突，若开启确定性计算后多次执行的结果不相同，则考虑存在这些算子。
**配置示例**："is_deterministic": true。
| 否 | +| enable_dataloader | 自动控制开关，bool 类型，仅 PyTorch 场景支持。可取值 true（开启）或 false（关闭），默认为 false。配置为 True 后自动识别 step 参数指定的迭代，并在该迭代执行完成后退出训练，此时 start、stop 和 step 函数可不配置，开启该开关要求训练脚本是通过 torch.utils.data.dataloader 方式加载数据。仅支持 PyTorch 单卡训练使用，分布式训练场景下存在数据 dump 不全问题，**下个版本即将废弃该功能**。 | 否 | + +**\***： +1. 模块级精度数据 dump 说明（仅 PyTorch 场景支持） + + 大模型场景下，通常不是简单的利用自动迁移能力实现从 GPU 到 NPU 的训练脚本迁移，而是会对 NPU 网络进行一系列针对性的适配，因此，常常会造成迁移后的 NPU 模型存在部分子结构不能与 GPU 原始模型完全对应。模型结构不一致导致 API 调用类型及数量不一致，若直接按照 API 粒度进行精度数据 dump 和比对，则无法完全比对所有的 API。 + + 本小节介绍的功能是对模型中的大粒度模块进行数据 dump，使其比对时，对于无法以 API 粒度比对的模块可以直接以模块粒度进行比对。 + + 模块指的是继承自 nn.Module 类模块，通常情况下这类模块就是一个小模型，可以被视为一个整体，dump 数据时以模块为粒度进行 dump。 + +2. 固定随机数范围（仅 PyTorch 场景支持） + + seed_all 函数可固定随机数的范围如下表。 + + | API | 固定随机数 | + | ---------------------------------------- | --------------------------- | + | os.environ['PYTHONHASHSEED'] = str(seed) | 禁止 Python 中的 hash 随机化 | + | random.seed(seed) | 设置 random 随机生成器的种子 | + | np.random.seed(seed) | 设置 numpy 中随机生成器的种子 | + | torch.manual_seed(seed) | 设置当前 CPU 的随机种子 | + | torch.cuda.manual_seed(seed) | 设置当前 GPU 的随机种子 | + | torch.cuda.manual_seed_all(seed) | 设置所有 GPU 的随机种子 | + | torch_npu.npu.manual_seed(seed) | 设置当前 NPU 的随机种子 | + | torch_npu.npu.manual_seed_all(seed) | 设置所有 NPU 的随机种子 | + | torch.backends.cudnn.enable=False | 关闭 cuDNN | + | torch.backends.cudnn.benchmark=False | cuDNN 确定性地选择算法 | + | torch.backends.cudnn.deterministic=True | cuDNN 仅使用确定性的卷积算法 | + + 需要保证 CPU 或 GPU 以及 NPU 的模型输入完全一致，dump 数据的比对才有意义，seed_all 并不能保证模型输入完全一致，如下表所示场景需要保证输入的一致性。 + + | 场景 | 固定方法 | + | --------------- | ------------- | + | 数据集的 shuffle | 关闭 shuffle。 | + | dropout | 关闭 dropout。 | + + 关闭 shuffle 示例： + + ```python + train_loader = torch.utils.data.DataLoader( + train_dataset, + batch_size = batch_size, + shuffle = False, + num_workers = num_workers + ) + ``` + + 关闭 dropout： + + 在使用 `from msprobe.pytorch import PrecisionDebugger` 后，工具会自动将 `torch.nn.functional.dropout`、`torch.nn.functional.dropout2d`、`torch.nn.functional.dropout3d`、`torch.nn.Dropout`、`torch.nn.Dropout2d`、`torch.nn.Dropout3d` 的接口参数 p 置为0。 + +### 1.2 task 配置为 statistics + +| 参数名 | 解释 | 是否必选 | +| ------------ | ------------------- | -------- | +| scope | PyTorch 和 MindSpore 动态图场景 dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 API 的数据）。该参数在 [ ] 内配置两个模块名或API名，用于锁定区间，dump 该范围内的数据。
**配置示例**："scope": ["MyModuleOP1", "MyModuleOP2"]。与 level 参数取值相关，level 为 L0 和 mix 级别时，可配置模块名；level 为 L1 级别时，可配置 API 名。MindSpore 动态图场景当前仅支持配置为 API 名。 | 否 | +| list | 自定义 dump 范围，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 API 的数据）。包含如下配置方法：
PyTorch 和 MindSpore 动态图场景配置具体的 API 全称，dump 该 API 数据。
**配置示例**："list": ["Tensor.permute.1.forward", "Tensor.transpose.2.forward", "Torch.relu.3.backward"]。
PyTorch 和 MindSpore 动态图场景指定某一类 API，dump 某一类的 API 级别输入输出数据。
**配置示例**："list": ["relu"]。
MindSpore 静态图场景配置 kernel_name，可以是算子的名称列表，也可以指定算子类型（"level": "L2"时不支持），还可以配置算子名称的正则表达式（当字符串符合“name-regex(xxx)”格式时，后台则会将其作为正则表达式。例如，“name-regex(Default/.+)”可匹配算子名称以“Default/”开头的所有算子）。 | 否 | +| data_mode | dump 数据过滤，str 类型。可取值，
PyTorch 场景支持"all"、"forward"、"backward"、"input"和"output"，表示仅保存 dump 的数据中文件名包含"forward"、"backward"、"input"和"output"的前向、反向、输入或输出的 dump 文件。
MindSpore 场景仅支持"all"、"input"和"output"参数，且各参数只能单独配置，不支持自由组合。
**配置示例**："data_mode": ["backward"]或"data_mode": ["forward", "backward"]。默认为["all"]，即保存所有 dump 的数据。除了 all 参数只能单独配置外，其他参数可以自由组合。 | 否 | +| summary_mode | 控制 dump 文件输出的模式，str 类型，仅 PyTorch 场景支持，可取值，
md5：dump 输出包含 md5 值以及 API 统计信息的 dump.json 文件，用于验证数据的完整性；
statistics：dump 仅输出包含 API 统计信息的 dump.json 文件，默认值。
**配置示例**："summary_mode": "md5"。 | 否 | + +### 1.3 task 配置为 tensor + +| 参数名 | 解释 | 是否必选 | +| -------------- | ---------------------- | -------- | +| scope | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同。 | 否 | +| list | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同。另外，
PyTorch 和 MindSpore 动态图场景配置 kernel_api，dump 前向和反向 API 的kernel_api 级别数据，其中 dump 反向 API 时需要配置 **backward_input** 参数。
**前向 API 配置示例**："list": ["Tensor.permute.1.forward"]；
**反向 API 配置示例**："list": ["Tensor.permute.1.forward"], "backward.input": ["./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"]。
| 否 | +| backward_input | 该输入文件为首次运行训练 dump 得到反向 API 输入的 dump 文件，str 类型，仅 PyTorch 场景支持，默认未配置。例如若需要 dump Functional.conv2d.1 API 的反向过程的输入输出，则需要在 dump 目录下查找命名包含 Functional.conv2d.1、backward 和 input 字段的 dump 文件。
**配置示例**："backward_input": ["./npu_dump/step0/rank0/Functional.conv2d.1.backward.input.0.pt"] | 否 | +| data_mode | 与[ 1.2 task 配置为 statistics ](#12-task-配置为-statistics)中的解释相同 | 否 | +| file_format | MindSpore 场景真实 tensor 数据的保存格式，str 类型，可取值，
"bin"：dump 的 tensor 文件为二进制格式，"level": "L1" 时不支持；
"npy"：dump 的 tensor 文件后缀为 .npy，默认值。 | 否 | +| online_run_ut* | 在线预检模式开关，bool 类型，可取值 true（开启）、false（关闭），默认未配置，表示关闭。配置为 true 表示开启在线预预检。| 否 | +| nfs_path* | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。仅在 online_run_ut 字段配置为 true 时生效，未配置该参数后 host 和 port 不生效。 | 否 | +| host* | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。仅在 online_run_ut 字段配置为 true 时生效，局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 | +| port* | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。仅在 online_run_ut 字段配置为 true 时生效，局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。| 否 | + +**\***：online_run_ut、nfs_path、host、port 等字段仅在线预检场景 NPU 机器生效。 + +### 1.4 task 配置为 run_ut + +仅 PyTorch 场景支持。 + +| 参数名称 | 解释 | 是否必选 | +| --------------- | ------------------------ | ------------ | +| white_list**\*1** | API dump 白名单，仅对指定的 API 进行 dump。
**配置示例**："white_list": ["conv1d", "conv2d"]。默认未配置白名单，即 dump 全量 API 数据。 | 否 | +| black_list**\*1** | API dump 黑名单，被指定的 API 不进行 dump。
**配置示例**："black_list": ["conv1d", "conv2d"]。默认未配置黑名单，即 dump 全量 API 数据。 | 否 | +| error_data_path | 配置保存精度未达标的 API 输入输出数据路径，默认为当前路径。
**配置示例**："error_data_path": "./"。 | 否 | +| is_online**\*2** | 在线预检模式开关，bool 类型，可取值 true（开启）、false（关闭），默认关闭。 | 否 | +| nfs_path**\*2** | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效，仅在 is_online 字段配置为 true 时生效。 | 否 | +| host**\*2** | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。仅在 is_online 字段配置为 true 时生效。 | 否 | +| port**\*2** | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。仅在 is_online 字段配置为 true 时生效。| 否 | +| rank_list**\*2** | 指定在线预检的 Rank ID，默认值为[0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。仅在 is_online 字段配置为 true 时生效。 | 否 | + +**\***： +1. white_list 和 black_list 同时配置时，二者配置的 API 名单若无交集，则白名单生效，若 API 名单存在交集，则白名单排除的部分以及交集的 API 不进行 dump。 +2. is_online、nfs_path、host、port、rank_list 等字段仅在线预检场景 GPU 机器生效。 + +### 1.5 task 配置为 overflow_check + +| 参数名 | 解释 | 是否必选 | +| ------------- | ---------------------- | -------- | +| overflow_nums | 控制溢出次数，int 类型，仅 PyTorch 场景支持，表示第 N 次溢出时，停止训练，过程中检测到溢出 API 对应的 kernel 数据均 dump。
**配置示例**："overflow_nums": 3。默认为1，即检测到1次溢出，训练停止，配置为-1时，表示持续检测溢出直到训练结束。 | 否 | +| check_mode | MindSpore 场景 kernel 级别的溢出检测，str 类型，可取值：
"aicore"：开启 AI Core 的溢出检测；
"atomic"：开启 Atomic 的溢出检测；
"all"：开启 AI Core 和 Atomic 的溢出检测，默认值。
**配置示例**："check_mode": "aicore"。 | 否 | + +### 1.6 task 配置为 free_benchmark + +仅 PyTorch 场景与 MindSpore 动态图场景支持，且"level"为"L1"。 + +- task 配置为 free_benchmark 时，开启**无标杆比对**，在 NPU 环境下通过对当前模型 API 的输入添加扰动因子，二次执行，将得到的输出与未添加扰动因子前的输出进行比对，从而**得出该模型中可能存在因迁移等变化导致精度降低的 API**。 + +- 无标杆比对优势在于省去了从 CPU/GPU 环境获取标杆数据的步骤，也省去了在 NPU 环境执行 dump 的操作，降低了精度比对的操作难度。 + +- 建议配置白名单（配置 scope 或 list）控制少量 API 进行无标杆比对，一次对过多 API 执行无标杆比对可能导致显存溢出或性能膨胀。 + +| 参数名 | 解释 | 是否必选 | +| ------------ | -------------- | -------- | +| scope | 自定义检测 API 列表（仅 PyTorch 场景支持），list[str] 类型，默认值为空列表，当 list 也为空列表时，表示检测所有 API。需要在 [ ] 内配置具体 API 名（在 dump 的结果中查看）。
**配置示例**："scope": ["Torch.matmul.0", "Tensor.pow.4"]。
与 list 参数不能同时配置。 | 否 | +| list | 自定义检测 API 类型或 API 名称，list[str] 类型，默认值为空列表，表示检测所有 API（PyTorch 场景下还需 scope 也为空列表）。包含如下配置方法：
PyTorch 场景下，指定某一类 API，对某一类的 API 进行无标杆比对。
**配置示例**："list": ["relu"]。
MindSpore 场景下，指定 API 名称，对列表中的 API 进行检测。
**配置示例**："list": ["mindspore.mint.div", "mindspore.ops.bmm", "mindspore.Tensor.\_\_add\_\_"]。
与 scope 参数不能同时配置。 | 否 | +| fuzz_device | 标杆设备，str 类型。可取值，
"npu"：无标杆，通过添加扰动因子进行比对，默认值；
"cpu"：以 CPU 为标杆，pert_mode 须配置为"to_cpu"（仅 PyTorch 场景支持）。
**配置示例**："fuzz_device": "cpu"。 | 否 | +| pert_mode | 无标杆扰动因子，str 类型。可取值，
"improve_precision"：对输入做升精度，默认值；
"add_noise"：对输入增加噪声；
"no_change"：不加扰动直接二次执行；
"bit_noise"：输入的末位比特翻转；
"change_value"：输入的张量首尾值调换（仅 PyTorch 场景支持）；
"to_cpu"：在 CPU 等价执行（仅 PyTorch 场景支持）。
**配置示例**："pert_mode": "improve_precision"。 | 否 | +| handler_type | 处理类型，可取值，
"check"：进行无标杆比对检查，默认值；
"fix"：将扰动后的 API 输出结果覆盖原始 API 输出结果，尝试将 Loss 曲线恢复正常，该模式下不支持预热 if_preheat。
**配置示例**："handler_type": "fix"。 | 否 | +| fuzz_level | 无标杆数据 dump 级别，即选择比对结果文件应输出的表头属性，当前仅支持取值为："L1"。输出结果详见**\*1**。 | 否 | +| fuzz_stage | 前反向，选择对 API 前向或反向进行无标杆比对，可取值：
"forward"：前向，默认值；
"backward"：反向。
**配置示例**："fuzz_stage": "backward"。 | 否 | +| if_preheat | 预热功能（仅 PyTorch 场景支持），开启功能后工具可以根据每次迭代的输出调整精度算法的阈值，从而更准确地找出存在精度问题的 API，bool 类型。可取值：
true（开启）或 false（关闭），默认关闭。
**配置示例**："if_preheat": "true"。"handler_type": "fix"不支持预热。 | 否 | +| preheat_step | 开启预热的迭代数量（仅 PyTorch 场景支持），int 类型，默认值为 15。须配置 "if_preheat": "true"。 | 否 | +| max_sample | 每个算子预热的采样次数的最大阈值（仅 PyTorch 场景支持），int 类型，默认值为 20。须配置 "if_preheat": "true"。 | 否 | + +**\***： +1. 无标杆比对数据存盘格式 + + 无标杆比对在 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 类型。 | diff --git a/debug/accuracy_tools/msprobe/docs/03.config_examples.md b/debug/accuracy_tools/msprobe/docs/03.config_examples.md new file mode 100644 index 0000000000000000000000000000000000000000..f51c84054029850cfd5222c7cc97005c10b0f2a3 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/03.config_examples.md @@ -0,0 +1,247 @@ +# 配置示例 + +以下示例包含当前支持的所有场景可配置的完整参数。 + +## 1 PyTorch 场景 + +### 1.1 task 配置为 statistics + +```json +{ + "task": "statistics", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + "seed": 1234, + "is_deterministic": false, + "enable_dataloader": false, + + "statistics": { + "scope": [], + "list": [], + "data_mode": ["all"], + "summary_mode": "statistics" + } +} +``` + +### 1.2 task 配置为 tensor + +```json +{ + "task": "tensor", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + "seed": 1234, + "is_deterministic": false, + "enable_dataloader": false, + + "tensor": { + "scope": [], + "list":[], + "data_mode": ["all"], + "backward_input": "" + } +} +``` + +### 1.3 task 配置为 run_ut + +```json +{ + "task": "run_ut", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + "seed": 1234, + "is_deterministic": false, + "enable_dataloader": false, + + "run_ut": { + "white_list": [], + "black_list": [], + "error_data_path": "./" + } +} +``` + +### 1.4 task 配置为 overflow_check + +```json +{ + "task": "overflow_check", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + "seed": 1234, + "is_deterministic": false, + "enable_dataloader": false, + + "overflow_check": { + "overflow_nums": 1 + } +} +``` + +### 1.5 task 配置为 free_benchmark + +```json +{ + "task": "free_benchmark", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + "seed": 1234, + "is_deterministic": false, + "enable_dataloader": false, + + "free_benchmark": { + "scope": [], + "list": ["conv2d"], + "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 + } +} +``` + +## 2 MindSpore 静态图场景 + +### 2.1 task 配置为 statistics + +```json +{ + "task": "statistics", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L2", + + "statistics": { + "list": [], + "data_mode": ["all"], + "summary_mode": "statistics" + } +} +``` + +### 2.2 task 配置为 tensor + +```json +{ + "task": "tensor", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L2", + + "tensor": { + "list":[], + "data_mode": ["all"], + "backward_input": "" + } +} +``` + +### 2.3 task 配置为 overflow_check + +```json +{ + "task": "overflow_check", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L2", + + "overflow_check": { + "check_mode": "all" + } +} +``` + +## 3 MindSpore 动态图场景 + +### 3.1 task 配置为 statistics + +```json +{ + "task": "statistics", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + + "statistics": { + "scope": [], + "list": [], + "data_mode": ["all"], + "summary_mode": "statistics" + } +} +``` + +### 3.2 task 配置为 tensor + +```json +{ + "task": "tensor", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + + "tensor": { + "scope": [], + "list":[], + "data_mode": ["all"], + } +} +``` + +### 3.3 task 配置为 overflow_check + +```json +{ + "task": "overflow_check", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + + "overflow_check": { + "overflow_nums": 1 + } +} +``` + +### 3.4 task 配置为 free_benchmark + +```json +{ + "task": "free_benchmark", + "dump_path": "/home/data_dump", + "rank": [], + "step": [], + "level": "L1", + + "free_benchmark": { + "list": ["mindspore.ops.add"], + "fuzz_device": "npu", + "pert_mode": "improve_precision", + "handler_type": "check", + "fuzz_level": "L1", + "fuzz_stage": "forward" + } +} +``` diff --git a/debug/accuracy_tools/msprobe/docs/04.acl_config_examples.md b/debug/accuracy_tools/msprobe/docs/04.acl_config_examples.md new file mode 100644 index 0000000000000000000000000000000000000000..4095423bdf48e449d424caebfc3c71e130abcdfd --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/04.acl_config_examples.md @@ -0,0 +1,76 @@ +# acl_config.json 配置文件说明 + +当 PyTorch 场景 level 取"L2"时，须配置 acl_config 参数，并指定 acl_config.json 文件（用于指定 L2 kernel 级 dump 的配置），此时 **config.json** 文件配置示例如下： + +## 1 前向 kernel dump 配置示例 + +"scope"配置为前向 API 名称，仅支持配置一个 API。 + +```json +{ + "task": "tensor", + "dump_path": "/home/data_dump", + "level": "L2", + "rank": [0], + "step": [0], + "is_deterministic": false, + "tensor": { + "scope": ["Tensor.__mul__.10.forward"], + "list":[], + "data_mode": ["all"], + "backward_input": [""], + "file_format": "npy" + }, + "acl_config": "acl_config.json" +} +``` + +## 2 反向 kernel dump 配置示例 + +执行反向 kernel dump 前需要先使用工具 dump 该 API 的反向输入，保存 pt 文件，"backward_input"参数中传入该 pt 文件路径。 + +"scope"配置为反向API名称，仅支持配置一个API。 + +```json +{ + "task": "tensor", + "dump_path": "/home/data_dump", + "level": "L2", + "rank": [0], + "step": [0], + "is_deterministic": false, + "tensor": { + "scope": ["Tensor.__mul__.10.backward"], + "list":[], + "data_mode": ["all"], + "backward_input": ["Tensor.__mul__.10.backward.input.0.pt"], + "file_format": "npy" + }, + "acl_config": "acl_config.json" +} +``` + +## 3 acl_config.json 配置示例 + +该文件须自行创建，配置示例如下： + +```json +{ + "dump": + { + "dump_list":[], + "dump_path":"./dump/output", + "dump_mode":"all", + "dump_op_switch":"on" + } +} +``` + +**acl_config.json 参数说明** + +| 字段名 | 解释 | +| -------------- | ------------------------------------------------------------ | +| dump_list | 待 dump 数据的 API 模型。为空，无需配置。 | +| dump_path | dump 数据文件存储到运行环境的目录，主要配置的是 kernel 级数据的存放路径。支持配置绝对路径或相对路径。dump_path 须为已存在目录。 | +| dump_mode | dump 数据模式，可取值，
output：dump API 的输出数据，默认值；
input：dump API 的输入数据；
all：dump API 的输入、输出数据。 | +| dump_op_switch | 单 API 模型 dump 数据开关，可取值，
off：关闭单API模型dump，默认值；
on：开启单API模型dump。 | diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/dump.md b/debug/accuracy_tools/msprobe/docs/05.data_dump_Pytorch.md similarity index 40% rename from debug/accuracy_tools/msprobe/pytorch/doc/dump.md rename to debug/accuracy_tools/msprobe/docs/05.data_dump_Pytorch.md index 31d6303ba701bfd2331b8d28f75ad2a7899e3f3f..3f2b2a88b5fb4d247b98692c21341f43b74496f9 100644 --- a/debug/accuracy_tools/msprobe/pytorch/doc/dump.md +++ b/debug/accuracy_tools/msprobe/docs/05.data_dump_Pytorch.md @@ -1,177 +1,134 @@ -# **精度数据采集** +# PyTorch 场景下的精度数据采集 -msprobe工具主要通过在训练脚本内添加dump接口并启动训练的方式来采集精度数据。 +msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。 -执行dump操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 +本工具提供固定的 API 支持列表，若需要删除或增加 dump 的 API，可以在 msprobe/pytorch/hook_module/support_wrap_ops.yaml 文件内手动修改，如下示例： -## dump接口介绍 - -### PrecisionDebugger +```yaml +functional: # functional为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API + - conv1d + - conv2d + - conv3d +``` -**功能说明** +## 1 接口介绍 -通过加载dump配置文件的方式来确定dump操作的详细配置。 +### 1.1 PrecisionDebugger -PrecisionDebugger接口可以在from msprobe.pytorch import PrecisionDebugger之后的位置添加。详细使用可参考“**示例代码**”或“**model配置代码示例**”。 +**功能说明**：通过加载 dump 配置文件的方式来确定 dump 操作的详细配置。 -**原型** +**原型**： ```Python PrecisionDebugger(config_path=None, task=None, dump_path=None, level=None, model=None, step=None) ``` -说明：上述参数除config_path和model外，其他参数均在[config.json](../../config)文件中可配，此处的参数优先级高于[config.json](../../config)文件中的配置，而config.json文件可以配置更多参数，若需要进行更多场景的精度数据dump，建议配置[config.json](../../config)文件。config.json文件的配置可参考《[配置文件说明](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/config/README.md)》。 +**\***： +1. config_path：指定 dump 配置文件路径；model：指定具体的 torch.nn.Module，默认未配置，level 配置为"L0"或"mix"时必须配置该参数。其他参数均在 [config.json](../config.json) 文件中可配，详细配置可见 [config.json 介绍](./02.config_introduction.md)。 +2. 此接口的参数均不是必要，且优先级高于 [config.json](../config.json) 文件中的配置，但可配置的参数相比 config.json 较少。 -**参数说明** +### 1.2 start -| 参数名 | 说明 | 是否必选 | -| ----------- | ------------------------------------------------------------ | -------- | -| config_path | 指定dump配置文件路径，String类型。参数示例："./config.json"。未配置该路径时，默认使用[config.json](../../config)文件的默认配置。 | 否 | -| task | dump的任务类型，String类型。可取值"statistics"（仅dump API统计信息）、"tensor"（dump API统计信息和完全复刻整网的API运行情况的真实数据）、"overflow_check"（溢出检测），默认未配置，取"statistics"，参数示例：task="tensor"。 | 否 | -| dump_path | 设置dump数据目录路径，String类型。参数示例：dump_path="./dump_path"。 | 否 | -| level | dump级别，根据不同级别dump不同数据，String类型。可取值：
"L0"：dump module模块级精度数据，仅PyTorch场景支持”。
"L1"：dump API级精度数据，默认值。
"L2"：dump kernel级精度数据。
"mix"：dump module模块级和API级精度数据。
配置示例：level="L1"。 | 否 | -| model | 指定具体的torch.nn.Module，默认未配置，level配置为"L0"或"mix"时必须配置该参数。配置示例参见“**model配置代码示例**”。 | 否 | -| step | 指定dump某个step的数据，list[int]类型。默认未配置，表示dump所有step数据。dump特定step时，须指定为训练脚本中存在的step。step为list格式，可配置逐个step，例如：step=[0,1,2]。 | 否 | +**功能说明**：启动精度数据采集。在模型初始化之后的位置添加。需要与 stop 函数一起添加在 for 循环内。 -#### model配置代码示例 - -示例中定义了一个nn.Module类型的简单网络，在进行数据dump时使用原型函数PrecisionDebugger并传入config_path参数和model参数，其中model参数传入数据的类型为torch.nn.Module类型或torch.nn.Module子类型。 - -```python -#根据需要import包 -import os -import torch -import torch.nn as nn -import torch_npu -import torch.nn.functional as F -from msprobe.pytorch import PrecisionDebugger - -torch.npu.set_device("npu:0") -#定义一个简单的网络 -class ModuleOP(nn.Module): - def __init__(self) -> None: - super().__init__() - self.linear_1 = nn.Linear(in_features=8,out_features=4) - self.linear_2 = nn.Linear(in_features=4,out_features=2) - - def forward(self,x): - x1 = self.linear_1(x) - x2 = self.linear_2(x1) - r1 = F.relu(x2) - return r1 - -if __name__ == "__main__" - module = ModuleOP() - - #注册工具 - debugger = PrecisionDebugger('./config.json',model=module) - debugger.start() - x = torch.randn(10,8) - out = module(x) - loss = out.sum() - loss.backward() - debugger.stop() -``` - -### start函数 - -**功能说明** - -dump启动函数。 - -在模型初始化之后的位置添加。需要与stop函数一起添加在for循环内。 - -**原型** +**原型**： ```Python debugger.start() ``` -该函数为类函数，可以使用debugger.start()也可以使用PrecisionDebugger.start()。 - -### stop函数 +### 1.3 stop -**功能说明** +**功能说明**：停止精度数据采集。在 **start** 函数之后的任意位置添加。若需要 dump 反向数据，则需要添加在反向计算代码（如，loss.backward）之后。使用示例可参见 [2.1 采集 model 的精度数据](#21-采集-model-的精度数据)和 [2.2 采集完整的前反向数据](#22-采集完整的前反向数据)。 -dump停止函数。 - -在**start**函数之后的任意位置添加。若需要dump反向数据，则需要添加在反向计算代码（如loss.backward）之后。 - -**原型** +**原型**： ```Python debugger.stop() ``` -该函数为类函数，可以使用debugger.stop()也可以使用PrecisionDebugger.stop()。 - -### forward_backward_dump_end函数 +### 1.4 forward_backward_dump_end -**功能说明** +**功能说明**：停止精度数据采集。用于 dump 指定代码的前反向数据。在 **start** 函数之后，反向计算代码（如，loss.backward）之前的任意位置添加，可以采集 **start** 函数和该函数之间的前反向数据，可以通过调整 **start** 函数与该函数的位置，来指定需要 dump 的代码块。要求 **stop** 函数添加在反向计算代码（如，loss.backward）之后，此时该函数与 **stop** 函数之间的代码不会被 dump。使用示例可参见 [2.3 采集指定代码块的前反向数据](#23-采集指定代码块的前反向数据) -dump停止函数。用于dump指定代码的前反向数据。 +**原型**： -在**start**函数之后，反向计算代码（如loss.backward）之前的任意位置添加，可以dump **start**函数和该函数之间的前反向数据，可以通过调整**start**函数与该函数的位置，来指定需要dump的代码块。 +```Python +forward_backward_dump_end() +``` -要求**stop**函数添加在反向计算代码（如loss.backward）之后，此时该函数与**stop**函数之间的代码不会被dump。 +### 1.5 step -使用示例参见“**示例代码 > 扩展示例**”。 +**功能说明**：更新 dump 参数。在最后一个 **stop** 函数后或一个 step 结束的位置添加。需要与 **start** 函数一起添加在 for 循环内。 -**原型** +**原型**： ```Python -forward_backward_dump_end() +debugger.step() ``` -该函数为类函数，可以使用debugger.forward_backward_dump_end()也可以使用PrecisionDebugger.forward_backward_dump_end()。 +## 2 示例代码 -### step函数 +### 2.1 采集 model 的精度数据 -**功能说明** +这个示例定义了一个 nn.Module 类型的简单网络，在进行数据采集时使用原型函数 PrecisionDebugger 传入 config_path 参数和 model 参数。 -结束标识。 - -在最后一个**stop**函数后或一个step结束的位置添加。需要与start函数一起添加在for循环内。 - -**原型** +```python +# 根据需要import包 +import torch +import torch.nn as nn +import torch_npu # 需安装 torch_npu +import torch.nn.functional as F +from msprobe.pytorch import PrecisionDebugger -```Python -debugger.step() -``` -该函数为类函数，可以使用debugger.step()也可以使用PrecisionDebugger.step()。 +torch.npu.set_device("npu:0") +# 定义网络 +class ModuleOP(nn.Module): + def __init__(self) -> None: + super().__init__() + self.linear_1 = nn.Linear(in_features=8,out_features=4) + self.linear_2 = nn.Linear(in_features=4,out_features=2) -## 示例代码 + def forward(self,x): + x1 = self.linear_1(x) + x2 = self.linear_2(x1) + r1 = F.relu(x2) + return r1 -### 基础操作 +if __name__ == "__main__": + module = ModuleOP() + # 注册工具 + debugger = PrecisionDebugger('./config.json', model=module) + debugger.start() + x = torch.randn(10,8) + out = module(x) + loss = out.sum() + loss.backward() + debugger.stop() -如下示例可dump完整代码的前反向数据。 +``` +### 2.2 采集完整的前反向数据 ```Python from msprobe.pytorch import PrecisionDebugger # 请勿将PrecisionDebugger的初始化流程插入到循环代码中 debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path") - # 模型、损失函数的定义及初始化等操作 # ... - # 数据集迭代的位置一般为模型训练开始的位置 for data, label in data_loader: debugger.start() # 开启数据dump - # 如下是模型每个step执行的逻辑 output = model(data) #... loss.backward() - debugger.stop() # 关闭数据dump debugger.step() # 结束一个step的dump ``` -### 扩展示例 - -如下示例dump指定代码块前反向数据。 +### 2.3 采集指定代码块的前反向数据 ```Python from msprobe.pytorch import PrecisionDebugger @@ -181,26 +138,23 @@ debugger = PrecisionDebugger(config_path="./config.json", dump_path="./dump_path # 模型、损失函数的定义及初始化等操作 # ... - # 数据集迭代的位置一般为模型训练开始的位置 for data, label in data_loader: debugger.start() # 开启数据dump - # 如下是模型每个step执行的逻辑 output = model(data) debugger.forward_backward_dump_end() # 插入该函数到start函数之后，只dump start函数到该函数之间代码的前反向数据，本函数到stop函数之间的数据则不dump #... loss.backward() - debugger.stop() # 关闭数据dump debugger.step() # 结束一个step的dump ``` -## dump结果文件介绍 -训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。 -dump结果目录结构示例如下： +## 3 dump 结果文件介绍 + +训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。目录结构示例如下： ```Python ├── dump_path @@ -228,11 +182,11 @@ dump结果目录结构示例如下： │ ├── step2 ``` -dump过程中，pt文件在对应算子或者模块被执行后就会落盘，而json文件则需要在正常执行PrecisionDebugger.stop()后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关npy文件，可能会导致json文件中数据丢失。 +dump 过程中，pt 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。 -其中rank为设备上各卡的ID，每张卡上dump的数据会生成对应dump目录。非分布式场景下没有rank ID，目录名称为rank。 +其中 rank 为设备上各卡的 ID，每张卡上 dump 的数据会生成对应 dump 目录。非分布式场景下没有rank ID，目录名称为rank。 -pt文件保存的前缀和PyTorch对应关系如下： +pt 文件保存的前缀和 PyTorch 对应关系如下： | 前缀 | Torch模块 | | ----------- | ------------------- | @@ -243,18 +197,3 @@ pt文件保存的前缀和PyTorch对应关系如下： | VF | torch._VF | | Aten | torch.ops.aten | | Distributed | torch.distributed | - -## 工具支持的API列表 - -msprobe工具维护固定的API支持列表，若需要删除或增加dump的API，可以在msprobe/pytorch/hook_module/support_wrap_ops.yaml文件内手动修改，如下示例： - -```Python -functional: # functional为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API - - conv1d - - conv2d - - conv3d -``` - -# FAQ - -[FAQ](./FAQ.md) diff --git a/debug/accuracy_tools/msprobe/mindspore/doc/dump.md b/debug/accuracy_tools/msprobe/docs/06.data_dump_MindSpore.md similarity index 33% rename from debug/accuracy_tools/msprobe/mindspore/doc/dump.md rename to debug/accuracy_tools/msprobe/docs/06.data_dump_MindSpore.md index 1582b265d0635811041b69d7ddc0c2060562d18f..cad25d98410f7e885a21d89f3128f8ef61ff0f86 100644 --- a/debug/accuracy_tools/msprobe/mindspore/doc/dump.md +++ b/debug/accuracy_tools/msprobe/docs/06.data_dump_MindSpore.md @@ -1,94 +1,66 @@ -# **精度数据采集** +# MindSpore 场景下的精度数据采集 -msprobe工具主要通过在训练脚本内添加dump接口并启动训练的方式来采集精度数据。 +msprobe 工具主要通过在训练脚本内添加 dump 接口、启动训练的方式采集精度数据。 -执行dump操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 +本工具提供固定的 API 支持列表，若需要删除或增加 dump 的 API，可以在 msprobe/mindspore/dump/hook_cell/support_wrap_ops.yaml 文件内手动修改，如下示例： -## dump接口介绍 - -### PrecisionDebugger +```yaml +ops: # ops为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API + - adaptive_avg_pool1d + - adaptive_avg_pool2d + - adaptive_avg_pool3d +``` -**功能说明** +## 1 接口介绍 -通过加载dump配置文件的方式来确定dump操作的详细配置。 +### 1.1 PrecisionDebugger -PrecisionDebugger可以在from msprobe.mindspore import PrecisionDebugger之后的位置添加。详细使用可参考“**示例代码**”。 +**功能说明**：通过加载 dump 配置文件的方式来确定 dump 操作的详细配置。 -**原型** +**原型**： ```Python PrecisionDebugger(config_path=None) ``` -**参数说明** +**\***： +1. config_path：指定 dump 配置文件路径，string 类型。参数示例："./config.json"。未配置该路径时，默认使用 [config.json](../config.json) 文件的默认配置。 -| 参数名 | 说明 | 是否必选 | -| ----------- | ------------------------------------------------------------ | -------- | -| config_path | 指定dump配置文件路径，String类型。参数示例："./config.json"。未配置该路径时，默认使用[config.json](../../config)文件的默认配置。config.json文件可以配置更多参数，若需要进行更多场景的精度数据dump，建议配置[config.json](../../config/config.json)文件。config.json文件的配置可参考《[配置文件说明](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/config/README.md)》。 | 否 | +### 1.2 start -### start函数 +**功能说明**：启动精度数据采集。在模型初始化之后的位置添加。需要与 stop 函数一起添加在 for 循环内。 -**功能说明** - -启动函数。 - -在模型初始化之后的位置添加。需要与stop函数一起添加在for循环内。 - -**原型** +**原型**： ```Python -debugger.start(model = None) +debugger.start(model=None) ``` +**\***： +1. model：指具体的 mindspore.nn.Cell，默认未配置，L1 级别下传入 model 可以采集 primitive op。 -该函数为类函数，可以使用debugger.start(model = None)也可以使用PrecisionDebugger.start(model = None) - - -**参数说明** +### 1.3 stop -| 参数名 | 说明 | 是否必选 | -| ----------- |---------------------------------------------------------------------------------------| -------- | -| model | 指具体的mindspore.nn.Cell，默认未配置，L1级别下传入model可以使能对primitive op的dump，否则无法dump primitive op。 | 否 | +**功能说明**：停止数据采集。在 **start** 函数之后的任意位置添加。需要与 start 函数一起添加在 for 循环内。若需要 dump 反向数据，则需要添加在反向计算代码之后。**仅 MindSpore 动态图场景支持。** - -### stop函数 - -**功能说明** - -dump停止函数。 - -在**start**函数之后的任意位置添加。需要与start函数一起添加在for循环内。若需要dump反向数据，则需要添加在反向计算代码之后。 - -仅MindSpore动态图场景支持。 - -**原型** +**原型**： ```Python debugger.stop() ``` -该函数为类函数，可以使用debugger.stop()也可以使用PrecisionDebugger.stop()。 - -### step函数 - -**功能说明** - -结束标识。 - -在最后一个**stop**函数后或一个step结束的位置添加。 +### 1.4 step -仅MindSpore动态图场景支持。 +**功能说明**：在最后一个 **stop** 函数后或一个 step 结束的位置添加。**仅 MindSpore 动态图场景支持。** -**原型** +**原型**： ```Python debugger.step() ``` -该函数为类函数，可以使用debugger.step()也可以使用PrecisionDebugger.step()。 +## 2 示例代码 -## 示例代码 - -### MindSpore静态图场景 +### 2.1 MindSpore 静态图场景 ```Python from msprobe.mindspore import PrecisionDebugger @@ -99,9 +71,7 @@ debugger.start() ... ``` -### MindSpore动态图场景 - -当使用模型使用for循环时，在每个迭代的开始插入debugger.start()，在每个迭代的结束插入debugger.stop()与debugger.step()： +### 2.2 MindSpore 动态图场景 ```Python import mindspore as ms @@ -124,40 +94,25 @@ for data, label in data_loader: debugger.step() # 结束一个step的dump ``` -当使用模型的train方法而非for循环时，可以通过在callbacks参数中传入MsprobeStep(debugger)： - -```Python -from msprobe.mindspore.common.utils import MsprobeStep -from msprobe.mindspore import PrecisionDebugger - -# 初始化PrecisionDebugger -debugger = PrecisionDebugger(config_path="./config.json") - -# 自动在每个step开始时调用start()，在每个step结束时调用stop()和step()。 -# 这意味着您无需手动在循环内添加start、stop和step函数，框架会自动完成数据的dump操作。 -trainer.train(1, dataset_train, callbacks=[loss_monior, MsprobeStep(debugger)]) - -``` - -## dump结果文件介绍 +## 3 dump 结果文件介绍 -### MindSpore静态图场景 +### 3.1 MindSpore 静态图场景 -训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。 +训练结束后，工具将 dump 的数据保存在 dump_path 参数指定的目录下。 -- jit_level为O0/O1时 +- jit_level 为O0/O1时： - dump结果目录请参见MindSpore官网中的《[同步Dump数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%90%8C%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)》。 + dump 结果目录请参见 MindSpore 官网中的[同步 Dump 数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%90%8C%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)。 -- jit_level为O2时 +- jit_level 为O2时： - dump结果目录请参见MindSpore官网中的《[异步Dump数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%BC%82%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)》。 + dump 结果目录请参见 MindSpore 官网中的[异步 Dump 数据对象目录](https://www.mindspore.cn/tutorials/experts/zh-CN/r2.3.0rc2/debug/dump.html#%E5%BC%82%E6%AD%A5dump%E6%95%B0%E6%8D%AE%E5%AF%B9%E8%B1%A1%E7%9B%AE%E5%BD%95)。 -jit_level请参见[mindspore.set_context](https://www.mindspore.cn/docs/zh-CN/r2.3.0/api_python/mindspore/mindspore.JitConfig.html#mindspore-jitconfig)配置jit_config。 +jit_level 请参见 [mindspore.set_context](https://www.mindspore.cn/docs/zh-CN/r2.3.0/api_python/mindspore/mindspore.JitConfig.html#mindspore-jitconfig) 配置 jit_config。 -### MindSpore动态图场景 +### 3.2 MindSpore 动态图场景 -训练结束后，工具将dump的数据保存在dump_path参数指定的目录下。 +训练结束后，工具将 dump 的数据保存在dump_path参数指定的目录下。 dump结果目录结构示例如下： @@ -169,9 +124,8 @@ dump结果目录结构示例如下： | | | | ├── MintFunctional.relu.0.backward.input.0.npy | | | | ├── Mint.abs.0.forward.input.0.npy | | | | ├── Functional.split.0.forward.input.0.npy -| | | | ├── Tensor.__add__.0.forward.output.0.npy | | | | ... -| | | | └── Jit.AlexNet.0.forward.input.0.npy +| | | | └── Tensor.__add__.0.forward.output.0.npy │ | | ├── dump.json # 保存前反向算子、算子的统计量信息或溢出算子信息。包含dump数据的API名称（命名格式为：`{api_type}_{api_name}_{API调用次数}_{前向反向}_{input/output}.{参数序号}`）、dtype、 shape、各数据的max、min、mean、L2norm统计信息以及当配置summary_mode="md5"时的md5数据。其中，“参数序号”表示该API下的第n个参数，例如1，则为第一个参数，若该参数为list格式，则根据list继续排序，例如1.1，表示该API的第1个参数的第1个子参数；L2norm表示L2范数（平方根） │ | | ├── stack.json # 算子调用栈信息 │ | | └── construct.json # 分层分级结构，level为L1时，construct.json内容为空 @@ -189,30 +143,15 @@ dump结果目录结构示例如下： │ ├── step2 ``` -dump过程中，npy文件在对应算子或者模块被执行后就会落盘，而json文件则需要在正常执行PrecisionDebugger.stop()后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关npy文件，可能会导致json文件中数据丢失。 +dump 过程中，npy 文件在对应算子或者模块被执行后就会落盘，而 json 文件则需要在正常执行 PrecisionDebugger.stop() 后才会写入完整数据，异常的程序终止会保存终止前被执行算子的相关 npy 文件，可能会导致 json 文件中数据丢失。 -其中rank为设备上各卡的ID，每张卡上dump的数据会生成对应dump目录。非分布式场景下没有rank ID，目录名称为rank。 +其中 rank 为设备上各卡的 ID，每张卡上 dump 的数据会生成对应 dump 目录。非分布式场景下没有 rank ID，目录名称为 rank。 -动态图场景下使能PSJit或PIJit，装饰特定Cell或function，被装饰的部分会全部/部分使能静态图流程。PSJit场景下config.json文件配置level为L1时，被PSJit装饰的部分也作为API被dump到对应目录；若配置level为L2时，则只会dump用户网络中静态图流程下的相关kernel。PIJit场景开启dump工具后，会被还原为动态图，按API粒度进行dump。 +npy 文件保存的前缀和 MindSpore 对应关系如下： -npy文件保存的前缀和MindSpore对应关系如下： - -| 前缀 | MindSpore模块 | +| 前缀 | MindSpore 模块 | | -------------- | ---------------------------- | | Tensor | mindspore.Tensor | | Functional | mindspore.ops | -| Primitive | mindspore.ops.Primitive | | Mint | mindspore.mint | | MintFunctional | mindspore.mint.nn.functional | -| Jit | mindspore.jit | - -## 工具支持的API列表 - -msprobe工具维护固定的API支持列表，若需要删除或增加dump的API，可以在msprobe/mindspore/dump/hook_cell/support_wrap_ops.yaml文件内手动修改，如下示例： - -```bash -ops: # ops为算子类别，找到对应的类别，在该类别下按照下列格式删除或添加API - - adaptive_avg_pool1d - - adaptive_avg_pool2d - - adaptive_avg_pool3d -``` diff --git a/debug/accuracy_tools/msprobe/docs/07.accuracy_checker_PyTorch.md b/debug/accuracy_tools/msprobe/docs/07.accuracy_checker_PyTorch.md new file mode 100644 index 0000000000000000000000000000000000000000..72fb01e2edc04d4e73ec899894c256f840319d2f --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/07.accuracy_checker_PyTorch.md @@ -0,0 +1,278 @@ +# PyTorch 场景的离线精度预检 + +## 1 简介 + +**PyTorch 离线精度预检**\*1通过扫描昇腾 NPU 上用户训练模型中的所有 API，输出模型精度的诊断和分析结果。具体而言，该工具通过采集模型中所有 API 的前反向信息，构造相应的单元测试，将 NPU 输出与标杆（CPU 高精度）比对，从而计算对应的精度指标，该过程已封装为 run_ut.py 函数；将 NPU 环境下采集的预检数据拷贝至 GPU 环境，同样执行 run_ut.py；最后通过**新精度标准比对法**\*2将 NPU 和 GPU 的预检结果进行比对，从而找出 NPU 中存在精度问题的 API。同时，本工具支持随机生成模式和真实数据模式\*3。 + +**\***： + +1. 支持 PyTorch 版本：1.11/2.0/2.1/2.2； +2. 依据新精度标准，对不同的API采取不同的比对算法（包括绝对阈值法，标杆比对法、二进制一致法、ULP误差比对法和双千指标法），最终给定预检判定结果； +3. 在预检 dump 时可以选择由工具构造随机数获得 dump 数据或选择真实输入的数据进行预检 dump 操作。随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。 + +## 2 离线预检流程 + +1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。 +2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。注意需要配置 level="L1"。 +3. 将 NPU 环境下 dump 的预检数据拷贝至 GPU 环境。 +4. 在 NPU 和 GPU 环境下分别执行 run_ut.py，生成的结果最终用于 api_precision_compare.py 函数的输入。详见 [3 离线预检操作指导](#3-离线预检操作指导)。 +5. 将 NPU 和 GPU 执行 run_ut.py 生成的 `accuracy_checking_details_{timestamp}.csv` 结果文件拷贝至同一环境下。 +6. 运行 api_precision_compare.py，输出结果为预检操作的最终结果。详见 [5 预检结果比对](#5-预检结果比对)章节。 + +## 3 离线预检操作指导 + +完成预检数据采集后，仅仅获取了 API 的输入数据，为了得到 NPU vs. CPU 高精度（标杆）的预检比对结果和 GPU vs. CPU 高精度（标杆）的预检比对结果，还需要进行 run_ut 操作。 + +run_ut 预检操作包括以下两种方式： + +- 使用 run_ut.py 执行预检：适用于数据量较小的单卡场景。 +- 使用 multi_run_ut.py 执行多线程预检：适用于数据量较大的大模型场景。 + +### 3.1 使用 run_ut.py 执行预检 + +将 API 信息输入到 run_ut 模块进行精度检测并比对，运行如下命令： + +```bash +msprobe -f pytorch run_ut -api_info ./dump.json +``` + + | 参数名称 | 解释 | 是否必选 | + | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- | + | -api_info 或 --api_info_file | 指定 API 信息文件 dump.json。 | 是 | + | -save_error_data | 保存精度未达标的 API 输入输出数据。 | 否 | + | -o 或 --out_path | 指定 run_ut 执行结果存盘路径，默认“./”（相对于 run_ut 的路径）。 | 否 | + | | | | + | -j 或 --jit_compile | 开启 jit 编译。 | 否 | + | -d 或 --device | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0。 | 否 | + | -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | run_ut 操作中断后继续执行场景下必须配置 | + | -f 或 --filter_api | 过滤模型中除最大值和最小值以外其他参数和结构相同的 API。适用于模型较大且重复 API 较多的场景。 | 否 | + | -config 或 --config_path | 指定离线预检操作过程中额外配置（包括黑名单、白名单等）的 [config.json](../config.json) 文件，默认未配置。config.json 文件的配置可参考[配置文件介绍](./02.config_introduction.md)。 | 否 | + +run_ut 执行结果包括 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 两个文件。`accuracy_checking_result_{timestamp}.csv` 属于 API 级，标明每个 API 是否通过测试。建议用户先查看 `accuracy_checking_result_{timestamp}.csv` 文件，对于其中没有通过测试的或者特定感兴趣的 API，根据其 API name 字段在 `accuracy_checking_details_{timestamp}.csv` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见[ 4 预检结果](#4-预检结果)。 + +如果需要保存比对不达标的输入和输出数据，可以在 run_ut 执行命令结尾添加 `-save_error_data`，例如： + +```bash +msprobe -f pytorch run_ut -api_info ./dump.json -save_error_data +``` + +数据默认会存盘到 './ut_error_data{timestamp}' 路径下（相对于启动 run_ut 的路径），如有需要，用户可以通过 error_data_path 参数来配置保存路径，error_data_path 参数在 [config.json](../config.json) 文件或 [config.yaml](../pytorch/api_accuracy_checker/config.yaml) 文件配置，config.json 文件需要在 run_ut 操作时通过 -config 参数指定，config.yaml 文件详见\*1。 + +**\***： + +1. config.yaml 文件说明 + + config.yaml 文件可以通过配置参数来控制 dump 和 run_ut 操作的白名单、黑名单等功能。操作步骤如下： + + - config.yaml 文件通常位于类似 /home/xxx/miniconda3/envs/xxx/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml 的路径中。 + + - 进入 config.yaml 文件 + + ```bash + vim /home/xxx/miniconda3/envs/xxx/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml + ``` + + - 修改 config.yaml 文件参数。 + + ```yaml + white_list: [] + black_list: [] + error_data_path: './' + precision: 14 + ``` + + | 参数名称 | 解释 | 是否必选 | + | ----------- | -----------| -------- | + | white_list | API dump 白名单，仅对指定的 API 进行 dump。
**参数示例**：white_list=["conv1d", "conv2d"]。默认未配置白名单，即 dump 全量 API 数据。 | 否 | + | black_list | API dump 黑名单，被指定的 API 不进行 dump。
**参数示例**：black_list=["conv1d", "conv2d"]。默认未配置黑名单，即 dump 全量 API 数据。 | 否 | + | error_data_path | 配置保存精度未达标的 API 输入输出数据路径。
**参数示例**："error_data_path": "./"。默认为当前路径。 | 否 | + | precision | 浮点数表示位数，默认取小数点后14位。 | 否 | + + 说明：white_list 和 black_list 同时配置时，二者配置的 API 名单若无交集，则白名单生效，若 API 名单存在交集，则白名单排除的部分以及交集的 API 不进行 dump。 + +2. API 预检黑名单和白名单 + + run_ut 过程支持 API 预检黑名单和白名单，通过如下文件配置 black_list（黑名单）或white_list（白名单）参数来指定不需要或需要预检的API名称： + + - 配置 [config.json](../config.json) 文件，该文件需要在 run_ut 操作时通过 -config 参数指定。 + + - config.json 文件的优先级高于 config.yaml 文件，即执行 config.json 文件时，config.yaml 文件的配置不生效。 + +### 3.2 使用 multi_run_ut.py 执行多线程预检 + +multi_run_ut.py 脚本，可以并行执行多个 run_ut 操作，从而减少预检耗时。示例如下： + +```bash +msprobe -f pytorch multi_run_ut -api_info ./dump.json -n 32 -d 0 1 2 3 +``` + +| 参数名称 | 解释 | 是否必选 | +| ---------------------------- | ------------------------------------------------------------ | ---------------------------------- | +| -api_info 或 --api_info_file | 指定 API 信息文件 dump.json。 | 是 | +| -save_error_data | 保存精度未达标的 API 输入输出数据。 | 否 | +| -o 或 --out_path | 指定 run_ut 执行结果存盘路径，默认“./”（相对于 run_ut 的路径）。 | 否 | +| -j 或 --jit_compile | 开启 jit 编译。 | 否 | +| -n | 同时执行 run_ut 线程的数量，默认为 8，最大支持 64，但每个 Device 最大支持 8 个线程。当指定多个线程和多个 Device 时，线程数在每张卡上均分。 | 否 | +| -d 或 --device | 指定 Device ID，选择 UT 代码运行所在的卡，默认值为 0，支持同时指定 0~7，共 8 个 Device。 | 否 | +| -csv_path 或 --result_csv_path | 指定本次运行中断时生成的 `accuracy_checking_result_{timestamp}.csv` 文件路径，执行 run_ut 中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的 `accuracy_checking_result_{timestamp}.csv` 文件。详见 [3.3 断点续检](#33-断点续检)。 | run_ut 操作中断后继续执行场景下必须配置 | +| -f 或 --filter_api | 过滤模型中除最大值和最小值以外其他参数和结构相同的 API。适用于模型较大且重复 API 较多的场景。 | 否 | + +### 3.3 断点续检 + +断点续检操作通过如下命令执行： + +```bash +msprobe -f pytorch run_ut -api_info ./dump.json -csv_path /home/xxx/ut/accuracy_checking_result_{timestamp}.csv +``` + +精度预检 run_ut 过程中，若因环境、数据量过大等原因导致预检进程中断，那么当用户解决这些问题后，重新执行 run_ut 操作，可以通过断点续检操作继续前面未完成的预检，会在 -csv_path 指定的 `accuracy_checking_result_{timestamp}.csv` 文件以及对应的 `accuracy_checking_details_{timestamp}.csv` 文件中继续写入后续的结果，不会重新创建结果文件。 + +须指定为上次预检中断的 `accuracy_checking_result_{timestamp}.csv` 文件。请勿修改 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件名，包括时间戳，否则断点续检会因无法识别到文件名而失败。 + +## 4 预检结果 + +精度预检生成的 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件示例如下： + +可以通过先查看 `accuracy_checking_result_{timestamp}.csv` 文件的 Forward Test Success 和 Backward Test Success，判断是否存在未通过测试的 API，再查看 `accuracy_checking_details_{timestamp}.csv` 文件的 API 详细达标情况，API 达标情况介绍请参见\*1。 + +`accuracy_checking_result_{timestamp}.csv` + +![accuracy_checking_result](img/accuracy_checking_result.png) + +| 字段 | 含义 | +| --------------------- | ------------------------- | +| API name | API 名称。 | +| Forward Test Success | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误。 | +| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，如果是空白的话代表该 API 没有反向输出。 | +| Message | 提示信息。 | + +该结果为中间结果，仅作为参考，建议完成 [5 预检结果比对](#5-预检结果比对)后查看比对结果。该结果后续将会删除。 + +Forward Test Success 和 Backward Test Success 是否通过测试是由 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差、双百双千双万指标判定结果决定的。 + +需要注意的是 `accuracy_checking_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `accuracy_checking_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error，仅存在 waring 和 pass 且不存在 error 则标记 waring。 + +`accuracy_checking_details_{timestamp}.csv` + +![accuracy_checking_details](img/accuracy_checking_details.png) + +| 字段 | 含义 | +| ------------------- | ------------------------------------------------------------ | +| API name | NPU 或 GPU下的 API 名称。 | +| Bench Dtype | 标杆数据的 API 数据类型。 | +| DEVICE Dtype | NPU 或 GPU 数据的 API 数据类型。 | +| Shape | API 的 Shape信息。 | +| 余弦相似度 | NPU 或 GPU 数据与标杆数据的余弦相似度。 | +| 最大绝对误差 | NPU 或 GPU 数据与标杆数据的最大绝对误差。 | +| 双百指标 | 双百精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于百分之一的个数占总元素个数的比例。测试通过标准为相对误差大于百分之一的个数占总元素个数的比例小于百分之一。 | +| 双千指标 | 双千精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。 | +| 双万指标 | 双万精度指标。是指 NPU 或 GPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于万分之一的个数占总元素个数的比例。测试通过标准为相对误差大于万分之一的个数占总元素个数的比例小于万分之一。 | +| 二进制一致错误率 | NPU 或 GPU 数据中每个 Tensor 精度不一致的数值的数量与 Tensor 中数值数量的比值。只有数据是 builtin 类型（bool、int、float、str）、torch.bool 和 torch 的 int 类型或者在新精度标准中使用二进制一致算法进行比对的 API 才会展示。 | +| 误差均衡性 | NPU 或 GPU 数据与标杆数据精度差的上下浮动情况。 | +| 均方根误差 | NPU 或 GPU 数据与标杆数据的均方根误差。 | +| 小值域错误占比 | NPU 或 GPU Tensor 中与标杆的绝对误差大于错误阈值的小值在小值域（小值的总数量）中的占比。判断为小值以及绝对误差的错误阈值参见\*2。 | +| 相对误差最大值 | NPU 或 GPU 数据与标杆数据相对误差的最大值。 | +| 相对误差平均值 | NPU 或 GPU 数据与标杆数据相对误差的平均值。 | +| inf/nan 错误率 | NPU 与标杆 inf/nan 计算不一致的元素个数占总元素的个数比例。 | +| 相对误差错误率 | NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。 | +| 绝对误差错误率 | NPU 与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。 | +| ULP 误差最大值 | NPU 或 GPU 数据与标杆数据 ULP 误差的最大值（取绝对值后）。 | +| ULP 误差平均值 | NPU 或 GPU 数据与标杆数据ULP误差的平均值（取绝对值后）。 | +| ULP 误差大于阈值占比 | NPU 或 GPU 数据与标杆数据的 ULP 误差（取绝对值后）大于阈值（当 NPU 或 GPU 数据类型为 float16 或 bfloat16 时，阈值为 1；当 NPU 或 GPU 数据类型为 float32 时，阈值为 32）的元素个数占总元素的个数比例。 | +| Status | API 预检通过状态，pass 表示通过测试，error 表示未通过，warning 表示测试未通过双千或双万精度指标，SKIP 表示该 API 的某个参数的反向不要计算梯度，所以没有任何计算过程，其他信息均为空。 | +| message | 提示信息。 | + +**\***： + +1. API 预检指标： + + API 预检指标是通过对 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差双百、双千、双万精度指标的数值进行判断，得出该 API 是否符合精度标准的参考指标。 + + API预检通过测试，则在`accuracy_checking_details_{timestamp}.csv`文件中的 Status 列标记 pass，否则标记 error 或 warning，详细规则如下： + + - 余弦相似度 > 0.99：≤ 0.99 为不达标，标记 error，> 0.99 达标，进行下一步； + - 最大绝对误差 ＜ 0.001：＜ 0.001 达标，标记 pass，≥ 0.001 为不达标，进行下一步； + - 双百、双千、双万精度指标： + + 对于 float16 和 bfloat16 数据：双百指标不通过，标记 error；双百指标通过，双千指标不通过，标记 warning；双百、双千指标均通过，标记 pass。 + + 对于 float32 和 float64 数据：双千指标不通过，标记 error；双千指标通过，双万指标不通过，标记 warning；双千、双万指标均通过，标记 pass。 + - 在 `accuracy_checking_result_{timestamp}.csv` 中以 Forward Test Success 和 Backward Test Success 字段统计该算子前向反向输出的测试结果，对于标记 pass 的算子，则在 `accuracy_checking_result_{timestamp}.csv` 中标记 TRUE 表示测试通过，对于标记 error 或 warning 的算子，则在 `accuracy_checking_result_{timestamp}.csv` 中标记 FALSE 表示测试不通过。由于一个算子可能有多个前向或反向的输入或输出，那么该类算子的输入或输出中必须全为 pass，才能在 `accuracy_checking_result_{timestamp}.csv` 中标记 TRUE，只要有一个输入或输出标记 error 或 warning，那么在`accuracy_checking_result_{timestamp}.csv`中标记 FALSE。 + +2. 小值域阈值： + + 判定为小值的阈值： + + - torch.float32：e-6 + - torch.float16：e-3 + - torch.bfloat16：e-3 + + 小值域的绝对误差阈值： + + - torch.float32：e-9 + - torch.float16：e-5 + - torch.bfloat16：e-5 + +## 5 预检结果比对 + +需要同时获取 NPU 和 GPU 环境下 run_ut 操作的预检结果 `accuracy_checking_details_{timestamp}.csv` 文件。执行如下命令进行 NPU 和 GPU 预检结果的比对： + +```bash +msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_details_{timestamp}.csv -gpu /home/xxx/gpu/accuracy_checking_details_{timestamp}.csv -o /home/xxx/ +``` + +| 参数名称 | 说明 | 是否必选 | +| -------------------- | ------------- | -------- | +| -npu 或 --npu_csv_path | NPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否 | +| -gpu 或 --gpu_csv_path | GPU 预检结果 `accuracy_checking_details_{timestamp}.csv` 文件路径。默认从当前目录下识别该文件。 | 否 | +| -o 或 --out_path | 指定 api_precision_compare.py 执行结果存盘路径，默认为当前目录。 | 否 | + +执行完成后输出 `api_precision_compare_result_{timestamp}.csv` 和 `api_precision_compare_details_{timestamp}.csv` 文件。文件示例如下： + +可以通过先查看 `api_precision_compare_result_{timestamp}.csv` 文件的 Forward Test Success 和 Backward Test Success，判断是否存在未通过测试的 API，再查看 `api_precision_compare_details_{timestamp}.csv` 文件的 API 详细达标情况。 + +`api_precision_compare_result_{timestamp}.csv` + +![api_precision_compare_result](img/api_precision_compare_result.png) + +| 字段 | 含义 | +| --------------------- | ------------------------------------------------------------ | +| API name | API 名称。 | +| Forward Test Success | 前向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，skip 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 | +| Backward Test Success | 反向 API 是否通过测试，pass 为通过，warning 为待观察，error 为错误，如果是空白的话代表该 API 没有反向输出，skip 表示该 API 的数据类型不支持使用新精度标准进行比对，如 float64。 | +| Message | 提示信息。 | + +Forward Test Success 和 Backward Test Success 是否通过测试是由 `api_precision_compare_details_{timestamp}.csv` 中的各个指标判定结果决定的。需要注意的是 `api_precision_compare_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `api_precision_compare_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error，仅存在 warning 和 pass 且不存在 error 标记 warning。 + +`api_precision_compare_details_{timestamp}.csv` + +![api_precision_compare_details](img/api_precision_compare_details.png) + +| 字段 | 含义 | +| ------------------------ | ------------------------------------------------------------ | +| API name | NPU 或 GPU 下的 API 名称。 | +| 小值域错误比值 | NPU 与 CPU 的小值域的错误比率 / GPU 与 CPU 的小值域的错误比率。标杆比对法指标。 | +| 小值域错误判定结果 | 小值域错误比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。 | +| 均方根误差比值 | NPU 与 CPU 的均方根误差 / GPU 与 CPU 的均方根误差。标杆比对法指标。 | +| 均方根误差判定结果 | 均方根误差比值小于等于 1 标记为 pass，1~2 之间标记为 waring，大于 2 标记为 error。 | +| 相对误差最大值比值 | NPU 与 CPU 的相对误差最大值 / GPU 与 CPU 的相对误差最大值。标杆比对法指标。 | +| 相对误差最大值判定结果 | 相对误差最大值比值小于等于 1 标记为 pass，1 ~ 10 之间标记为 waring，大于 10 标记为 error。 | +| 相对误差平均值比值 | NPU 与 CPU 的相对误差的平均值 / GPU 与 CPU 的相对误差的平均值。标杆比对法指标。 | +| 相对误差平均值判定结果 | 相对误差平均值比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。 | +| 误差均衡性比值 | NPU 与 CPU 的误差均衡性 / GPU 与 CPU 的误差均衡性。标杆比对法指标。 | +| 误差均衡性判定结果 | 误差均衡性比值小于等于 1 标记为 pass，1 ~ 2 之间标记为 waring，大于 2 标记为 error。该字段暂不参与 api_precision_compare_result 的结果判定。 | +| inf / nan 错误率 | NPU 与标杆 inf / nan 计算不一致的元素个数占总元素的个数比例。绝对阈值法指标。 | +| inf / nan 判定结果 | inf / nan 错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 | +| 相对误差错误率 | NPU 与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。绝对阈值法指标。 | +| 相对误差判定结果 | 相对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 | +| 绝对误差错误率 | NPU 与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。绝对阈值法指标。 | +| 绝对误差判定结果 | 绝对误差错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 | +| 二进制一致错误率 | NPU 或 GPU 数据中每个 Tensor 精度不一致的数值的数量与 Tensor 中数值数量的比值。只有数据是 builtin 类型（bool、int、float、str）、torch.bool 和 torch 的 int 类型或者在新精度标准中使用二进制一致算法进行比对的 API 才会展示。二进制一致法指标。 | +| 二进制一致错误率判定结果 | 二进制一致错误率判定结果，等于 0 标记为 pass，其余情况标记为 error。 | +| ULP 误差平均值 | NPU 数据与标杆数据 ULP 误差的平均值（取绝对值后）。ULP 误差比对法指标。 | +| ULP 误差大于阈值占比 | NPU 数据与标杆数据的 ULP 误差（取绝对值后）大于阈值（当 NPU 数据类型为 float16 或 bfloat16 时，阈值为 1；当 NPU 数据类型为 float32 时，阈值为 32）的元素个数占总元素的个数比例。ULP 误差比对法指标。 | +| ULP 误差大于阈值占比比值 | NPU 与 CPU 的 ULP 误差大于阈值占比 / GPU 与 CPU 的 ULP 误差大于阈值占比。ULP 误差比对法指标。 | +| ULP 误差判定结果 | ULP 误差判定结果。
当 NPU 或 GPU 数据类型是 float16 或 bfloat16 时，以下两条标准满足其一标记为 pass，否则标记为 error：
NPU ULP 误差大于阈值占比小于 0.001；
NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。
当 NPU 或 GPU 数据类型是 float32 时，以下三条标准满足其一标记为 pass，否则标记为 error：
NPU ULP 误差平均值小于 64；
NPU ULP 误差大于阈值占比小于 0.05；
NPU ULP 误差大于阈值占比小于 GPU ULP 误差大于阈值占比。 | +| 双千指标 | 双千精度指标。是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。仅 conv1d 和 conv2d 使用该指标。双千指标法指标。 | +| 双千指标判定结果 | 双千指标判定结果。双千指标大于 0.999 标记为 pass，否则标记为 error。 | +| 比对结果 | 综合所有指标的最终结果。如果比对指标中有 error，则标记为 error；有 warning，则标记为 warning；否则标记为 pass。 | +| 比对算法 | API 使用的比对算法，为标杆比对法、二进制一致法、绝对阈值法和 ULP 误差比对法中的一种。 | +| Message | 提示信息。当前提示该 API 比对结果为 error 或 warning 时对应不符合标准的指标。 | diff --git a/debug/accuracy_tools/msprobe/docs/08.accuracy_checker_online_Pytorch.md b/debug/accuracy_tools/msprobe/docs/08.accuracy_checker_online_Pytorch.md new file mode 100644 index 0000000000000000000000000000000000000000..b643dc69cd216fd960c44b74bbc78e28c869ec1b --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/08.accuracy_checker_online_Pytorch.md @@ -0,0 +1,182 @@ +# PyTorch 场景的在线精度预检 + +## 1 简介 + +为了应对大模型场景下，通过离线预检方式 dump API 输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行 NPU 训练操作的过程中，通过 TCP/IP 协议在 NPU +Host 与 GPU Host 设备间建立连接，将 NPU 上对应 API 的输入数据在 GPU 设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据 dump 的步骤，降低存储资源的占用。 + +## 2 在线精度预检流程 + +在线精度预检当前支持**局域网场景**和**共享存储场景**，请根据不同的场景选择对应的配置。 + +在线精度预检操作流程如下： + +1. 准备 GPU 和 NPU 可正常运行的训练环境，PyTorch 版本大于等于2.0，并保证两台 Host 在同一局域网内可正常通信或能通过共享存储进行通信。 +2. GPU 和 NPU Host 设备上同时安装msprobe工具，详见[ msprobe 安装](./01.installation.md)章节，其中在线预检要安装 twisted、pyOpenSSL，这些包为 Python 模块。 +3. 分别配置 GPU 侧、NPU 侧的 config.json 文件。 +4. 在 GPU 侧运行 `msprobe -f pytorch run_ut -config ./config.json`。 +5. 在 NPU 侧配置训练脚本。 +6. 在 NPU 侧执行训练。 + +## 3 在线精度预检操作指导 + +### 3.1 配置 config.json 文件 + +预检工具安装完成后，需要在 GPU 和 NPU 环境下分别配置 config.json。其中需要重点关注文件中的 is_online、is_benchmark_device、host 和 port 参数的配置，保障在线预检时 GPU 和 NPU 两台设备间的通信正常。 + +#### 3.1.1 GPU 侧在线预检配置说明 + +| 参数名称 | 说明 | 是否必选 | +|-----------------|--------------|------| +| task | 任务名称，str 类型，配置为 run_ut 表示预检任务。通过其他字段 is_online 判断离线预检、在线预检任务。 | 是 | +| white_list | 预检的 API 白名单，list[str] 类型。
**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置白名单，即预检全量 API 数据。 | 否 | +| black_list | 预检的 API 黑名单，list[str] 类型。
**配置示例**：white_list=["conv1d", "conv2d"]。默认未配置黑名单，即预检全量 API 数据。 | 否 | +| error_data_path | 配置保存精度未达标的 API 输入输出数据路径，str 类型。在线预检模式下该参数不生效。 | 否 | +| is_online | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。 | 是 | +| nfs_path | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效。 | 否 | +| host | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机地址 127.0.0.1 或本机局域网 IP。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 | +| port | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，GPU 侧配置为本机可用端口。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 | +| rank_list | 指定在线预检的 Rank ID，默认值为 [0]，list[int] 类型，应配置为大于等于 0 的整数，且须根据实际卡的 Rank ID 配置，若所配置的值大于实际训练所运行的卡的 Rank ID，则在线预检输出数据为空。GPU 和 NPU 须配置一致。 | 是 | + +#### 3.1.2 NPU 侧在线预检配置说明 + +| 参数名称 | 说明 | 是否必选 | +|------------------|-------------|------| +| task | 任务名称，str 类型，配置为 tensor 表示 dump API 统计信息和完全复刻整网的 API 运行情况的真实数据。通过字段 online_run_ut 判断是否使用在线预检功能。 | 是 | +| dump_path | dump 路径，str 类型，配置为合法路径即可，兼容 tensor 任务静态检查。 | 是 | +| level | dump 级别，str 类型，在线预检时配置为 L1，表示 dump API 级精度数据。在线预检可不配置，默认取值 L1。 | 是 | +| rank | 指定对某张卡上的数据进行 dump，list[int] 类型，默认未配置(表示 dump所有卡的数据)，需要与 GPU 侧配置项 rank_list 保持一致。 | 否 | +| step | 指定 dump 某个 step 的数据，list[int] 类型，默认未配置，表示 dump 所有 step 的数据。dump 特定 step 时，须指定为训练脚本中存在的 step。 | 否 | +| seed | 随机种子数，int 类型，默认值为 1234。通过固定随机数保证模型的输入或输出一致。 | 否 | +| is_deterministic | 确定性计算模式，bool 类型，可取值 true（开启）或 false（关闭），默认关闭。 | 否 | +| scope | dump 范围，list[str] 类型，默认未配置（list 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。 | 否 | +| list | dump 范围，list[str] 类型，默认未配置（scope 也未配置时表示 dump 所有 api 的数据），配置方式参考 [config.json 配置介绍](./02.config_introduction.md)。 | 否 | +| online_run_ut | 在线预检模式开关，bool 类型，可取值 True（开启）、False（关闭），默认关闭。 | 是 | +| nfs_path | 在线预检模式共享存储目录路径，str 类型，用于 GPU 设备和 NPU 设备间进行通信。配置该参数后 host 和 port 不生效。 | 否 | +| host | 在线预检模式局域网场景信息接收端 IP，str 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的局域网 IP 地址。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 | +| port | 在线预检模式局域网场景信息接收端端口号，int 类型，用于 GPU 设备和 NPU 设备间进行通信，NPU 侧须配置为 GPU 侧的端口号。局域网场景时，不能配置 nfs_path 参数，否则局域网场景不生效。 | 否 | + +#### 3.1.3 局域网场景配置示例 + +GPU 侧： + +```json +{ + "task": "run_ut", + "run_ut": { + "white_list": [], + "black_list": [], + "error_data_path": "./", + "is_online": true, + "nfs_path": "", + "host": "127.0.0.1", + "port": 59208, + "rank_list": [0] + } +} +``` + +NPU 侧： + +```json +{ + "task": "tensor", + "dump_path": "./dump_path", + "rank": [0], + "step": [0], + "level": "L1", + "seed": 1234, + "is_deterministic": true, + "tensor": { + "scope": [], + "list": [], + "online_run_ut": true, + "nfs_path": "", + "host": "xx.xx.xx.x", + "port": 59208 + } +} +``` + +#### 3.1.4 共享存储场景配置示例 + +GPU 侧： + +```json +{ + "task": "run_ut", + "run_ut": { + "white_list": [], + "black_list": [], + "error_data_path": "./", + "is_online": true, + "nfs_path": "/nfs/xxx/data", + "host": "", + "port": -1, + "rank_list": [0] + } +} +``` + +NPU 侧： + +```json +{ + "task": "tensor", + "dump_path": "./dump_path", + "rank": [0], + "step": [0], + "level": "L1", + "seed": 1234, + "is_deterministic": true, + "tensor": { + "scope": [], + "list": [], + "online_run_ut": true, + "nfs_path": "/nfs/xxx/data", + "host": "", + "port": -1 + } +} +``` + +### 3.2 在 GPU 侧运行 run_ut + +由于 GPU 侧为通信接收端，需先于 NPU 侧执行 run_ut 操作，命令如下： + +```bash +msprobe -f pytorch run_ut -config ./config.json +``` + +GPU 侧配置好 config.json 文件后执行 run_ut 命令，此时 GPU 处于预检等待状态： + +- 局域网场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到 GPU 侧时，GPU 启动预检操作。 +- 共享存储场景：当 NPU 侧启动训练后将预检的 API 输入和输出数据发送到共享存储时，GPU 启动预检操作。 + +### 3.2 在 NPU 侧配置训练脚本 + +在 NPU 训练脚本中添加如下代码以获取 run_ut 操作的预检 API 输入和输出数据： + +```python +from msprobe.pytorch import PrecisionDebugger + +debugger = PrecisionDebugger("config.json") +... + +debugger.start() + +... + +debugger.stop() +debugger.step() +``` + +### 3.3 在 NPU 侧执行训练脚本 + +配置完 NPU 侧训练脚本后即可执行训练脚本，命令示例如下： + +```bash +bash train.sh +``` + +训练脚本执行完毕后，在 GPU 侧 dump_path 目录下生成比对结果文件，详细介绍请参见[离线精度预检中的 **4 预检结果**](./07.accuracy_checker_Pytorch.md#4-预检结果)。 diff --git a/debug/accuracy_tools/msprobe/docs/09.accuracy_checker_MindSpore.md b/debug/accuracy_tools/msprobe/docs/09.accuracy_checker_MindSpore.md new file mode 100644 index 0000000000000000000000000000000000000000..e7257c1b49395464d7be4396c7c8492d0e4e2878 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/09.accuracy_checker_MindSpore.md @@ -0,0 +1,70 @@ +# MindSpore 动态图场景的离线精度预检 + +## 1 简介 + +**MindSpore 动态图精度预检**\*1通过扫描昇腾 NPU 上用户训练 MindSpore 模型中的所有 Mint API，输出精度情况的诊断和分析。工具以模型中所有 Mint API 前反向的 dump 结果为输入，构造相应的 API 单元测试，将 NPU 输出与标杆（CPU 高精度）比对，计算对应的精度指标，从而找出 NPU 中存在精度问题的 Mint API。本工具支持随机生成模式和真实数据模式\*2。 + +**\***： + +1. 支持 Mindspore 版本：2.4； +2. 在预检 dump 时可以选择由工具构造随机数进行输入获得 dump 数据或选择获取真实输入数据进行预检 dump 操作。随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。 + +## 2 离线预检流程 + +操作流程如下： + +1. 在 NPU 和 GPU 环境下分别安装 msprobe。详见[ msprobe 安装](./01.installation.md)章节。 +2. 在 NPU 训练脚本内添加 msprobe 工具 dump 接口 PrecisionDebugger，采集待预检数据。详见 [MindSpore 场景下的数据采集](./06.data_dump_MindSpore.md)章节，注意需要配置 level="L1"。 +3. 执行预检操作，查看预检结果文件，分析预检不达标的API。 + +## 3 离线预检操作指导 + +命令如下： +```bash +msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result +``` + +| 参数名称 | 说明 |参数类型 | 是否必选 | +| ---------------------------- | --------------------------------------|---------------------- | ---------------------------------- | +| -api_info 或 --api_info_file | 指定 API 信息文件 dump.json。 | str | 是 | +| -o或--out_path | 指定预检结果存盘路径，默认“./”。 | str | 否 | + +预检执行结果包括 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 两个文件。`accuracy_checking_result_{timestamp}.csv` 属于 API 级，标明每个 API 是否通过测试。建议用户先查看 `accuracy_checking_result_{timestamp}.csv` 文件，对于其中没有通过测试的或者特定感兴趣的 API，根据其 API Name 字段在 `accuracy_checking_details_{timestamp}.csv` 中查询其各个输出的达标情况以及比较指标。详细介绍请参见 [4 预检结果](#4-预检结果)。 + +## 4 预检结果 + +精度预检生成的 `accuracy_checking_result_{timestamp}.csv` 和 `accuracy_checking_details_{timestamp}.csv` 文件内容详情如下： + +`accuracy_checking_details_{timestamp}.csv` + +| 字段 | 含义 | +| ------------------- | ------------------------------------------------------------ | +| API Name | API 名称。 | +| Bench Dtype | 标杆数据的 API 数据类型。 | +| Tested Dtype | 被检验数据的 API 数据类型。 | +| Shape | API 的 Shape 信息。 | +| Cosine | 被检验数据与标杆数据的余弦相似度。 | +| MaxAbsErr | 被检验数据与标杆数据的最大绝对误差。 | +| MaxRelativeErr | 被检验数据与标杆数据的最大相对误差。 | +| Status | API 预检通过状态，pass 表示通过测试，error 表示未通过。 | +| message | 提示信息。 | + +`accuracy_checking_result_{timestamp}.csv` + +| 字段 | 含义 | +| --------------------- | ----------------- | +| API Name | API 名称。 | +| Forward Test Success | 前向 API 是否通过测试，pass 为通过，error 为错误。 | +| Backward Test Success | 反向 API 是否通过测试，pass 为通过，error 为错误，如果是空白的话代表该 API 没有反向输出。 | +| Message | 提示信息。 | + +Forward Test Success 和 Backward Test Success 是否通过测试是由 `accuracy_checking_details_{timestamp}.csv` 中的余弦相似度、最大绝对误差判定结果决定的。具体规则详见\*1。 +需要注意的是 `accuracy_checking_details_{timestamp}.csv` 中可能存在一个 API 的前向（反向）有多个输出，那么每个输出记录一行，而在 `accuracy_checking_result_{timestamp}.csv` 中的结果需要该 API 的所有结果均为 pass 才能标记为 pass，只要存在一个 error 则标记 error。 + +**\***： + +1. API预检指标： + + - API 预检指标是通过对`accuracy_checking_details_{timestamp}.csv`中的余弦相似度、最大绝对误差的数值进行判断，得出该API是否符合精度标准的参考指标。详细规则如下： + + - 余弦相似度大于0.99，并且最大绝对误差小于0.0001，标记“pass”，否则标记为“error”。 diff --git a/debug/accuracy_tools/msprobe/docs/11.accuracy_compare_PyTorch.md b/debug/accuracy_tools/msprobe/docs/11.accuracy_compare_PyTorch.md new file mode 100644 index 0000000000000000000000000000000000000000..85004c7e5ae7bd04b2111833f4ae957d8aac0285 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/11.accuracy_compare_PyTorch.md @@ -0,0 +1,247 @@ +# PyTorch 场景的精度比对 + +## 1 简介 + +- 本节主要介绍通过命令行和比对函数的方式进行 CPU 或 GPU 与 NPU 的精度数据比对，执行精度比对操作前需要先完成 CPU 或 GPU 与 NPU 的精度数据 dump，参见 [PyTorch 场景下的数据采集](./05.data_dump_Pytorch.md)章节。 + +- msprobe 使用子命令 compare 进行比对，可支持单卡和多卡场景的精度数据比对。 + +- 比对函数均通过单独创建精度比对脚本执行，可支持单卡和多卡场景的精度数据比对。 + +- 工具性能：比对数据量较小时（单份文件小于 10 GB），比对速度 0.1 GB/s；比对数据量较大时，比对速度 0.3 GB/s。 推荐环境配置：独占环境，CPU 核心数 192，固态硬盘（IO 速度参考：固态硬盘 > 500 MB/s，机械硬盘 60 ~ 170 MB/s）。用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。比对速度的计算方式：两份比对文件大小/比对耗时。 + +**使用场景**： + +- 同一模型，从 CPU 或 GPU 移植到 NPU 中存在精度下降问题，对比 NPU 芯片中的 API 计算数值与 CPU 或 GPU 芯片中的 API 计算数值，进行问题定位。 +- 同一模型，进行迭代（模型、框架版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的 API 计算数值，进行问题定位。 + +**注意事项**： + +- NPU 自研 API，在 CPU 或 GPU 侧若没有对应的 API，该 API 的 dump 数据不比对。 +- NPU 与 CPU 或 GPU 的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个 API 因为输入的数据差异较大而无法比对的情况。 +- CPU 或 GPU 与 NPU 中两个相同的 API 会因为调用次数不同导致无法比对或比对到错误的 API，不影响整体运行，该 API 忽略。 + +**API匹配条件**： + +进行精度比对时，需要判断CPU或GPU的API与NPU的API是否相同可比对，须满足以下匹配条件： + +- 两个API的名称相同，API命名规则：`{api_type}.{api_name}.{api调用次数}.{正反向}.{输入输出}.index`，如：Functional.conv2d.1.backward.input.0。 +- 两个API的输入输出Tensor数量和各个Tensor的Shape相同。 + +通常满足以上两个条件，工具就认为是同一个API，成功进行API的匹配，后续进行相应的计算精度比对。 + +## 2 精度比对操作指导 + +### 2.1 命令行方式 + +将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。 + +请先参见 [PyTorch 场景下的数据采集](./05.data_dump_Pytorch.md)章节完成 CPU 或 GPU 与 NPU 的精度数据 dump。 + +**操作步骤**： + +1. 创建比对文件，文件内容及示例请参见\*1。 + +2. 运行命令： + + ```shell + msprobe -f pytorch compare -i ./compare.json -o ./output -s + ``` + + **参数说明**： + + | 参数名 | 说明 | 是否必选 | + |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | + | -i 或 --input_path | 指定比对文件路径。比对文件内容及示例请参见\*1。 | 是 | + | -o 或 --output_path | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是 | + | -s 或 --stack_mode | 配置 stack_mode 的开关。仅当比对文件\*1配置 stack_path 需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | + | -c 或 --compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否 | + | -f 或 --fuzzy_match | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | + +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 + } + ``` + + - 多卡场景示例： + + ```json + { + "npu_path": "./npu_dump/step0", + "bench_path": "./bench_dump/step0", + "is_print_compare_log": true + } + ``` + + **参数说明**： + + | 参数名 | 说明 | 是否必选 | + | -------------------- | ------------------------------------------------------------ | ------------------ | + | npu_path | 配置 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是 | + | bench_path | 配置 CPU、GPU 或 NPU 环境下的 dump.json 文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是 | + | stack_path | 配置 NPU dump 目录下的 stack.json 文件。数据类型：str。 | 单卡必选，多卡不选 | + | is_print_compare_log | 配置是否开启日志打屏。可取值 True 或 False。数据类型：bool | 否 | + +### 2.2 比对函数方式 + +#### 2.2.1 compare_distributed 函数 + +此函数将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，支持单卡和多卡，可同时比对多卡的 dump 数据。多机场景需要每个设备单独执行比对操作。可自动检索和匹配对应卡和进程所 dump 的数据文件，再调用 compare 进行比对。单机单卡时与 compare 函数二选一。 + +**函数原型**： + +```Python +compare_distributed(npu_dump_dir, bench_dump_dir, output_path, **kwargs) +``` + +**参数说明**： + +| 参数名 | 说明 | 是否必选 | +| -------------- | ------------------------------------------------------------ | -------- | +| npu_dump_dir | 配置 NPU 环境下的 dump 目录。str 类型。dump 数据目录须指定到 step 级。
**配置示例**：'./npu_dump/step0'。 | 是 | +| bench_dump_dir | 配置 CPU、GPU 或 NPU 环境下的 dump 目录。str 类型。
**配置示例**：'./gpu_dump/step0'。 | 是 | +| output_path | 配置比对结果文件存盘目录。需要预先创建 output_path 目录。str 类型。
**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}-rank{cpu/gpu/npu_ID}_{timestamp}.xlsx`。 | 是 | +| **kwargs | 支持 compare 的所有可选参数。 | 否 | + +**函数示例**： + +```Python +from msprobe.pytorch import * +compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output') +``` + +#### 2.2.2 compare 函数 + +此函数将 CPU 或 GPU 与 NPU 的 dump 文件进行比对，仅支持单机单卡。 + +**函数原型**： + +```Python +compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_match=False) +``` + +**参数说明**： + +| 参数名 | 说明 | 是否必选 | +| ------------ | ------------------------------------------------------------ | -------- | +| input_param | 配置 dump 数据文件及目录，dict 类型。配置参数包括：
"npu_json_path"：指定 NPU dump 目录下的 dump.json 文件。
**配置示例**："npu_json_path": "./npu_dump/dump.json"。
"bench_json_path"：指定 CPU、GPU 或 NPU dump 目录下的 dump.json 文件。
**配置示例**："bench_json_path": "./bench_dump/dump.json"。
"stack_json_path"：指定 NPU dump 目录下的 stack.json 文件。
**配置示例**："stack_json_path": "./npu_dump/stack.json"。
"is_print_compare_log"：配置是否开启日志打屏。
**配置示例**：True 或 False。 | 是 | +| output_path | 配置比对结果文件存盘目录，str 类型。
**配置示例**：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是 | +| stack_mode | 配置 stack_mode 的开关，bool 类型。仅当配置 stack_json_path 时需要开启。
**配置示例**：stack_mode=True，默认为 False。 | 否 | +| auto_analyze | 自动精度分析，bool 类型。开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 advisor_{timestamp}.txt 文件）。
**配置示例**：auto_analyze=False，默认为 True。 | 否 | +| fuzzy_match | 模糊匹配，bool 类型。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。
**配置示例**：fuzzy_match=True，默认为 False。 | 否 | + +**函数示例**： + +单机单卡场景下创建比对脚本，例如 compare.py，拷贝如下代码，具体参数请根据实际环境修改。 + +```Python +from msprobe.pytorch import compare +input_param={ +"npu_json_path": "./npu_dump/dump.json", +"bench_json_path": "./bench_dump/dump.json", +"stack_json_path": "./npu_dump/stack.json", +"is_print_compare_log": True +} +compare(input_param, output_path="./output", stack_mode=True) +``` + +#### 2.2.3 统计量比对 + +在使用 **compare** 或 **compare_distributed** 函数创建的比对脚本且在 [config.json](../config.json) 文件中配置 `"task": "statistics"` 时，可以进行统计量比对，此时比对 dump.json 文件中的统计信息，开启后的比对结果生成 Max diff、Min diff、Mean diff 和 L2norm diff，表示 NPU dump 数据中 API 的输入或输出与标杆数据输入或输出的最大值、最小值、平均值以及 L2 范数的差。可以通过该值判断 API 是否存在精度问题：当某个 API 的输入和输出的 Max diff、Min diff、Mean diff 和 L2norm diff 均为 0 或无限趋于 0，那么可以判断该 API 无精度问题，反之则可能存在精度问题。 + +**比对脚本示例**： + +以 compare.py 为例： + +```Python +from msprobe.pytorch import compare +input_param={ +"npu_json_path": "./npu_dump/dump.json", +"bench_json_path": "./bench_dump/dump.json", +"stack_json_path": "./npu_dump/stack.json", +"is_print_compare_log": True +} +compare(input_param, output_path="./output", stack_mode=True) +``` + +**统计量比对结果说明**： + +数据量比对同样生成 `compare_result_{timestamp}.xlsx` 和 `advisor_{timestamp}.txt` 文件。其中 `advisor_{timestamp}.txt` 主要对 `compare_result_{timestamp}.xlsx` 中可能存在精度问题（Result 为 Waring）的 API 提出定位建议；`compare_result_{timestamp}.xlsx` 主要有如下两种情况： + +- "summary_mode": "statistics" 时比对 dump.json 文件： + + ![compare_result_pkl](img/compare_result_pkl.png) + + 上图是对 dump.json 文件中 NPU 及标杆 API 的统计信息进行比对，判断可能存在精度问题的 API，文件中记录 NPU 及标杆 API 的基本信息和统计信息，其中需要关注 Result 列，包含结果：Waring（NPU 与标杆统计信息的比对中存在相对误差大于 0.5，则需要重点检查该 API）；为空（相对误差小于等于 0.5，可以不需要重点关注，但不代表不存在精度问题）；Nan（表示统计信息数据没有匹配上）。 + +- "summary_mode": "md5" 时比对 dump.json 文件： + + ![compare_result_pkl_md5.png](img/compare_result_pkl_md5.png.png) + + 上图是对 dump.json 文件中 NPU 及标杆 API 的 MD5 信息进行比对，判断 API 数据的完整性，文件中记录 NPU 及标杆 API 的基本信息和 MD5 信息，其中需要关注 Result 列，包含结果：Pass（表示 NPU 与标杆的 MD5 值一致，即 API 数据完整）；Different（表示 NPU 与标杆的 MD5 值不一致，即 API 数据不完全一致，可以通过 NPU_Stack_Info 列 API 调用栈查询该 API 的详细信息）；Nan（表示 MD5 信息数据没有匹配上）。 + +## 3 精度比对结果分析 + +PyTorch 精度比对是以 CPU 或 GPU 的计算结果为标杆，通过计算精度评价指标判断 API 在运行时是否存在精度问题。 + +- `advisor_{timestamp}.txt` 文件中给出了可能存在精度问题的 API 的专家建议，可直接打开查看。 + +- `compare_result_{timestamp}.xlsx` 文件列出了所有执行精度比对的 API 详细信息和比对结果，示例如下： + + ![compare_result](https://gitee.com/cai-weiwei1989/att_ptdbg/raw/master/debug/accuracy_tools/ptdbg_ascend/doc/img/compare_result.png) + + 可以从该结果文件中进行[判断计算精度达标情况](#31-判断计算精度达标情况)、[计算精度评价指标分析](#32-计算精度评价指标分析)以及[异常信息识别](#33-异常信息识别)等分析动作。 + +### 3.1 判断计算精度达标情况 + +精度比对结果 `compare_result_{timestamp}.xlsx` 文件中只需要通过 Accuracy Reached or Not 来判断计算精度是否达标，判断标准如下： + +1. Cosine < 0.99 且 MaxAbsError > 0.001 时，精度不达标，标记为 No。 +2. Cosine < 0.9，精度不达标，标记为 No。 +3. MaxAbsError > 1，精度不达标，标记为 No。 +4. 其余情况下记为精度达标，标记为 Yes。 + +### 3.2 计算精度评价指标分析 + +1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于 1 说明计算出的两个张量越相似，实际可接受阈值为大于 0.99。在计算中可能会存在 nan，主要由于可能会出现其中一个向量为 0。 + +2. MaxAbsErr：当最大绝对误差越接近 0 表示其计算的误差越小，实际可接受阈值为小于 0.001。 + +3. MaxRelativeErr：当最大相对误差越接近 0 表示其计算的误差越小。 + + 当 dump 数据中存在 0 或 Nan 时，比对结果中最大相对误差则出现 inf 或 Nan 的情况，属于正常现象。 + +4. One Thousandth Err Ratio（双千分之一）、Five Thousandths Err Ratio（双千分之五）精度指标：是指 NPU 的 Tensor 中的元素逐个与对应的标杆数据对比，相对误差大于千分之一、千分之五的比例占总元素个数的比例小于千分之一、千分之五。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。 + +### 3.3 异常信息识别 + +精度比对结果 `compare_result_{timestamp}.xlsx` 文件中对于存在异常信息的API会进行高亮处理： + +- 红色可能出现的情况有： + - NPU max 或 NPU min 信息中存在 nan/inf； + - Max diff存在大于1e+10的值； + - 统计数据中output的Max diff除以max(0.01, Bench max) > 0.5； + - 真实数据中One Thousandth Err Ratio的input > 0.9同时output < 0.6。 +- 黄色可能出现的情况有： + - Max diff的input与output都大于1，同时output比input大一个数量级以上； + - 统计数据Max diff除以max(0.01, Bench max)的output > 0.1同时input < 0.01； + - 真实数据One Thousandth Err Ratio的input - output > 0.1； + - 真实数据Cosine的input - output > 0.1。 + +Shape为 [ ] 时，统计量列说明： + +当 NPU Tensor Shape 列为 [ ] 时，表示标量或 0 维张量，统计量列（NPU max、NPU min、NPU mean、NPU l2norm）展示相同的唯一元素。Bench 同理。 diff --git a/debug/accuracy_tools/msprobe/docs/12.accuracy_compare_MindSpore.md b/debug/accuracy_tools/msprobe/docs/12.accuracy_compare_MindSpore.md new file mode 100644 index 0000000000000000000000000000000000000000..7b5f7e7309bc5f2c2d7311e07a3107cb0dc546a2 --- /dev/null +++ b/debug/accuracy_tools/msprobe/docs/12.accuracy_compare_MindSpore.md @@ -0,0 +1,62 @@ +# MindSpore 场景的精度比对 + +## 1 简介 + +msprobe 精度比对工具主要通过对同一个模型，在两个不同的 MindSpore 环境下，输入相同的训练数据，在分别得到 dump 数据后，对这两个 dump 数据进行全量自动对比，从而快速定位不同版本之间的精度问题。 + +## 2 精度比对操作指导 + +### 2.1 命令行方式 + +该工具目前使用方式为命令行形式，对 MindSpore 的 dump 数据仅支持单卡。 + +请先参见 [MindSpore 场景下的数据采集](./06.data_dump_MindSpore.md)章节，完成不同环境下 MindSpore 精度数据的采集。 + +**操作步骤**： + +1. 使用 MindSpore 进行 dump，得到不同框架版本的 dump 数据。 + +2. 创建比对文件，文件内容及示例请参见\*1。 + +3. 运行命令： + + ```shell + msprobe -f mindspore compare -i ./compare.json -o ./output -s + ``` + + **参数说明**： + + | 参数名 | 说明 | 是否必选 | + |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | + | -i 或 --input_path | 指定比对文件路径。比对文件内容及示例请参见\*1。 | 是 | + | -o 或 --output_path | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是 | + | -s 或 --stack_mode | 配置 stack_mode 的开关。仅当比对文件\*1配置 stack_path 需要开启。默认未配置，表示关闭。 | 否 | + | -c 或 --compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的 Accuracy Reached or Not 列显示为 No），并给出问题可能产生的原因（打屏展示并生成 `advisor_{timestamp}.txt` 文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否 | + | -f 或 --fuzzy_match | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的 API，可匹配并进行比对。默认未配置，表示关闭。 | 否 | + +4. 查看比对结果，请参见 [PyTorch 场景的精度比对——精度比对结果分析](./11.accuracy_compare_PyTorch.md#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 文件（单卡场景），str 类型。 | 是 | + | bench_path | 配置 CPU、GPU 或 NPU 环境下的 dump.json 文件（单卡场景），str 类型。 | 是 | + | stack_path | 配置 NPU dump 目录下的 stack.json 文件，str 类型。 | 是| + | is_print_compare_log | 配置是否开启日志打屏，bool 类型。可取值 True 或 False，默认为 True。 | 否 | + \ No newline at end of file diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/run_overflow_check.md b/debug/accuracy_tools/msprobe/docs/13.overflow_check_PyTorch.md similarity index 97% rename from debug/accuracy_tools/msprobe/pytorch/doc/run_overflow_check.md rename to debug/accuracy_tools/msprobe/docs/13.overflow_check_PyTorch.md index f56165b255860de3a562e04a07066b67c73fa44a..e633a3f24eb3ed28e663de2fa025789903333daa 100644 --- a/debug/accuracy_tools/msprobe/pytorch/doc/run_overflow_check.md +++ b/debug/accuracy_tools/msprobe/docs/13.overflow_check_PyTorch.md @@ -1,4 +1,4 @@ -# **溢出解析工具** +# 溢出解析工具（更新中） 针对训练过程中的溢出检测场景（当《[精度数据采集](./dump.md)》开启溢出检测dump时），对于输入正常但输出存在溢出的API，会在训练执行目录下将溢出的API信息按照前向和反向分类，dump并保存为`dump.json`，前向过程溢出的API可通过该工具对`dump.json`进行解析，输出溢出API为正常溢出还是非正常溢出，从而帮助用户快速判断。 diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/parse_tool.md b/debug/accuracy_tools/msprobe/docs/15.data_parse_PyTorch.md similarity index 69% rename from debug/accuracy_tools/msprobe/pytorch/doc/parse_tool.md rename to debug/accuracy_tools/msprobe/docs/15.data_parse_PyTorch.md index 81efa10fa3ec4307603e24e9599c5a00367462d4..68a3d1a57dc1b649ffdb6d02d7be378900458e65 100644 --- a/debug/accuracy_tools/msprobe/pytorch/doc/parse_tool.md +++ b/debug/accuracy_tools/msprobe/docs/15.data_parse_PyTorch.md @@ -1,26 +1,32 @@ -# **数据解析工具** +# PyTorch 场景的数据解析 -数据解析工具（parse_tool）提供命令行交互式界面，提供更多的数据解析功能并且展示结果。 +## 1 简介 -使用场景：本工具主要用于精度比对前后两次NPU kernel层级dump数据的一致性。 +数据解析功能提供命令行交互式界面，提供了更多的结果展示。 -## 进入parse交互式界面 +使用场景：本工具主要用于精度比对前后两次 NPU kernel 层级 dump 数据的一致性。 -安装msprobe工具后（详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节），可以通过使用命令 **msprobe -f pytorch parse** 进入交互式界面，如下所示： +依赖：CANN 包中的 msaccucmp 工具，需要安装 Ascend-CANN-toolkit，详见《[CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)》。 + +## 2 数据解析操作指导 + +### 2.1 进入 parse 交互式界面 + +安装 msprobe 工具后，可以通过使用命令 `msprobe -f pytorch parse` 进入交互式界面，如下所示： ```bash msprobe -f pytorch parse Parse >>> ``` -可在parse的界面中执行Shell命令，以及如下场景的相关解析命令： +可在 parse 的界面中执行 Shell 命令，以及如下场景的相关解析命令（详细介绍请参见以下章节。）： -- 支持指定kernel层级算子数据比对。 -- 支持指定kernel层级算子数据转换及展示。 -- 支持交互式指定pkl文件中API对应dump数据查看。 -- 支持API进行可选层级比对和打印（统计级和像素级）。 +- 支持指定 kernel 层级算子数据比对。 +- 支持指定 kernel 层级算子数据转换及展示。 +- 支持交互式指定 pkl 文件中 API 对应 dump 数据查看。 +- 支持 API 进行可选层级比对和打印（统计级和像素级）。 -Ctrl+C可以退出parse交互式界面。不退出parse交互式界面若需要执行非该界面下的内置Shell命令，且命令与parse交互式界面命令冲突时，非该界面命令需要使用run命令，在相关命令前加上run前缀，如下示例： +Ctrl+C 可以退出 parse 交互式界面。不退出 parse 交互式界面若需要执行非该界面下的内置 Shell 命令，且命令与 parse 交互式界面命令冲突时，非该界面命令需要使用 run 命令，在相关命令前加上 run 前缀，如下示例： ```bash msprobe -f pytorch parse @@ -28,13 +34,9 @@ Parse >>> run vim cli.py Parse >>> vim cli.py ``` -以上各场景详细介绍请参见下文章节。 +### 2.2 kernel 层级算子数据批量转换 -## kernel层级算子数据批量转换 - -本功能会将原有待比对dump数据目录下的dump数据按照算子名和时间戳进行梳理并分类，之后再将dump数据转为为npy文件。 - -依赖：CANN包中的msaccucmp工具，需要安装Ascend-CANN-toolkit，详见《[CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)》。 +本功能会将原有待比对 dump 数据目录下的 dump 数据按照算子名和时间戳进行梳理并分类，之后再将 dump 数据转为 npy 文件。 输入以下比对命令进行数据转换。 @@ -44,13 +46,13 @@ cad -m my_dump_path [-out output_path] [-asc msaccucmp_path] | 参数名称 | 说明 | 是否必选 | | -------- | ------------------------------------------------------------ | -------- | -| -m | 待转换kernel dump数据目录。需要指定到kernel dump数据的deviceid级目录。 | 是 | -| -out | 结果输出目录，须指定已存在的目录，默认为./parse_data/acl_batch_convert。未指定时保存在默认路径下，比对结束后会打印log提示输出结果存放路径。 | 否 | -| -asc | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py。 | 否 | +| -m | 待转换 kernel dump 数据目录。需要指定到 kernel dump 数据的 deviceid 级目录。 | 是 | +| -out | 结果输出目录，须指定已存在的目录，默认为 ./parse_data/acl_batch_convert。未指定时保存在默认路径下，比对结束后会打印 log 提示输出结果存放路径。 | 否 | +| -asc | 指定 msaccucmp 路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py。 | 否 | -**示例** +**示例代码**： -``` +```bash # 传入待比对数据目录 Parse >>> cad -m /home/xxx/my_dump_path/20000124003856/0 # 转换结果打印 @@ -66,9 +68,9 @@ Parse >>> cad -m /home/xxx/my_dump_path/20000124003856/0 [INFO] The comparison result have been written to "./parse_data/acl_batch_convert". ``` -输出结果： +**输出结果**： -原dump数据目录： +原 dump 数据目录： ``` ├── /home/xxx/my_dump_path/20000124003856/0/ @@ -93,11 +95,9 @@ Parse >>> cad -m /home/xxx/my_dump_path/20000124003856/0 │ ├── ... ``` -## kernel层级算子数据比对 - -本功能主要用于比对前后两次NPU kernel层级dump数据的一致性。 +### 2.3 kernel 层级算子数据比对 -本功能支持批量比对，若需要进行批量比对，需要先将两份待比对的NPU kernel层级dump数据进行“**kernel层级算子数据批量转换**”，可以使两份数据更好的匹配；若直接进行dump数据的比对，建议只比对单个dump数据文件。 +本功能主要用于比对前后两次 NPU kernel 层级 dump 数据的一致性，并支持批量比对，比对时需要先将两份待比对的 NPU kernel 层级 dump 数据进行 [kernel 层级算子数据批量转换](#22-kernel-层级算子数据批量转换)，可以使两份数据更好的匹配；若直接进行 dump 数据的比对，建议只比对单个 dump 数据文件。 输入以下比对命令进行数据比对。 @@ -107,14 +107,14 @@ vc -m my_dump_path -g golden_dump_path [-out output_path] [-cmp_path msaccucmp_p | 参数名称 | 说明 | 是否必选 | | --------- | ------------------------------------------------------------ | -------- | -| -m | 待比对kernel dump数据目录。如果比对单个算子，需要指定到kernel dump数据的model_id级目录；如果批量比对，则指定到cad转换后的timestamp级目录。 | 是 | -| -g | 标杆kernel dump数据目录。如果比对单个算子，需要指定到kernel dump数据的model_id级目录；如果批量比对，则指定到cad转换后的timestamp级目录。 | 是 | -| -out | 结果输出目录，须指定已存在的目录，默认为./parse_data/acl_batch_comapre。未指定时保存在默认路径下，比对结束后会打印log提示输出结果存放路径。 | 否 | -| -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | +| -m | 待比对 kernel dump 数据目录。如果比对单个算子，需要指定到 kernel dump 数据的 model_id 级目录；如果批量比对，则指定到 cad 转换后的 timestamp 级目录。 | 是 | +| -g | 标杆 kernel dump 数据目录。如果比对单个算子，需要指定到 kernel dump 数据的 model_id 级目录；如果批量比对，则指定到 cad 转换后的 timestamp 级目录。 | 是 | +| -out | 结果输出目录，须指定已存在的目录，默认为 ./parse_data/acl_batch_comapre。未指定时保存在默认路径下，比对结束后会打印 log 提示输出结果存放路径。 | 否 | +| -cmp_path | 指定 msaccucmp 路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | -输出结果：batch_compare_{timestamp}.csv文件。 +输出结果：`batch_compare_{timestamp}.csv` 文件。 -**示例** +**示例代码**： ```bash # 传入待比对数据目录以及标杆数据目录 @@ -122,11 +122,9 @@ Parse >>> vc -m ./my_dump_path -g ./golden_data_path [INFO]Compare result is saved in : parse_data/acl_batch_comapre/batch_compare_1707271118.csv ``` -## kernel算子数据的npy转换 +### 2.3 kernel 算子数据的 npy 转换 -依赖：CANN包中的msaccucmp工具，需要安装Ascend-CANN-toolkit，详见《[CANN 软件安装指南](https://gitee.com/link?target=https%3A%2F%2Fwww.hiascend.com%2Fdocument%2Fdetail%2Fzh%2Fcanncommercial%2F700%2Fenvdeployment%2Finstg%2Finstg_0001.html)》。 - -输入以下转换命令进行数据转换， 将kernel级别dump数据转为npy文件。 +输入以下转换命令进行数据转换， 将 kernel 级别 dump 数据转为 npy 文件。 ```bash dc -n file_name/file_path [-f format] [-out output_path] @@ -134,18 +132,18 @@ dc -n file_name/file_path [-f format] [-out output_path] | 参数名称 | 说明 | 是否必选 | | --------- | ------------------------------------------------------------ | -------- | -| -n | 需转换的dump数据文件或dump数据文件目录。 | 是 | -| -f | 开启format转换，指定该参数时需要配置format格式。当前内置的Format转换支持如下类型： FRACTAL_NZ转换NCHW FRACTAL_NZ转换成NHWC FRACTAL_NZ转换ND HWCN转换FRACTAL_Z HWCN转换成NCHW HWCN转换成NHWC NC1HWC0转换成HWCN NC1HWC0转换成NCHW NC1HWC0转换成NHWC NCHW转换成FRACTAL_Z NCHW转换成NHWC NHWC转换成FRACTAL_Z NHWC转换成HWCN NHWC转换成NCHW NDC1HWC0转换成NCDHW | 否 | +| -n | 需转换的 dump 数据文件或 dump 数据文件目录。 | 是 | +| -f | 开启 format 转换，指定该参数时需要配置 format 格式。当前内置的 Format 转换支持如下类型：
FRACTAL_NZ 转换 NCHW；
FRACTAL_NZ 转换成 NHWC；
FRACTAL_NZ 转换 ND；
HWCN 转换 FRACTAL_Z；
HWCN 转换成 NCHW；
HWCN 转换成 NHWC；
NC1HWC0 转换成 HWCN；
NC1HWC0 转换成 NCHW；
NC1HWC0 转换成 NHWC；
NCHW 转换成 FRACTAL_Z；
NCHW转换成NHWC；
NHWC转换成FRACTAL_Z；
NHWC转换成HWCN；
NHWC转换成NCHW；
NDC1HWC0转换成NCDHW。 | 否 | | -out | 结果输出目录。 | 否 | -| -cmp_path | 指定msaccucmp路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | +| -cmp_path | 指定 msaccucmp 路径，默认路径为：/usr/local/Ascend/ascend-toolkit/latest/tools/operator_cmp/compare/msaccucmp.py | 否 | -- 输出结果：npy文件。 +- 输出结果：npy 文件。 -- 若指定-out参数需要用户传入输出路径，并且路径需要已存在。 +- 若指定 -out 参数需要用户传入输出路径，并且路径需要已存在。 -- 若未指定输出目录， 则比对结束后将结果保存在默认目录 “./parse_data/convert_result”中，比对结束后会打印log提示输出结果存放路径及转换结果。 +- 若未指定输出目录， 则比对结束后将结果保存在默认目录 “./parse_data/convert_result” 中，比对结束后会打印 log 提示输出结果存放路径及转换结果。 -- 输入以下命令，展示npy数据统计信息。 +- 输入以下命令，展示 npy 数据统计信息。 ```bash pt -n file_path @@ -153,11 +151,11 @@ dc -n file_name/file_path [-f format] [-out output_path] | 参数名称 | 说明 | 是否必选 | | -------- | ------------- | -------- | - | -n | npy文件路径。 | 是 | + | -n | npy 文件路径。 | 是 | - 打印统计信息：shape, dtype, max, min和mean。默认在npy文件路径下将该数据保存为txt文件。 + 打印统计信息：shape, dtype, max, min 和 mean。默认在 npy 文件路径下将该数据保存为 txt 文件。 -**示例1** +**示例代码1**： ```bash # 传入需转换的dump文件目录 @@ -178,7 +176,7 @@ Parse >>> dc -n ./dump_data/ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` -**示例2** +**示例代码2**： ```bash # 查看某个dump数据块的数据信息 @@ -191,9 +189,9 @@ Path: ./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595 TextFile:./parse_data/dump_convert/Add.fp32_vars_add_1fp32_vars_Relu_6.24.5.1636595794631347.input.0.npy.txt ``` -## dump.json文件中指定API的dump数据信息查看（暂不支持） +### 2.4 dump.json 文件中指定 API 的 dump 数据信息查看（暂不支持） -输入以下命令，解析并输出dump.json文件中指定API的统计信息。 +输入以下命令，解析并输出 dump.json 文件中指定 API 的统计信息。 ```bash pk -f pkl_path -n api_name @@ -201,13 +199,13 @@ pk -f pkl_path -n api_name | 参数名称 | 说明 | 是否必选 | | -------- | ----------------------- | -------- | -| -f | 指定dump.json文件路径。 | 是 | -| -n | 指定API名称。 | 是 | +| -f | 指定 dump.json 文件路径。 | 是 | +| -n | 指定 API 名称。 | 是 | - 输出结果：打印统计信息（shape, dtype, max和min mean）。 -- 若pkl文件中存在相应的堆栈信息，则会打印堆栈信息。 +- 若 pkl 文件中存在相应的堆栈信息，则会打印堆栈信息。 -**示例** +**示例代码**： ```bash # 传入pkl文件及api名称 @@ -222,7 +220,7 @@ Statistic Info: [Functional_conv2d_0_forward_output][dtype: torch.float32][shape: [2, 2, 1, 1]][max: 0.02364911139011383][min: -1.762906551361084][mean: -0.6710853576660156] ``` -## API可选层级比对 +### 2.5 API 可选层级比对 输入以下命令, 进行统计级和像素级比对。 @@ -230,17 +228,17 @@ Statistic Info: cn -m my_data*.npy -g gloden*.npy [-p num] [-al atol] [-rl rtol] ``` -- 统计级比对：对tensor整体进行余弦值及相对误差的计算。 -- 像素级比对：对输入的两个npy文件进行逐元素比对。若两个tensor对应元素的相对误差或绝对误差大于**误差阈值**（-al和-rl配置）则被标记为错误数据。 +- 统计级比对：对 tensor 整体进行余弦值及相对误差的计算。 +- 像素级比对：对输入的两个 npy 文件进行逐元素比对。若两个 tensor 对应元素的相对误差或绝对误差大于**误差阈值**（-al 和 -rl 配置）则被标记为错误数据。 | 参数名称 | 说明 | 是否必选 | | -------- | ----------------------------------------------- | -------- | | -m | 待比对数据。 | 是 | | -g | 标杆数据。 | 是 | -| -p | 设置比对结束后打印错误元素的个数，默认值20。 | 否 | -| -al | 判定数据存在精度问题的绝对误差阈值，默认0.001。 | 否 | -| -rl | 判定数据存在精度问题的相对误差阈值，默认0.001。 | 否 | -| -s | 将npy文件保存成txt文件，用于查看，默认开启。 | 否 | +| -p | 设置比对结束后打印错误元素的个数，默认值 20。 | 否 | +| -al | 判定数据存在精度问题的绝对误差阈值，默认 0.001。 | 否 | +| -rl | 判定数据存在精度问题的相对误差阈值，默认 0.001。 | 否 | +| -s | 将 npy 文件保存成 txt 文件，用于查看，默认开启。 | 否 | 输出结果： @@ -248,7 +246,7 @@ cn -m my_data*.npy -g gloden*.npy [-p num] [-al atol] [-rl rtol] - 两个文件的统计信息（shape, dtype, max, min和mean）。 - 错误数据打印表格。 -**示例** +**示例代码**： ```bash # 对比两个tensor的数据 @@ -283,4 +281,3 @@ Parse >>> cn -m Add.InceptionV3_InceptionV3_Mixed_7a_Branch_0_add_3.323.16194941 │ ErrorPer: 0.023504638671875 (rl= 0.005, al= 0.002) │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` - diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/grad_probe.md b/debug/accuracy_tools/msprobe/docs/19.grad_probe.md similarity index 96% rename from debug/accuracy_tools/msprobe/doc/grad_probe/grad_probe.md rename to debug/accuracy_tools/msprobe/docs/19.grad_probe.md index fcbd2f123d1610c275049cc4f523c87364f53a6a..d7856e35a5e5a61b35aa7ef645ab9e98f42e4bd5 100644 --- a/debug/accuracy_tools/msprobe/doc/grad_probe/grad_probe.md +++ b/debug/accuracy_tools/msprobe/docs/19.grad_probe.md @@ -1,4 +1,4 @@ -# Ascend模型梯度状态监测工具 +# Ascend 模型梯度状态监测工具 梯度状态监测工具提供了两种能力： @@ -7,10 +7,7 @@ 工具支持PyTorch版本：2.0/2.1/2.2；支持MindSpore版本：r2.3。 -## 工具特性 -- 使用便捷，无需在训练流程里插入代码 -- 可以精准定位问题出现的step ## 使用方式 @@ -65,7 +62,7 @@ + 值分布：梯度数据落在各个区间的元素个数占总元素个数的比例。 + 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) + ![Alt text](img/grad_probe_image-1.png) 2. 插入代码。示例代码如下： @@ -110,7 +107,7 @@ gm.stop() 样例如下： -![Alt text](img/image.png) +![Alt text](img/grad_probe_image.png) | 字段 | 含义 | | --------------------- | ------------------------------------------------------------| @@ -166,15 +163,15 @@ GradComparator.compare_distributed("配置文件里写的dump_path", - 第0步相似度低于0.97 -![Alt text](img/image-3.png) +![Alt text](img/grad_probe_image-3.png) - 第3步相似度下降超过0.03 -![Alt text](img/image-4.png) +![Alt text](img/grad_probe_image-4.png) - 正常情况 -![Alt text](img/image-2.png) +![Alt text](img/grad_probe_image-2.png) 这个原则是一个经验性的指标，并不是严格的标注，还需要结合实际情况具体分析。 @@ -202,6 +199,3 @@ GradComparator.compare_distributed(dump_path1, dump_path2, output_path) | dump_path1 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path。 | 是 | | dump_path2 |需要比对的其中一个dump目录，也就是配置文件里写的dump_path，与dump_path1可以互换。 | 是 | | output_path |输出结果目录，不存在会新建。 | 是 | - - -# FAQ diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/FAQ.md b/debug/accuracy_tools/msprobe/docs/FAQ_PyTorch.md similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/FAQ.md rename to debug/accuracy_tools/msprobe/docs/FAQ_PyTorch.md diff --git "a/debug/accuracy_tools/msprobe/pytorch/doc/msprobe\347\262\276\345\272\246\345\267\245\345\205\267\346\225\260\346\215\256dump\346\240\207\345\207\206\346\200\247\350\203\275\345\237\272\347\272\277\346\212\245\345\221\212.md" b/debug/accuracy_tools/msprobe/docs/S01.report_msprobe_dump_standard_performance_baseline.md similarity index 94% rename from "debug/accuracy_tools/msprobe/pytorch/doc/msprobe\347\262\276\345\272\246\345\267\245\345\205\267\346\225\260\346\215\256dump\346\240\207\345\207\206\346\200\247\350\203\275\345\237\272\347\272\277\346\212\245\345\221\212.md" rename to debug/accuracy_tools/msprobe/docs/S01.report_msprobe_dump_standard_performance_baseline.md index c9db3ae78d7d47330cf6cddcc66c741c77a63514..b2db1214705d72442c82c3feebec6b29a1191fa9 100644 --- "a/debug/accuracy_tools/msprobe/pytorch/doc/msprobe\347\262\276\345\272\246\345\267\245\345\205\267\346\225\260\346\215\256dump\346\240\207\345\207\206\346\200\247\350\203\275\345\237\272\347\272\277\346\212\245\345\221\212.md" +++ b/debug/accuracy_tools/msprobe/docs/S01.report_msprobe_dump_standard_performance_baseline.md @@ -1,6 +1,6 @@ -# msprobe精度工具标准性能基线报告 +# msprobe 精度工具标准性能基线报告 -## 环境信息 +## 1 环境信息 NPU：Atlas A2 训练系列产品 @@ -12,7 +12,7 @@ Torch：2.1.0 CANN：8.0.T2 -除上述环境信息影响性能外，API的数量、种类以及Shape都会对性能产生影响，因此本次选取指定网络进行测试，为了避免算子编译耗时的影响，所有模型运行时都开启二进制，模型中添加torch.npu.set_compile_mode(jit_compile=False)，所有模型都dump第二个step的数据。 +除上述环境信息影响性能外，API 的数量、种类以及 Shape 都会对性能产生影响，因此本次选取指定网络进行测试，为了避免算子编译耗时的影响，所有模型运行时都开启二进制，模型中添加 torch.npu.set_compile_mode(jit_compile=False)，所有模型都 dump 第二个 step 的数据。 ## 模型信息和性能基线 diff --git "a/debug/accuracy_tools/msprobe/pytorch/doc/\346\227\240\346\240\207\346\235\206\345\267\245\345\205\267\345\234\272\346\231\257\351\252\214\350\257\201\345\222\214\346\200\247\350\203\275\345\237\272\347\272\277\346\212\245\345\221\212.md" b/debug/accuracy_tools/msprobe/docs/S02.report_free_benchmarking_validation_performance_baseline.md similarity index 100% rename from "debug/accuracy_tools/msprobe/pytorch/doc/\346\227\240\346\240\207\346\235\206\345\267\245\345\205\267\345\234\272\346\231\257\351\252\214\350\257\201\345\222\214\346\200\247\350\203\275\345\237\272\347\272\277\346\212\245\345\221\212.md" rename to debug/accuracy_tools/msprobe/docs/S02.report_free_benchmarking_validation_performance_baseline.md diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_1.png b/debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_1.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_1.png rename to debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_1.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_2.png b/debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_2.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_2.png rename to debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_2.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_3.png b/debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_3.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_3.png rename to debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_3.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_4.png b/debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_4.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/BLOOM-7B_4.png rename to debug/accuracy_tools/msprobe/docs/img/BLOOM-7B_4.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_1.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_1.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_1.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_1.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_2.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_2.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_2.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_2.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_3.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_3.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_3.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_3.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_4.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_4.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_4.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_4.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_5.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_5.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_5.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_5.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_6.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_6.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_6.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_6.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_7.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_7.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_7.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_7.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_8.png b/debug/accuracy_tools/msprobe/docs/img/GPT-3_8.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/GPT-3_8.png rename to debug/accuracy_tools/msprobe/docs/img/GPT-3_8.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/YOLOV5S_1.png b/debug/accuracy_tools/msprobe/docs/img/YOLOV5S_1.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/YOLOV5S_1.png rename to debug/accuracy_tools/msprobe/docs/img/YOLOV5S_1.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/YOLOV5S_2.png b/debug/accuracy_tools/msprobe/docs/img/YOLOV5S_2.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/YOLOV5S_2.png rename to debug/accuracy_tools/msprobe/docs/img/YOLOV5S_2.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/accuracy_checking_details.png b/debug/accuracy_tools/msprobe/docs/img/accuracy_checking_details.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/accuracy_checking_details.png rename to debug/accuracy_tools/msprobe/docs/img/accuracy_checking_details.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/accuracy_checking_result.png b/debug/accuracy_tools/msprobe/docs/img/accuracy_checking_result.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/accuracy_checking_result.png rename to debug/accuracy_tools/msprobe/docs/img/accuracy_checking_result.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/api_precision_compare_details.png b/debug/accuracy_tools/msprobe/docs/img/api_precision_compare_details.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/api_precision_compare_details.png rename to debug/accuracy_tools/msprobe/docs/img/api_precision_compare_details.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/api_precision_compare_result.png b/debug/accuracy_tools/msprobe/docs/img/api_precision_compare_result.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/api_precision_compare_result.png rename to debug/accuracy_tools/msprobe/docs/img/api_precision_compare_result.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/auto_analyze_log.png b/debug/accuracy_tools/msprobe/docs/img/auto_analyze_log.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/auto_analyze_log.png rename to debug/accuracy_tools/msprobe/docs/img/auto_analyze_log.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/compare_result_pkl.png b/debug/accuracy_tools/msprobe/docs/img/compare_result_pkl.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/compare_result_pkl.png rename to debug/accuracy_tools/msprobe/docs/img/compare_result_pkl.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/compare_result_pkl_md5.png.png b/debug/accuracy_tools/msprobe/docs/img/compare_result_pkl_md5.png.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/compare_result_pkl_md5.png.png rename to debug/accuracy_tools/msprobe/docs/img/compare_result_pkl_md5.png.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/cpu_info.png b/debug/accuracy_tools/msprobe/docs/img/cpu_info.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/cpu_info.png rename to debug/accuracy_tools/msprobe/docs/img/cpu_info.png diff --git a/debug/accuracy_tools/msprobe/config/img/free_benchmark.png b/debug/accuracy_tools/msprobe/docs/img/free_benchmark.png similarity index 100% rename from debug/accuracy_tools/msprobe/config/img/free_benchmark.png rename to debug/accuracy_tools/msprobe/docs/img/free_benchmark.png diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/img/image-1.png b/debug/accuracy_tools/msprobe/docs/img/grad_probe_image-1.png similarity index 100% rename from debug/accuracy_tools/msprobe/doc/grad_probe/img/image-1.png rename to debug/accuracy_tools/msprobe/docs/img/grad_probe_image-1.png diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/img/image-2.png b/debug/accuracy_tools/msprobe/docs/img/grad_probe_image-2.png similarity index 100% rename from debug/accuracy_tools/msprobe/doc/grad_probe/img/image-2.png rename to debug/accuracy_tools/msprobe/docs/img/grad_probe_image-2.png diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/img/image-3.png b/debug/accuracy_tools/msprobe/docs/img/grad_probe_image-3.png similarity index 100% rename from debug/accuracy_tools/msprobe/doc/grad_probe/img/image-3.png rename to debug/accuracy_tools/msprobe/docs/img/grad_probe_image-3.png diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/img/image-4.png b/debug/accuracy_tools/msprobe/docs/img/grad_probe_image-4.png similarity index 100% rename from debug/accuracy_tools/msprobe/doc/grad_probe/img/image-4.png rename to debug/accuracy_tools/msprobe/docs/img/grad_probe_image-4.png diff --git a/debug/accuracy_tools/msprobe/doc/grad_probe/img/image.png b/debug/accuracy_tools/msprobe/docs/img/grad_probe_image.png similarity index 100% rename from debug/accuracy_tools/msprobe/doc/grad_probe/img/image.png rename to debug/accuracy_tools/msprobe/docs/img/grad_probe_image.png diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/img/module_compare.png b/debug/accuracy_tools/msprobe/docs/img/module_compare.png similarity index 100% rename from debug/accuracy_tools/msprobe/pytorch/doc/img/module_compare.png rename to debug/accuracy_tools/msprobe/docs/img/module_compare.png diff --git a/debug/accuracy_tools/msprobe/mindspore/debugger/precision_debugger.py b/debug/accuracy_tools/msprobe/mindspore/debugger/precision_debugger.py index 0b3fec632d1244cf0e847a779df02372ee803b38..d7ff0e5a6854cb05e90e2490a5dcf2149dbaadd9 100644 --- a/debug/accuracy_tools/msprobe/mindspore/debugger/precision_debugger.py +++ b/debug/accuracy_tools/msprobe/mindspore/debugger/precision_debugger.py @@ -31,7 +31,7 @@ class PrecisionDebugger: return self.initialized = True if not config_path: - config_path = os.path.join(os.path.dirname(__file__), "../../config/config.json") + config_path = os.path.join(os.path.dirname(__file__), "../../config.json") common_config, task_config = parse_json_config(config_path) self.task = common_config.task if self.task == Const.GRAD_PROBE: diff --git a/debug/accuracy_tools/msprobe/mindspore/doc/api_accuracy_checker.md b/debug/accuracy_tools/msprobe/mindspore/doc/api_accuracy_checker.md deleted file mode 100644 index 7bb454b907c4ec9991081afbae87b76940a3d475..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/mindspore/doc/api_accuracy_checker.md +++ /dev/null @@ -1,76 +0,0 @@ -# **MindSpore动态图精度预检工具** - -## 简介 - -MindSpore动态图精度预检工具通过扫描昇腾NPU上用户训练MindSpore模型中所有Mint API，输出精度情况的诊断和分析。工具以模型中所有的Mint API前反向的dump结果为输入，构造相应的API单元测试，将NPU输出与标杆（CPU高精度）比对，计算对应的精度指标，从而找出NPU中存在精度问题的Mint API。 - - -**真实数据/随机生成模式**：精度预检工具支持随机生成模式和真实数据模式，即在预检dump时可以选择由工具构造随机数进行输入获得dump数据或选择获取真实输入数据进行预检dump操作；随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。 - -**工具支持Mindspore版本**：2.4。 - -**工具特性** - -- 落盘数据小。 -- 支持随机生成模式和真实数据模式。 -- 单API测试，排除整网中的累计误差问题。 - -## 预检流程 - -精度预检操作流程如下： - -1. 在NPU和GPU环境下分别安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 -2. 在NPU训练脚本内添加msprobe工具dump接口PrecisionDebugger，采集待预检数据。详见《[精度数据采集](./dump.md)》，注意需要配置level="L1"。 -3. 执行预检操作，查看预检结果文件，分析预检不达标的API。 - -## 预检操作 - - -```bash -msprobe -f mindspore run_ut -api_info ./dump.json -o ./checker_result -``` - -| 参数名称 | 说明 |参数类型 | 是否必选 | -| ---------------------------- | --------------------------------------|---------------------- | ---------------------------------- | -| -api_info或--api_info_file | 指定API信息文件dump.json。 | str | 是 | -| -o或--out_path | 指定预检结果存盘路径，默认“./”。 | str | 否 | - -预检执行结果包括`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`两个文件。`accuracy_checking_result_{timestamp}.csv`是API粒度的，标明每个API是否通过测试。建议用户先查看`accuracy_checking_result_{timestamp}.csv`文件，对于其中没有通过测试的或者特定感兴趣的API，根据其API Name字段在`accuracy_checking_details_{timestamp}.csv`中查询其各个输出的达标情况以及比较指标。详细介绍请参见“**预检结果**”。 - -## 预检结果 - -精度预检生成的`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`文件内容详情如下： - -`accuracy_checking_details_{timestamp}.csv` - -| 字段 | 含义 | -| ------------------- | ------------------------------------------------------------ | -| API Name | API名称。 | -| Bench Dtype | 标杆数据的API数据类型。 | -| Tested Dtype | 被检验数据的API数据类型。 | -| Shape | API的Shape信息。 | -| Cosine | 被检验数据与标杆数据的余弦相似度。 | -| MaxAbsErr | 被检验数据与标杆数据的最大绝对误差。 | -| MaxRelativeErr | 被检验数据与标杆数据的最大相对误差。 | -| Status | API预检通过状态，pass表示通过测试，error表示未通过。 | -| message | 提示信息。 | - -`accuracy_checking_result_{timestamp}.csv` - -| 字段 | 含义 | -| --------------------- | ------------------------------------------------------------ | -| API Name | API名称。 | -| Forward Test Success | 前向API是否通过测试，pass为通过，error为错误。 | -| Backward Test Success | 反向API是否通过测试，pass为通过，error为错误，如果是空白的话代表该API没有反向输出。 | -| Message | 提示信息。 | - -Forward Test Success和Backward Test Success是否通过测试是由`accuracy_checking_details_{timestamp}.csv`中的余弦相似度、最大绝对误差判定结果决定的。具体规则详见“**API预检指标**”。 -需要注意的是`accuracy_checking_details_{timestamp}.csv`中可能存在一个API的前向（反向）有多个输出，那么每个输出记录一行，而在`accuracy_checking_result_{timestamp}.csv`中的结果需要该API的所有结果均为pass才能标记为pass，只要存在一个error则标记error。 - - -## API预检指标 - -API预检指标是通过对`accuracy_checking_details_{timestamp}.csv`中的余弦相似度、最大绝对误差的数值进行判断，得出该API是否符合精度标准的参考指标。详细规则如下： - - - 余弦相似度大于0.99，并且最大绝对误差小于0.0001，标记“pass”，否则标记为“error”。 - diff --git a/debug/accuracy_tools/msprobe/mindspore/doc/compare.md b/debug/accuracy_tools/msprobe/mindspore/doc/compare.md deleted file mode 100644 index 01b4da70b9927ba473cd7db91b7d41e7f6b6c77c..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/mindspore/doc/compare.md +++ /dev/null @@ -1,58 +0,0 @@ -# 精度比对工具 -msprobe精度比对工具主要通过对同一个模型，在两个不同的MindSpore环境下，输入相同的训练数据，在分别得到dump数据后，对这两个dump数据进行全量自动对比，从而快速定位不同版本之间的精度问题。 - -执行精度比对操作需要安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 - -## 命令行方式比对 - -精度比对工具目前使用方式为命令行形式，对MindSpore的dump数据仅支持单卡。 - -请先参见《[精度数据采集](./dump.md)》完成不同环境下MindSpore精度数据的采集。 - -### 操作步骤 - -1. 使用MindSpore进行dump，得到不同框架版本的dump数据。 - -2. 创建比对文件，文件内容及示例请参见“**比对文件**”。 - -3. 执行如下示例命令进行比对： - - ```shell - msprobe -f mindspore compare -i ./compare.json -o ./output -s - ``` - - **完整参数说明** - - | 参数名 | 说明 | 是否必选 | - |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | - | -i或--input_path | 指定比对文件路径。比对文件内容及示例请参见“**比对文件**”。 | 是 | - | -o或--output_path | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是 | - | -s或--stack_mode | 配置stack_mode的开关。仅当**比对文件**配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | - | -c或--compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否 | - | -f或--fuzzy_match | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | - -4. 查看比对结果，请详见PyTorch目录下的《[精度比对工具](../../pytorch/doc/ptdbg_ascend_compare.md)》的“比对结果分析”章节。 - -### 比对文件 - -以在当前目录创建./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文件（单卡场景）。数据类型：str。 | 是 | -| bench_path | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）。数据类型：str。 | 是 | -| stack_path | 配置NPU dump目录下的stack.json文件。数据类型：str。 | 是| -| is_print_compare_log | 配置是否开启日志打屏。可取值True或False，默认为True。数据类型：bool | 否 | \ No newline at end of file diff --git a/debug/accuracy_tools/msprobe/pytorch/api_accuracy_checker/common/config.py b/debug/accuracy_tools/msprobe/pytorch/api_accuracy_checker/common/config.py index 14478dfef2b4874c0e0d063fbc4e4528645240a1..6a2015565ab85d08802d861412552be8701d1376 100644 --- a/debug/accuracy_tools/msprobe/pytorch/api_accuracy_checker/common/config.py +++ b/debug/accuracy_tools/msprobe/pytorch/api_accuracy_checker/common/config.py @@ -1,5 +1,4 @@ import os -import yaml from msprobe.core.common.utils import check_file_or_directory_path from msprobe.core.common.utils import load_yaml from msprobe.pytorch.pt_config import RunUTConfig diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker.md b/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker.md deleted file mode 100644 index bb0f09a0385b41ce9dcccd8181f839ee6c03cf23..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker.md +++ /dev/null @@ -1,313 +0,0 @@ -# **精度预检工具** - -## 简介 - -精度预检工具通过扫描昇腾NPU上用户训练模型中所有API，输出精度情况的诊断和分析。工具通过dump模型中所有的API前反向信息；构造相应的API单元测试，将NPU输出与标杆（CPU高精度）比对，从而计算对应的精度指标，该过程称为run_ut；将NPU环境下dump的预检数据拷贝至GPU环境，同样执行run_ut；最后通过**新精度标准比对法**将NPU和GPU的预检结果进行比对，从而找出NPU中存在精度问题的API。 - -**新精度标准比对法**：依据新精度标准，对不同的API采取不同的比对算法进行比对（包括绝对阈值法，标杆比对法、二进制一致法、ULP误差比对法和双千指标法），最终给定预检判定结果。 - -**真实数据模式**：精度预检工具支持随机生成模式和真实数据模式，即在预检dump时可以选择由工具构造随机数进行输入获得dump数据或选择获取真实输入数据进行预检dump操作；随机生成模式执行效率高，可以快速获得结果，但数据精度低，只能大致判断精度问题；真实数据模式执行效率略低于随机生成模式，但是数据精度高，可以准确判断精度问题。 - -**工具支持PyTorch版本**：1.11/2.0/2.1/2.2。 - -**工具特性** - -- 落盘数据小。 -- 支持随机生成模式和真实数据模式。 -- 单API测试，排除整网中的累计误差问题。 - -## 预检流程 - -精度预检操作流程如下： - -1. 在NPU和GPU环境下分别安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 -2. 在NPU训练脚本内添加msprobe工具dump接口PrecisionDebugger，采集待预检数据。详见《[精度数据采集](./dump.md)》，注意需要配置level="L1"。 -3. 将NPU环境下dump的预检数据拷贝至GPU环境。 -4. 在NPU和GPU环境下分别执行run_ut，生成结果用于最终api_precision_compare操作的输入。详见“**run_ut预检操作**”。 -5. 将NPU和GPU执行run_ut生成的`accuracy_checking_details_{timestamp}.csv`结果文件拷贝至同一环境下。 -6. 运行api_precision_compare.py，输出结果为预检操作的最终结果。详见“**预检结果比对**”。 - -## 预检操作 - -### run_ut预检操作 - -完成待预检数据采集后，仅仅获取了API的输入数据，为了得到NPU vs CPU高精度（标杆）的预检比对结果和GPU vs CPU高精度（标杆）的预检比对结果，还需要进行run_ut操作。 - -run_ut预检操作包括如下场景： - -- 使用run_ut.py执行预检：run_ut.py适用于数据量较小的单卡场景。 -- 使用multi_run_ut.py执行多线程预检：multi_run_ut.py适用于数据量较大的大模型场景。 - -#### 使用run_ut.py执行预检 - -1. 将API信息输入给run_ut模块运行精度检测并比对，运行如下命令： - - ```bash - msprobe -f pytorch run_ut -api_info ./dump.json - ``` - - | 参数名称 | 说明 | 是否必选 | - | ---------------------------- | ------------------------------------------------------------ | ---------------------------------- | - | -api_info或--api_info_file | 指定API信息文件dump.json。 | 是 | - | -save_error_data | 保存精度未达标的API输入输出数据。 | 否 | - | -o或--out_path | 指定run_ut执行结果存盘路径，默认“./”（相对于run_ut的路径）。 | 否 | - | | | | - | -j或--jit_compile | 开启jit编译。 | 否 | - | -d或--device | 指定Device ID，选择UT代码运行所在的卡，默认值为0。 | 否 | - | -csv_path或--result_csv_path | 指定本次运行中断时生成的`accuracy_checking_result_{timestamp}.csv`文件路径，执行run_ut中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的`accuracy_checking_result_{timestamp}.csv`文件。详见“**断点续检**”。 | run_ut操作中断后继续执行场景下必选 | - | -f或--filter_api | 过滤模型中除最大值和最小值以外其他参数和结构相同的API。适用于模型较大且重复API较多的场景。 | 否 | - | -config或--config_path | 指定预检操作过程中的额外配置（包括黑名单、白名单等）的[config.json](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe/config)文件，默认未配置。config.json文件的配置可参考《[配置文件说明](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/msprobe/config/README.md#pytorch场景task配置为run_ut)》。 | 否 | - - run_ut执行结果包括`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`两个文件。`accuracy_checking_result_{timestamp}.csv`是API粒度的，标明每个API是否通过测试。建议用户先查看`accuracy_checking_result_{timestamp}.csv`文件，对于其中没有通过测试的或者特定感兴趣的API，根据其API name字段在`accuracy_checking_details_{timestamp}.csv`中查询其各个输出的达标情况以及比较指标。详细介绍请参见“**预检结果**”。 - -2. （可选）如果需要保存比对不达标的输入和输出数据，可以在run_ut执行命令结尾添加-save_error_data，例如： - - ```bash - msprobe -f pytorch run_ut -api_info ./dump.json -save_error_data - ``` - - 数据默认会存盘到'./ut_error_data{timestamp}'路径下（相对于启动run_ut的路径），有需要的话，用户可以通过error_data_path参数来配置保存路径，error_data_path参数在[config.json](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe/config)文件或config.yaml文件配置，config.json文件需要在run_ut操作时通过-config参数指定，config.yaml文件详见“**config.yaml文件说明**”。 - -#### 使用multi_run_ut.py执行多线程预检 - -multi_run_ut.py脚本，可以并行执行多个run_ut操作，从而降低预检耗时。 - -命令示例如下： - -```bash -msprobe -f pytorch multi_run_ut -api_info ./dump.json -n 32 -d 0 1 2 3 -``` - -| 参数名称 | 说明 | 是否必选 | -| ---------------------------- | ------------------------------------------------------------ | ---------------------------------- | -| -api_info或--api_info_file | 指定API信息文件dump.json。 | 是 | -| -save_error_data | 保存精度未达标的API输入输出数据。 | 否 | -| -o或--out_path | 指定run_ut执行结果存盘路径，默认“./”（相对于run_ut的路径）。 | 否 | -| -j或--jit_compile | 开启jit编译。 | 否 | -| -n | 同时执行run_ut线程的数量，默认为8，最大支持64，但每个Device最大支持8个线程，当指定多个线程和多个Device时，则线程数在每张卡上均分。 | 否 | -| -d或--device | 指定Device ID，选择UT代码运行所在的卡，默认值为0，支持同时指定0~7，共8个Device。 | 否 | -| -csv_path或--result_csv_path | 指定本次运行中断时生成的`accuracy_checking_result_{timestamp}.csv`文件路径，执行run_ut中断时，若想从中断处继续执行，配置此参数即可。需要指定为上次中断的`accuracy_checking_result_{timestamp}.csv`文件。详见“**断点续检**”。 | run_ut操作中断后继续执行场景下必选 | -| -f或--filter_api | 过滤模型中除最大值和最小值以外其他参数和结构相同的API。适用于模型较大且重复API较多的场景。 | 否 | - -#### 断点续检 - -精度预检run_ut过程中，若因环境、数据量过大等原因导致预检进程中断，那么当用户解决这些问题后，重新执行run_ut操作，可以通过断点续检操作继续前面未完成的预检，会在-csv_path指定的`accuracy_checking_result_{timestamp}.csv`文件以及对应的`accuracy_checking_details_{timestamp}.csv`文件中继续写入后续的结果，不会重新创建结果文件。 - -须指定为上次预检中断的`accuracy_checking_result_{timestamp}.csv`文件。请勿修改`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`文件名，包括时间戳，否则断点续检会因无法识别到文件名而失败。 - -断点续检操作通过如下命令执行： - -```bash -msprobe -f pytorch run_ut -api_info ./dump.json -csv_path /home/xxx/ut/accuracy_checking_result_{timestamp}.csv -``` - -#### API预检黑名单和白名单 - -run_ut过程支持API预检黑名单和白名单，通过如下文件配置black_list（黑名单）或white_list（白名单）参数来指定不需要或需要预检的API名称： - -- 配置[config.json](https://gitee.com/ascend/mstt/tree/master/debug/accuracy_tools/msprobe/config)文件，config.json文件需要在run_ut操作时通过-config参数指定。 -- 配置config.yaml文件，详见“**config.yaml文件说明**”。 - -config.json文件的优先级高于config.yaml文件，即执行config.json文件时，config.yaml文件的配置不生效。 - -### config.yaml文件说明 - -config.yaml文件可以通过配置参数来控制dump和run_ut操作的白名单、黑名单等功能。操作步骤如下： - -1. 查找msprobe工具安装路径。 - - ```bash - pip show mindstudio-probe - ``` - - 输出结果如下示例： - - ```bash - Name: mindstudio-probe - Version: 1.0 - Summary: This is a pytorch precision comparison tools - Home-page: - Author: - Author-email: - License: - Location: /home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages - Requires: numpy, openpyxl, pandas, pyyaml, rich, tqdm, wheel - Required-by: - ``` - - Location字段为msprobe工具的安装路径，那么config.yaml文件位置为/home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml - -2. 进入config.yaml文件 - - ```bash - vi /home/xx/anaconda3/envs/pt21py38/lib/python3.8/site-packages/msprobe/pytorch/api_accuracy_checker/config.yaml - ``` - -3. 修改config.yaml文件参数。 - - ```yaml - white_list: [] - black_list: [] - error_data_path: './' - precision: 14 - ``` - - | 参数名称 | 说明 | 是否必选 | - | --------------- | ------------------------------------------------------------ | -------- | - | white_list | API dump白名单，仅对指定的API进行dump。参数示例：white_list=["conv1d", "conv2d"]。默认未配置白名单，即dump全量API数据。 | 否 | - | black_list | API dump黑名单，被指定的API不进行dump。参数示例：black_list=["conv1d", "conv2d"]。默认未配置黑名单，即dump全量API数据。 | 否 | - | error_data_path | 配置保存精度未达标的API输入输出数据路径。参数示例"error_data_path": "./"。默认为当前路径。 | 否 | - | precision | 浮点数表示位数，默认取小数点后14位。 | 否 | - - 说明：white_list和black_list同时配置时，二者配置的API名单若无交集，则白名单生效，若API名单存在交集，则白名单排除的部分以及交集的API不进行dump。 - -## 预检结果 - -精度预检生成的`accuracy_checking_result_{timestamp}.csv`和`accuracy_checking_details_{timestamp}.csv`文件示例如下： - -可以通过先查看`accuracy_checking_result_{timestamp}.csv`文件的Forward Test Success和Backward Test Success，判断是否存在未通过测试的API，再查看`accuracy_checking_details_{timestamp}.csv`文件的API详细达标情况，API达标情况介绍请参见“**API预检指标**”。 - -`accuracy_checking_result_{timestamp}.csv` - -![accuracy_checking_result](img/accuracy_checking_result.png) - -| 字段 | 含义 | -| --------------------- | ------------------------------------------------------------ | -| API name | API名称。 | -| Forward Test Success | 前向API是否通过测试，pass为通过，warning为待观察，error为错误。 | -| Backward Test Success | 反向API是否通过测试，pass为通过，warning为待观察，error为错误，如果是空白的话代表该API没有反向输出。 | -| Message | 提示信息。 | - -该结果为中间结果，仅作为参考，建议完成“**预检结果比对**”后查看比对结果。该结果后续将会删除。 - -Forward Test Success和Backward Test Success是否通过测试是由`accuracy_checking_details_{timestamp}.csv`中的余弦相似度、最大绝对误差、双百双千双万指标判定结果决定的。 - -需要注意的是`accuracy_checking_details_{timestamp}.csv`中可能存在一个API的前向（反向）有多个输出，那么每个输出记录一行，而在`accuracy_checking_result_{timestamp}.csv`中的结果需要该API的所有结果均为pass才能标记为pass，只要存在一个error则标记error，仅存在waring和pass且不存在error标记waring。 - -`accuracy_checking_details_{timestamp}.csv` - -![accuracy_checking_details](img/accuracy_checking_details.png) - -| 字段 | 含义 | -| ------------------- | ------------------------------------------------------------ | -| API name | NPU或GPU下的API名称。 | -| Bench Dtype | 标杆数据的API数据类型。 | -| DEVICE Dtype | NPU或GPU数据的API数据类型。 | -| Shape | API的Shape信息。 | -| 余弦相似度 | NPU或GPU数据与标杆数据的余弦相似度。 | -| 最大绝对误差 | NPU或GPU数据与标杆数据的最大绝对误差。 | -| 双百指标 | 双百精度指标。是指NPU或GPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差小于百分之一的个数占总元素个数的比例。测试通过标准为相对误差大于百分之一的个数占总元素个数的比例小于百分之一。 | -| 双千指标 | 双千精度指标。是指NPU或GPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。 | -| 双万指标 | 双万精度指标。是指NPU或GPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差小于万分之一的个数占总元素个数的比例。测试通过标准为相对误差大于万分之一的个数占总元素个数的比例小于万分之一。 | -| 二进制一致错误率 | NPU或GPU数据中每个Tensor精度不一致的数值的数量与Tensor中数值数量的比值。只有数据是builtin类型（bool、int、float、str）、torch.bool和torch的int类型或者在新精度标准中使用二进制一致算法进行比对的API才会展示。 | -| 误差均衡性 | NPU或GPU数据与标杆数据精度差的上下浮动情况。 | -| 均方根误差 | NPU或GPU数据与标杆数据的均方根误差。 | -| 小值域错误占比 | NPU或GPU Tensor中与标杆的绝对误差大于错误阈值的小值在小值域（小值的总数量）中的占比。判断为小值以及绝对误差的错误阈值见“**小值域阈值**”。 | -| 相对误差最大值 | NPU或GPU数据与标杆数据相对误差的最大值。 | -| 相对误差平均值 | NPU或GPU数据与标杆数据相对误差的平均值。 | -| inf/nan错误率 | NPU与标杆inf/nan计算不一致的元素个数占总元素的个数比例。 | -| 相对误差错误率 | NPU与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。 | -| 绝对误差错误率 | NPU与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。 | -| ULP误差最大值 | NPU或GPU数据与标杆数据ULP误差的最大值（取绝对值后）。 | -| ULP误差平均值 | NPU或GPU数据与标杆数据ULP误差的平均值（取绝对值后）。 | -| ULP误差大于阈值占比 | NPU或GPU数据与标杆数据的ULP误差（取绝对值后）大于阈值（当NPU或GPU数据类型为float16或bfloat16时，阈值为1；当NPU或GPU数据类型为float32时，阈值为32）的元素个数占总元素的个数比例。 | -| Status | API预检通过状态，pass表示通过测试，error表示未通过，warning表示测试未通过双千或双万精度指标，SKIP表示该API的某个参数的反向不要计算梯度，所以没有任何计算过程，其他信息均为空。 | -| message | 提示信息。 | - -### 小值域阈值 - -判定为小值的阈值为： - -- torch.float32：e-6 -- torch.float16：e-3 -- torch.bfloat16：e-3 - -小值域的绝对误差阈值为： - -- torch.float32：e-9 -- torch.float16：e-5 -- torch.bfloat16：e-5 - -### API预检指标 - -API预检指标是通过对`accuracy_checking_details_{timestamp}.csv`中的余弦相似度、最大绝对误差双百、双千、双万精度指标的数值进行判断，得出该API是否符合精度标准的参考指标。 - -API预检通过测试，则在`accuracy_checking_details_{timestamp}.csv`文件中的“Status”列标记“pass”，否则标记“error”或“warning”，详细规则如下： - -1. 余弦相似度 > 0.99：≤ 0.99为不达标，标记“error”，> 0.99达标，进行下一步； -2. 最大绝对误差 ＜ 0.001：＜ 0.001达标，标记“pass”，≥ 0.001为不达标，进行下一步； -3. 双百、双千、双万精度指标： - - 对于float16和bfloat16数据：双百指标不通过，标记“error”；双百指标通过，双千指标不通过，标记“warning”；双百、双千指标均通过，标记“pass”。 - - 对于float32和float64数据：双千指标不通过，标记“error”；双千指标通过，双万指标不通过，标记“warning”；双千、双万指标均通过，标记“pass”。 - -4. 在`accuracy_checking_result_{timestamp}.csv`中以“Forward Test Success”和“Backward Test Success”字段统计该算子前向反向输出的测试结果，对于标记“pass”的算子，则在`accuracy_checking_result_{timestamp}.csv`中标记“TRUE”表示测试通过，对于标记“error”或“warning”的算子，则在`accuracy_checking_result_{timestamp}.csv`中标记“FALSE”表示测试不通过。由于一个算子可能有多个前向或反向的输入或输出，那么该类算子的输入或输出中必须全为“pass”，才能在`accuracy_checking_result_{timestamp}.csv`中标记“TRUE”，只要有一个输入或输出标记“error”或“warning”，那么在`accuracy_checking_result_{timestamp}.csv`中标记“FALSE”。 - -## 预检结果比对 - -需要同时获取NPU和GPU环境下run_ut操作的预检结果`accuracy_checking_details_{timestamp}.csv`文件。执行如下命令进行NPU和GPU预检结果的比对： - -```bash -msprobe -f pytorch api_precision_compare -npu /home/xxx/npu/accuracy_checking_details_{timestamp}.csv -gpu /home/xxx/gpu/accuracy_checking_details_{timestamp}.csv -o /home/xxx/ -``` - -| 参数名称 | 说明 | 是否必选 | -| -------------------- | ------------------------------------------------------------ | -------- | -| -npu或--npu_csv_path | NPU预检结果`accuracy_checking_details_{timestamp}.csv`文件路径。默认从当前目录下识别该文件。 | 否 | -| -gpu或--gpu_csv_path | GPU预检结果`accuracy_checking_details_{timestamp}.csv`文件路径。默认从当前目录下识别该文件。 | 否 | -| -o或--out_path | 指定api_precision_compare.py执行结果存盘路径，默认为当前目录。 | 否 | - -执行完成后输出`api_precision_compare_result_{timestamp}.csv`和`api_precision_compare_details_{timestamp}.csv`文件。文件示例如下： - -可以通过先查看`api_precision_compare_result_{timestamp}.csv`文件的Forward Test Success和Backward Test Success，判断是否存在未通过测试的API，再查看`api_precision_compare_details_{timestamp}.csv`文件的API详细达标情况。 - -`api_precision_compare_result_{timestamp}.csv` - -![api_precision_compare_result](img/api_precision_compare_result.png) - -| 字段 | 含义 | -| --------------------- | ------------------------------------------------------------ | -| API name | API名称。 | -| Forward Test Success | 前向API是否通过测试，pass为通过，warning为待观察，error为错误，skip表示该API的数据类型不支持使用新精度标准进行比对，如float64。 | -| Backward Test Success | 反向API是否通过测试，pass为通过，warning为待观察，error为错误，如果是空白的话代表该API没有反向输出，skip表示该API的数据类型不支持使用新精度标准进行比对，如float64。 | -| Message | 提示信息。 | - -Forward Test Success和Backward Test Success是否通过测试是由`api_precision_compare_details_{timestamp}.csv`中的各个指标判定结果决定的。需要注意的是`api_precision_compare_details_{timestamp}.csv`中可能存在一个API的前向（反向）有多个输出，那么每个输出记录一行，而在`api_precision_compare_result_{timestamp}.csv`中的结果需要该API的所有结果均为pass才能标记为pass，只要存在一个error则标记error，仅存在warning和pass且不存在error标记warning。 - -`api_precision_compare_details_{timestamp}.csv` - -![api_precision_compare_details](img/api_precision_compare_details.png) - -| 字段 | 含义 | -| ------------------------ | ------------------------------------------------------------ | -| API name | NPU或GPU下的API名称。 | -| 小值域错误比值 | NPU与CPU的小值域的错误比率/GPU与CPU的小值域的错误比率。标杆比对法指标。 | -| 小值域错误判定结果 | 小值域错误比值小于等于1标记为pass，1~2之间标记为waring，大于2标记为error。 | -| 均方根误差比值 | NPU与CPU的均方根误差/GPU与CPU的均方根误差。标杆比对法指标。 | -| 均方根误差判定结果 | 均方根误差比值小于等于1标记为pass，1~2之间标记为waring，大于2标记为error。 | -| 相对误差最大值比值 | NPU与CPU的相对误差最大值/GPU与CPU的相对误差最大值。标杆比对法指标。 | -| 相对误差最大值判定结果 | 相对误差最大值比值小于等于1标记为pass，1~10之间标记为waring，大于10标记为error。 | -| 相对误差平均值比值 | NPU与CPU的相对误差的平均值/GPU与CPU的相对误差的平均值。标杆比对法指标。 | -| 相对误差平均值判定结果 | 相对误差平均值比值小于等于1标记为pass，1~2之间标记为waring，大于2标记为error。 | -| 误差均衡性比值 | NPU与CPU的误差均衡性/GPU与CPU的误差均衡性。标杆比对法指标。 | -| 误差均衡性判定结果 | 误差均衡性比值小于等于1标记为pass，1~2之间标记为waring，大于2标记为error。该字段暂不参与api_precision_compare_result的结果判定。 | -| inf/nan错误率 | NPU与标杆inf/nan计算不一致的元素个数占总元素的个数比例。绝对阈值法指标。 | -| inf/nan判定结果 | inf/nan错误率判定结果，等于0标记为pass，其余情况标记为error。 | -| 相对误差错误率 | NPU与标杆的正常值计算相对误差，其大于错误阈值的元素个数占正常值元素个数的比例。绝对阈值法指标。 | -| 相对误差判定结果 | 相对误差错误率判定结果，等于0标记为pass，其余情况标记为error。 | -| 绝对误差错误率 | NPU与标杆的小值计算绝对误差，其大于错误阈值的元素个数占小值元素个数的比例。绝对阈值法指标。 | -| 绝对误差判定结果 | 绝对误差错误率判定结果，等于0标记为pass，其余情况标记为error。 | -| 二进制一致错误率 | NPU或GPU数据中每个Tensor精度不一致的数值的数量与Tensor中数值数量的比值。只有数据是builtin类型（bool、int、float、str）、torch.bool和torch的int类型或者在新精度标准中使用二进制一致算法进行比对的API才会展示。二进制一致法指标。 | -| 二进制一致错误率判定结果 | 二进制一致错误率判定结果，等于0标记为pass，其余情况标记为error。 | -| ULP误差平均值 | NPU数据与标杆数据ULP误差的平均值（取绝对值后）。ULP误差比对法指标。 | -| ULP误差大于阈值占比 | NPU数据与标杆数据的ULP误差（取绝对值后）大于阈值（当NPU数据类型为float16或bfloat16时，阈值为1；当NPU数据类型为float32时，阈值为32）的元素个数占总元素的个数比例。ULP误差比对法指标。 | -| ULP误差大于阈值占比比值 | NPU与CPU的ULP误差大于阈值占比/GPU与CPU的ULP误差大于阈值占比。ULP误差比对法指标。 | -| ULP误差判定结果 | ULP误差判定结果。
当NPU或GPU数据类型是float16或bfloat16时，以下两条标准满足其一标记为pass，否则标记为error：
NPU ULP误差大于阈值占比小于0.001；
NPU ULP误差大于阈值占比小于GPU ULP误差大于阈值占比。
当NPU或GPU数据类型是float32时，以下三条标准满足其一标记为pass，否则标记为error：
NPU ULP误差平均值小于64；
NPU ULP误差大于阈值占比小于0.05；
NPU ULP误差大于阈值占比小于GPU ULP误差大于阈值占比。 | -| 双千指标 | 双千精度指标。是指NPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差小于千分之一的个数占总元素个数的比例。测试通过标准为相对误差大于千分之一的个数占总元素个数的比例小于千分之一。仅conv1d和conv2d使用该指标。双千指标法指标。 | -| 双千指标判定结果 | 双千指标判定结果。双千指标大于0.999标记为pass，否则标记为error。 | -| 比对结果 | 综合所有指标的最终结果。如果比对指标中有error，则标记为error；有warning，则标记为warning；否则标记为pass。 | -| 比对算法 | API使用的比对算法，为标杆比对法、二进制一致法、绝对阈值法和ULP误差比对法中的一种。 | -| Message | 提示信息。当前提示该API比对结果为error或warning时对应不符合标准的指标。 | - -# FAQ - -[FAQ](./FAQ.md) diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker_online.md b/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker_online.md deleted file mode 100644 index 5050689a3c455c3f39ba9178ff53e1f0a29d9de2..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/pytorch/doc/api_accuracy_checker_online.md +++ /dev/null @@ -1,187 +0,0 @@ -# 在线精度预检 - -为了应对大模型场景下，通过离线预检方式dump API输入输出数据导致的存储资源紧张问题，提供在线精度预检功能。本功能实现在执行NPU训练操作的过程中，通过TCP/IP协议在NPU -Host与GPU Host设备间建立连接，将NPU上对应API的输入数据在GPU设备上运行，将两份输出数据进行比对，得到预检比对结果，从而减少数据dump的步骤，降低存储资源的占用。 - -## 在线精度预检流程 - -在线精度预检当前支持**局域网场景**和**共享存储场景**，请根据不同的场景选择对应的配置。 - -在线精度预检操作流程如下： - -1. 准备GPU和NPU可正常运行的训练环境，PyTorch版本大于等于2.0，并保证两台Host在同一局域网内可正常通信或能通过共享存储进行通信。 -2. GPU和NPU Host设备上同时安装msprobe工具，详见《[MindStudio精度调试工具](./../../README.md) - 》，其中在线预检要多安装twisted、pyOpenSSL依赖，该依赖为Python模块。 -3. 分别配置GPU侧、NPU侧的config.json文件。 -4. 在GPU侧运行msprobe -f pytorch run_ut -config ./config.json。 -5. 在NPU侧配置训练脚本。 -6. 在NPU侧执行训练。 - -## 在线精度预检操作指导 - -### 配置config.json文件 - -安装完成预检工具后，需要分别在GPU和NPU环境下分别配置config.json。其中需要重点关注文件中的is_online、is_benchmark_device、host和port参数的配置，保障在线预检时GPU和NPU两台设备间的通信正常。 - -#### GPU侧在线预检配置说明 - -| 参数名称 | 说明 | 是否必选 | -|-----------------|-----------------------------------------------------------------------------------------------------------------------|------| -| task | 任务名称，str类型，配置为run_ut表示预检任务。通过其他字段is_online判断离线预检、在线预检任务。 | 是 | -| white_list | 预检的API白名单，list[str]类型。参数示例：white_list=["conv1d", "conv2d"]。默认未配置白名单，即预检全量API数据。 | 否 | -| black_list | 预检的API黑名单，list[str]类型。参数示例：white_list=["conv1d", "conv2d"]。默认未配置黑名单，即预检全量API数据。 | 否 | -| error_data_path | 配置保存精度未达标的API输入输出数据路径，str类型。在线预检模式下该参数不生效。 | 否 | -| is_online | 在线预检模式开关，bool类型，可取值True（开启）、False（关闭），默认关闭。 | 是 | -| nfs_path | 在线预检模式共享存储目录路径，str类型，用于GPU设备和NPU设备间进行通信。配置该参数后host和port不生效。 | 否 | -| host | 在线预检模式局域网场景信息接收端IP，str类型，用于GPU设备和NPU设备间进行通信，GPU侧配置为本机地址127.0.0.1或本机局域网IP。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | -| port | 在线预检模式局域网场景信息接收端端口号，int类型，用于GPU设备和NPU设备间进行通信，GPU侧配置为本机可用端口。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | -| rank_list | 指定在线预检的Rank ID，默认值为[0]，list[int]类型，应配置为大于等于0的整数，且须根据实际卡的Rank ID配置，若所配置的值大于实际训练所运行的卡的Rank ID，则在线预检输出数据为空。GPU和NPU须配置一致。 | 是 | - -#### NPU侧在线预检配置说明 - -| 参数名称 | 说明 | 是否必选 | -|------------------|--------------------------------------------------------------------------------------------------------|------| -| task | 任务名称，str类型，配置为tensor表示dump API统计信息和完全复刻整网的API运行情况的真实数据。通过字段onlin_run_ut判断是否使用在线预检功能。 | 是 | -| dump_path | dump路径，str类型，配置为合法路径即可，兼容tensor任务静态检查 | 是 | -| level | dump级别，str类型，在线预检时配置为L1，表示dump API级精度数据。在线预检可不配置，默认取值L1。 | 是 | -| rank | 指定对某张卡上的数据进行dump，list[int]类型，默认未配置(表示dump所有卡的数据)，需要与GPU侧配置项rank_list保持一致。 | 否 | -| step | 指定dump某个step的数据，list[int]类型，默认未配置，表示dump所有step的数据。dump特定step时，须指定为训练脚本中存在的step。 | 否 | -| seed | 随机种子数，int类型，默认值为1234。通过固定随机数保证模型的输入或输出一致。 | 否 | -| is_deterministic | 确定性计算模式，bool类型，可取值true（开启）或false（关闭），默认关闭。 | 否 | -| scope | dump范围，list[str]类型，默认未配置（list也未配置时师表dump所有api的额数据），配置方式参考[《config配置文件说明》](./../../config/README.md) | 否 | -| list | 自定义dump范围，list[str]类型，默认未配置（scope也未配置时表示dump所有api的数据），配置方式参考[《config配置文件说明》](./../../config/README.md) | 否 | -| online_run_ut | 在线预检模式开关，bool类型，可取值True（开启）、False（关闭），默认关闭。 | 是 | -| nfs_path | 在线预检模式共享存储目录路径，str类型，用于GPU设备和NPU设备间进行通信。配置该参数后host和port不生效。 | 否 | -| host | 在线预检模式局域网场景信息接收端IP，str类型，用于GPU设备和NPU设备间进行通信，NPU侧须配置为GPU侧的局域网IP地址。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | -| port | 在线预检模式局域网场景信息接收端端口号，int类型，用于GPU设备和NPU设备间进行通信，NPU侧须配置为GPU侧的端口号。局域网场景时，不能配置nfs_path参数，否则局域网场景不生效。 | 否 | - -#### 局域网场景配置示例 - -若复制下列示例，请删除注释后使用。 - -GPU侧： - -```json -{ - "task": "run_ut", - "run_ut": { - "white_list": [], - "black_list": [], - "error_data_path": "./", - "is_online": true, - "nfs_path": "", - "host": "127.0.0.1", - "port": 59208, - "rank_list": [0] - } -} -``` - -NPU侧： - -```json -{ - "task": "tensor", - "dump_path": "./dump_path", - "rank": [0], - "step": [0], - "level": "L1", - "seed": 1234, - "is_deterministic": true, - "tensor": { - "scope": [], - "list": [], - "online_run_ut": true, - "nfs_path": "", - "host": "xx.xx.xx.x", - "port": 59208 - } -} -``` - -#### 共享存储场景配置示例 - -若复制下列示例，请删除注释后使用。 - -GPU侧： - -```json -{ - "task": "run_ut", - "run_ut": { - "white_list": [], - "black_list": [], - "error_data_path": "./", - "is_online": true, - "nfs_path": "/nfs/xxx/data", - "host": "", - "port": -1, - "rank_list": [0] - } -} -``` - -NPU侧： - -```json -{ - "task": "tensor", - "dump_path": "./dump_path", - "rank": [0], - "step": [0], - "level": "L1", - "seed": 1234, - "is_deterministic": true, - "tensor": { - "scope": [], - "list": [], - "online_run_ut": true, - "nfs_path": "/nfs/xxx/data", - "host": "", - "port": -1 - } -} -``` - -### 在GPU侧运行run_ut - -由于GPU侧为通信接收端，需先于NPU侧执行run_ut操作，命令如下： - -```bash -msprobe -f pytorch run_ut -config ./config.json -``` - -GPU侧配置好config.json文件后执行run_ut命令，此时GPU处于预检等待状态： - -- 局域网场景：当NPU侧启动训练后将预检的API输入和输出数据发送到GPU侧时，GPU启动预检操作。 -- 共享存储场景：当NPU侧启动训练后将预检的API输入和输出数据发送到共享存储时，GPU启动预检操作。 - -### 在NPU侧配置训练脚本 - -在NPU训练脚本中添加如下代码以获取run_ut操作的预检API输入和输出数据： - -```python -from msprobe.pytorch import PrecisionDebugger - -debugger = PrecisionDebugger("config.json") -... - -debugger.start() - -... - -debugger.stop() -debugger.step() -``` - -### 在NPU侧执行训练脚本 - -配置完NPU侧训练脚本后即可执行训练脚本，命令示例如下： - -```bash -bash train.sh -``` - -训练脚本执行完毕后，在GPU侧dump_path目录下生成比对结果文件，详细介绍请参见《[精度预检工具](./api_accuracy_checker.md)》中的” -**预检结果**“。 - diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_compare.md b/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_compare.md deleted file mode 100644 index ffff1f44f7c374c5f63e57308044d0d0fe3571a6..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_compare.md +++ /dev/null @@ -1,243 +0,0 @@ -# **精度比对工具** - -## 总体说明 - -- 本节主要介绍通过命令行方式和比对函数方式进行CPU或GPU与NPU的精度数据比对，执行精度比对操作前需要先完成CPU或GPU与NPU的精度数据dump，参见《[精度数据采集](./dump.md)》。 - -- 训练精度一体化工具msprobe，使用子命令compare进行比对，可支持单卡和多卡场景的精度数据比对。 - -- 比对函数均通过单独创建精度比对脚本执行，可支持单卡和多卡场景的精度数据比对。 - -- 工具性能：比对数据量较小时（参考值单份文件小于10GB），参考比对速度0.1GB/s；比对数据量较大时，参考比对速度0.3GB/s。 推荐环境配置：独占环境，CPU核心数192，固态硬盘（IO速度参考：固态硬盘 > 500MB/s，机械硬盘60 ~ 170MB/s）。 - - 用户环境性能弱于标准约束或非独占使用的比对速度酌情向下浮动。比对速度的计算方式：两份比对文件大小/比对耗时。 - -## 约束 - -- NPU自研API，在CPU或GPU若没有对应的API，该API的dump数据不比对。 -- NPU与CPU或GPU的计算结果误差可能会随着模型的执行不断累积，最终会出现同一个API因为输入的数据差异较大而无法比对的情况。 -- CPU或GPU与NPU中两个相同的API会因为调用次数不同导致无法比对或比对到错误的API，不影响整体运行，该API忽略。 - -## 命令行方式比对 - -将CPU或GPU与NPU的dump文件进行比对，支持单卡和多卡，可同时比对多卡的dump数据。多机场景需要每个设备单独执行比对操作。 - -请先参见《[精度数据采集](./dump.md)》完成CPU或GPU与NPU的精度数据dump。 - -### 操作步骤 - -1. 创建比对文件，文件内容及示例请参见“**比对文件**”。 - -2. 执行如下示例命令进行比对： - - ```shell - msprobe -f pytorch compare -i ./compare.json -o ./output -s - ``` - - **完整参数说明** - - | 参数名 | 说明 | 是否必选 | - |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | - | -i或--input_path | 指定比对文件路径。比对文件内容及示例请参见“**比对文件**”。 | 是 | - | -o或--output_path | 配置比对结果文件存盘目录。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。 | 是 | - | -s或--stack_mode | 配置stack_mode的开关。仅当**比对文件**配置"stack_path"需要开启。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | - | -c或--compare_only | 仅比对开关。未配置默认关闭仅比对，使用自动精度分析，工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。该参数默认未配置，使用自动精度分析，通过配置该参数开启仅比对，关闭自动精度分析，仅输出比对结果表格。 | 否 | - | -f或--fuzzy_match | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。通过直接配置该参数开启，默认未配置，表示关闭。 | 否 | - -3. 查看比对结果，请参见“**比对结果分析**”。 - -### 比对文件 - -以在当前目录创建./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 - } - ``` - -- 多卡场景示例 - - ```json - { - "npu_path": "./npu_dump/step0", - "bench_path": "./bench_dump/step0", - "is_print_compare_log": true - } - ``` - -**参数说明** - -| 参数名 | 说明 | 是否必选 | -| -------------------- | ------------------------------------------------------------ | ------------------ | -| npu_path | 配置NPU环境下的dump.json文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是 | -| bench_path | 配置CPU、GPU或NPU环境下的dump.json文件（单卡场景）或真实数据目录（多卡场景）。数据类型：str。 | 是 | -| stack_path | 配置NPU dump目录下的stack.json文件。数据类型：str。 | 单卡必选，多卡不选 | -| is_print_compare_log | 配置是否开启日志打屏。可取值True或False。数据类型：bool | 否 | - -## 比对函数方式比对 - -### compare_distributed - -**功能说明** - -将CPU或GPU与NPU的dump文件进行比对，支持单卡和多卡，可同时比对多卡的dump数据。多机场景需要每个设备单独执行比对操作。可自动检索和匹配对应卡和进程所dump的数据文件，再调用compare进行比对。单机单卡时与compare函数二选一。 - -**函数原型** - -```Python -compare_distributed(npu_dump_dir, bench_dump_dir, output_path, **kwargs) -``` - -**参数说明** - -| 参数名 | 说明 | 是否必选 | -| -------------- | ------------------------------------------------------------ | -------- | -| npu_dump_dir | 配置NPU环境下的dump目录。dump数据目录须指定到step级。参数示例：'./npu_dump/step0'。数据类型：str。 | 是 | -| bench_dump_dir | 配置CPU、GPU或NPU环境下的dump目录。参数示例：'./gpu_dump/step0'。数据类型：str。 | 是 | -| output_path | 配置比对结果文件存盘目录。需要预先创建output_path目录。参数示例：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_rank{npu_ID}-rank{cpu/gpu/npu_ID}_{timestamp}.xlsx`。数据类型：str。 | 是 | -| **kwargs | 支持compare的所有可选参数。 | 否 | - -**函数示例** - -创建比对脚本，例如compare_distributed.py，拷贝如下代码，具体参数请根据实际环境修改。 - -```Python -from msprobe.pytorch import * -compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output') -``` - -dump数据目录须指定到step级。 - -### compare - -**功能说明** - -将CPU或GPU与NPU的dump文件进行比对，仅支持单机单卡。 - -**函数原型** - -```Python -compare(input_param, output_path, stack_mode=False, auto_analyze=True, fuzzy_match=False) -``` - -**参数说明** - -| 参数名 | 说明 | 是否必选 | -| ------------ | ------------------------------------------------------------ | -------- | -| input_param | 配置dump数据文件及目录。数据类型：dict。配置参数包括：
"npu_json_path"：指定NPU dump目录下的dump.json文件。参数示例："npu_json_path": "./npu_dump/dump.json"。必选。
"bench_json_path"：指定CPU、GPU或NPU dump目录下的dump.json文件。参数示例："bench_json_path": "./bench_dump/dump.json"。必选。
"stack_json_path"：指定NPU dump目录下的stack.json文件。参数示例："stack_json_path": "./npu_dump/stack.json"。可选。
"is_print_compare_log"：配置是否开启日志打屏。可取值True或False。可选。 | 是 | -| output_path | 配置比对结果文件存盘目录。参数示例：'./output'。文件名称基于时间戳自动生成，格式为：`compare_result_{timestamp}.xlsx`。数据类型：str。 | 是 | -| stack_mode | 配置stack_mode的开关。仅当配置"stack_json_path"需要开启。可取值True或False，参数示例：stack_mode=True，默认为False。数据类型：bool。 | 否 | -| auto_analyze | 自动精度分析，开启后工具自动针对比对结果进行分析，识别到第一个精度不达标节点（在比对结果文件中的“Accuracy Reached or Not”列显示为No），并给出问题可能产生的原因（打屏展示并生成advisor_{timestamp}.txt文件）。可取值True或False，参数示例：auto_analyze=False，默认为True。数据类型：bool。 | 否 | -| fuzzy_match | 模糊匹配。开启后，对于网络中同一层级且命名仅调用次数不同的API，可匹配并进行比对。可取值True或False，参数示例：fuzzy_match=True，默认为False。数据类型：bool。 | 否 | - -**函数示例** - -单机单卡场景下创建比对脚本，例如compare.py，拷贝如下代码，具体参数请根据实际环境修改。 - -```Python -from msprobe.pytorch import compare -input_param={ -"npu_json_path": "./npu_dump/dump.json", -"bench_json_path": "./bench_dump/dump.json", -"stack_json_path": "./npu_dump/stack.json", -"is_print_compare_log": True -} -compare(input_param, output_path="./output", stack_mode=True) -``` - -### 统计量比对 - -若使用**compare**或**compare_distributed**函数创建的比对脚本中，在[config.json](../../config/config.json)文件中配置"task": "statistics"方式dump时，可以进行统计量比对，此时比对dump.json文件中的统计信息，开启后的比对结果文件生成Max diff、Min diff、Mean diff和L2norm diff，表示NPU dump数据中API的输入或输出与标杆数据输入或输出的最大值、最小值、平均值以及L2范数的差。可以通过该值判断API是否存在精度问题：当某个API的输入和输出的Max diff、Min diff、Mean diff和L2norm diff均为0或无限趋于0，那么可以判断该API无精度问题，反之则可能存在精度问题。 - -**比对脚本示例** - -以compare.py为例。 - -```Python -from msprobe.pytorch import compare -input_param={ -"npu_json_path": "./npu_dump/dump.json", -"bench_json_path": "./bench_dump/dump.json", -"stack_json_path": "./npu_dump/stack.json", -"is_print_compare_log": True -} -compare(input_param, output_path="./output", stack_mode=True) -``` - -**比对结果** - -数据量比对同样生成`compare_result_{timestamp}.xlsx`和`advisor_{timestamp}.txt`文件。其中`advisor_{timestamp}.txt`主要对`compare_result_{timestamp}.xlsx`中可能存在精度问题（Result为Waring）的API提出定位建议；`compare_result_{timestamp}.xlsx`主要有如下两种情况： - -- "summary_mode": "statistics"时比对dump.json文件： - - ![compare_result_pkl](img/compare_result_pkl.png) - - 上图是对dump.json文件中NPU及标杆API的统计信息进行比对，判断可能存在精度问题的API，文件中记录NPU及标杆API的基本信息和统计信息，其中需要关注Result列，包含结果：Waring（NPU与标杆统计信息的比对中存在相对误差大于0.5，则需要重点检查该API）；为空（相对误差小于等于0.5，可以不需要重点关注，但不代表不存在精度问题）；Nan（表示统计信息数据没有匹配上）。 - -- "summary_mode": "md5"时比对dump.json文件： - - ![compare_result_pkl_md5.png](img/compare_result_pkl_md5.png.png) - - 上图是对dump.json文件中NPU及标杆API的MD5信息进行比对，判断API数据的完整性，文件中记录NPU及标杆API的基本信息和MD5信息，其中需要关注Result列，包含结果：Pass（表示NPU与标杆的MD5值一致，即API数据完整）；Different（表示NPU与标杆的MD5值不一致，即API数据不完全一致，可以通过NPU_Stack_Info列API调用栈查询该API的详细信息）；Nan（表示MD5信息数据没有匹配上）。 - -## 比对结果分析 - -PyTorch精度比对是以CPU或GPU的计算结果为标杆，通过计算精度评价指标判断API在运行时是否存在精度问题。 - -- `advisor_{timestamp}.txt`文件中给出了可能存在精度问题的API的专家建议，可直接打开查看。 - -- `compare_result_{timestamp}.xlsx`文件列出了所有执行精度比对的API详细信息和比对结果，如下示例： - - ![compare_result](https://gitee.com/cai-weiwei1989/att_ptdbg/raw/master/debug/accuracy_tools/ptdbg_ascend/doc/img/compare_result.png) - - 可以从该结果文件中进行“**判断计算精度达标情况**”、“**计算精度评价指标分析**”以及“**异常信息识别**”等分析动作。 - -### **判断计算精度达标情况** - -精度比对结果`compare_result_{timestamp}.xlsx`文件中只需要通过Accuracy Reached or Not来判断计算精度是否达标，判断标准如下： - -1. Cosine < 0.99 且 MaxAbsError > 0.001时，精度不达标，标记为“No”。 -2. Cosine < 0.9，精度不达标，标记为“No”。 -3. MaxAbsError > 1，精度不达标，标记为“No”。 -4. 其余情况下记为精度达标，标记为“Yes”。 - -### **计算精度评价指标分析** - -1. Cosine：通过计算两个向量的余弦值来判断其相似度，数值越接近于1说明计算出的两个张量越相似，实际可接受阈值为大于0.99。在计算中可能会存在nan，主要由于可能会出现其中一个向量为0。 - -2. MaxAbsErr：当最大绝对误差越接近0表示其计算的误差越小，实际可接受阈值为小于0.001。 - -3. MaxRelativeErr：当最大相对误差越接近0表示其计算的误差越小。 - - 当dump数据中存在0或Nan时，比对结果中最大相对误差则出现inf或Nan的情况，属于正常现象。 - -4. One Thousandth Err Ratio（双千分之一）、Five Thousandths Err Ratio（双千分之五）精度指标：是指NPU的Tensor中的元素逐个与对应的标杆数据对比，相对误差大于千分之一、千分之五的比例占总元素个数的比例小于千分之一、千分之五。该数据仅作为精度下降趋势的参考，并不参与计算精度是否通过的判定。 - -### **异常信息识别** - -精度比对结果`compare_result_{timestamp}.xlsx`文件中对于存在异常信息的API会进行高亮处理： - -- 红色可能出现的情况有： - - NPU max或NPU min信息中存在nan/inf - - Max diff存在大于1e+10的值 - - 统计数据中output的Max diff除以max(0.01, Bench max) > 0.5 - - 真实数据中One Thousandth Err Ratio的input > 0.9同时output < 0.6 -- 黄色可能出现的情况有： - - Max diff的input与output都大于1，同时output比input大一个数量级以上 - - 统计数据Max diff除以max(0.01, Bench max)的output > 0.1同时input < 0.01 - - 真实数据One Thousandth Err Ratio的input - output > 0.1 - - 真实数据Cosine的input - output > 0.1 - -### **Shape为[]时，统计量列说明** -当NPU Tensor Shape列为[]时，表示标量或0维张量，统计量列（NPU max、NPU min、NPU mean、NPU l2norm）展示相同的唯一元素。Bench同理。 - -# FAQ - -[FAQ](./FAQ.md) - diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_overview.md b/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_overview.md deleted file mode 100644 index 019451454877eddd3cf6e59cc1eef1c48fcf2a3c..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_overview.md +++ /dev/null @@ -1,68 +0,0 @@ -# **精度比对工具** - -## 简介 - -在PyTorch训练网络，对同一模型或API调试过程中，遇到API相关的计算精度问题，定位时费时费力。 - -msprobe的精度比对工具，用来进行PyTorch整网API粒度的数据dump、精度比对和溢出检测，从而定位PyTorch训练场景下的精度问题。 - -**使用场景** - -主要的使用场景包括： - -- 同一模型，从CPU或GPU移植到NPU中存在精度下降问题，对比NPU芯片中的API计算数值与CPU或GPU芯片中的API计算数值，进行问题定位。 -- 同一模型，进行迭代（模型、框架版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的API计算数值，进行问题定位。 - -## 原理介绍 - -精度对比工具，通过在PyTorch模型中注册hook，跟踪计算图中API的前向传播与反向传播时的输入与输出，排查存在计算精度误差，进行问题的精准定位。 - -**精度比对流程** - -1. 当模型在CPU或GPU上进行正向和反向传播时，分别dump每一层的数值输入与输出。 - -2. 当模型在NPU中进行计算时，采用相同的方式dump下相应的数据。 - -3. 通过对比dump出的数值，计算余弦相似度和最大绝对误差的方式，定位和排查NPU API存在的计算精度问题。如下图所示。 - - 精度比对逻辑图 - - ![module_compare](img/module_compare.png) - -**API匹配条件** - -进行精度比对时，需要判断CPU或GPU的API与NPU的API是否相同可比对，须满足以下匹配条件： - -- 两个API的名称相同，API命名规则：`{api_type}.{api_name}.{api调用次数}.{正反向}.{输入输出}.index`，如：Functional.conv2d.1.backward.input.0。 -- 两个API的输入输出Tensor数量和各个Tensor的Shape相同。 - -通常满足以上两个条件，工具就认为是同一个API，成功进行API的匹配，后续进行相应的计算精度比对。 - -## 精度比对总体流程 - -1. 准备CPU或GPU训练工程。 - -2. 在环境下安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 - -3. 在训练脚本内添加msprobe工具dump接口PrecisionDebugger采集标杆数据。详见《[精度数据采集](./dump.md)》。 - -4. 执行训练dump数据。 - -5. 将CPU或GPU训练工程迁移为NPU训练工程。详见《[PyTorch模型迁移调优指南](https://www.hiascend.com/document/detail/zh/Pytorch/60RC1/ptmoddevg/trainingmigrguide/PT_LMTMOG_0003.html)》。 - -6. 在NPU环境下安装msprobe工具。详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 - -7. 在NPU训练脚本内添加msprobe工具dump接口PrecisionDebugger采集标杆数据。详见《[精度数据采集](./dump.md)》。 - -8. NPU环境下执行训练dump数据。 - -9. 执行精度比对。 - - 1. 创建并配置精度比对脚本，例如compare.py。 - - 2. 执行CPU或GPU dump与NPU dump数据的精度比对。 - - 3. 比对结果分析。 - - 详见《[CPU或GPU与NPU精度数据比对](./ptdbg_ascend_compare.md)》。 - diff --git a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_quickstart.md b/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_quickstart.md deleted file mode 100644 index 1a581226f9ac4ddecf881f2721346a9eb668b650..0000000000000000000000000000000000000000 --- a/debug/accuracy_tools/msprobe/pytorch/doc/ptdbg_ascend_quickstart.md +++ /dev/null @@ -1,381 +0,0 @@ -# **精度比对工具** - -本文主要介绍msprobe的精度比对工具的快速入门和场景化示例。 - -本文介绍的操作需要安装msprobe工具，详见《[MindStudio精度调试工具](../../README.md)》的“工具安装”章节。 - -本文介绍的操作主要是精度数据dump和精度比对，详细操作指导可参考《[精度数据采集](./dump.md)》和《[CPU或GPU与NPU精度数据比对](./ptdbg_ascend.md)》。 - -## 快速入门 - -### 单卡场景精度比对 - -**精度分析建议** - -PyTorch训练场景的精度问题分析建议参考以下思路进行精度比对和比对结果分析： - -1. 整网比对：dump整网数据并进行精度比对，初步定位异常范围。 - - 对于模型数据庞大（比如达到T级别）的场景，不推荐直接dump整网比对，整网dump可能导致磁盘不足，需要预留足够的存储空间或者分多次dump。 - -2. 缩小范围：根据Accuracy Reached or Not找出不符合精度标准的API。 - -3. 范围比对：对不符合精度标准的API重新dump详细信息。 - -4. 分析原因并优化：分析API精度不符合标准的原因并进行优化调整。 - -5. 整网比对：重新进行整网比对，判断优化后的API是否已符合精度标准以及是否出现新的精度问题。 - -6. 重复1~5步，直到不存在精度问题为止。 - -**精度分析示例** - -1. 修改dump配置文件config.json。 - - ```json - { - "task": "tensor", - "dump_path": "./npu_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - - "tensor": { - "scope": [], - "list": [], - "data_mode": ["all"], - "summary_mode": "statistics" - } - } - ``` - -2. 在训练脚本内添加msprobe工具，dump整网数据。 - - 分别dump CPU或GPU以及NPU数据，在PyTorch训练脚本插入dump接口，示例代码如下（下面以NPU为例，CPU或GPU dump基本相同）： - - ```python - from msprobe.pytorch import PrecisionDebugger - debugger = PrecisionDebugger(config_path="./config.json", dump_path="./npu_dump") - # 请勿将以上初始化流程插入到循环代码中 - - # 模型初始化 - # 下面代码也可以用PrecisionDebugger.start()和PrecisionDebugger.stop() - debugger.start() - - # 需要dump的代码片段1 - - debugger.stop() - debugger.start() - - # 需要dump的代码片段2 - - debugger.stop() - debugger.step() - ``` - -3. 比对整网数据。 - - 第1步中的NPU dump数据目录为npu_dump，假设GPU dump数据目录为gpu_dump；dump将生成dump.json、stack.json、construct.json文件以及dump数据目录。 - - 创建并配置精度比对脚本，以创建compare.py为例，示例代码如下： - - ```python - from msprobe.pytorch import compare - input_param={ - "npu_json_path": "./npu_dump/dump.json", - "bench_json_path": "./bench_dump/dump.json", - "stack_json_path": "./npu_dump/stack.json", - "is_print_compare_log": True - } - compare(input_param, output_path="./output", stack_mode=True) - ``` - - 执行比对： - - ```bash -python3 compare.py - ``` - - 在output目录下生成结果文件，包括：`compare_result_{timestamp}.xlsx`和`advisor_{timestamp}.txt` - -4. 找出存在问题的API。 - - 1. 根据`advisor_{timestamp}.txt`或打屏信息的提示，可找到存在精度问题的算子（Suspect Nodes）和专家建议（Expert Advice)。 - - ![auto_analyze_log](img/auto_analyze_log.png) - - 2. 根据第2步结果文件`compare_result_{timestamp}.xlsx`中的Accuracy Reached or No字段显示为NO的API，针对该API执行后续比对操作，分析该API存在的精度问题。 - -5. （可选）重新比对。 - - 根据第3步的dump数据重新配置compare.py并执行比对，可以对单API模型进行问题复现。 - -**注意**：部分API存在调用嵌套关系，比如functional.batch_norm实际调用torch.batch_norm，该场景会影响kernel init初始化多次，导致功能异常。 - -### 溢出检测场景 - -溢出检测是针对NPU的PyTorch API，检测是否存在溢出的情况。当前仅支持识别aicore浮点溢出。 - -溢出检测原理：针对溢出阶段，开启acl dump模式，重新对溢出阶段执行，落盘数据。 - -建议按照如下步骤操作： - -1. 修改dump配置文件config.json。 - - ```json - { - "task": "overflow_check", - "dump_path": "./npu_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - - "overflow_check": { - "overflow_nums": 3 - } - } - ``` - -2. 在NPU训练脚本内添加msprobe工具，执行溢出检测dump。 - - ```python - from msprobe.pytorch import PrecisionDebugger - debugger = PrecisionDebugger(config_path="./config.json", dump_path="./npu_dump") - # 请勿将以上初始化流程插入到循环代码中 - - # 模型初始化 - # 下面代码也可以用PrecisionDebugger.start()和PrecisionDebugger.stop() - debugger.start() - - # 需要dump的代码片段1 - - debugger.stop() - debugger.start() - - # 需要dump的代码片段2 - - debugger.stop() - debugger.step() - ``` - - 多卡使用时各卡单独计算溢出次数。 - -3. NPU环境下执行训练dump溢出数据。 - - 针对输入正常但输出存在溢出的API，会在训练执行目录下将溢出的API信息dump并保存为`dump.json`通过《[溢出解析工具](./run_overflow_check.md)》对json文件进行解析，输出溢出API为正常溢出还是非正常溢出，从而帮助用户快速判断。 - - 溢出解析工具执行命令如下： - - ```bash - msprobe -f pytorch run_overflow_check -api_info ./dump.json - ``` - - 反向过程溢出的API暂不支持精度预检功能。 - - -当重复执行溢出检测dump操作时，需要删除上一次dump目录下的溢出检测dump数据，否则将因重名而报错。 - -**注意事项** - -* （暂不支持）level为L2场景下，会增加npu的内存消耗，请谨慎开启。 -* （暂不支持）l部分API存在调用嵌套关系，比如functional.batch_norm实际调用torch.batch_norm，该场景会影响acl init初始化多次，导致level为L2功能异常。 -* 混合精度动态loss scale场景下，正常训练会有"Gradient overflow. SKipping step"日志，添加溢出检测后日志消失，可以通过设置环境变量export OVERFLOW_DEBUG_MODE_ENABLE=1，并将register_hook位置调整amp.initialize之前解决。此功能需要cann包配套支持，不支持版本执行报错EZ3003。 - -## 场景化示例 - -### 多卡场景精度比对 - -精度工具支持多卡场景的精度比对，多卡场景的dump步骤与单卡场景完全一致，请参见“**单卡场景精度比对**”章节，不同的是多卡数据精度比对时需要使用“compare_distributed”函数进行比对。 - -如下示例： - -说明：多机多卡场景需要每个节点单独执行比对操作。 - -假设NPU dump 数据目录为npu_dump，GPU dump数据目录为gpu_dump。 - -1. 创建比对脚本，例如compare_distributed.py，拷贝如下代码。 - - ```python - from msprobe.pytorch import * - compare_distributed('./npu_dump/step0', './gpu_dump/step0', './output') - ``` - - dump数据目录须指定到step级。 - -2. 执行比对： - - ```bash - python3 compare_distributed.py - ``` - -两次运行须用相同数量的卡，传入`compare_distributed`的两个文件夹下须有相同个数的rank文件夹，且不包含其他无关文件，否则将无法比对。 - -**多卡set_dump_path注意事项** - -多卡一般为多进程，须保证每个进程都正确调用PrecisionDebugger，或把PrecisionDebugger插入到import语句后，如： - -```python -from msprobe.pytorch import PrecisionDebugger -debugger = PrecisionDebugger(config_path="./config.json", dump_path="./npu_dump") -``` - -如此可保证set_dump_path在每个进程都被调用。 - -### NPU vs NPU精度比对 - -对于NPU vs NPU场景，是针对同一模型，进行迭代（模型、API版本升级或设备硬件升级）时存在的精度下降问题，对比相同模型在迭代前后版本的API计算数值，进行问题定位。 - -一般情况下迭代涉及NPU自定义算子，因此，可以仅dump NPU自定义算子进行比对。比对精度问题分析请参见“**单卡场景精度比对**”章节。 - -工具当前支持dump NPU自定义算子如下： - -| 序号 | NPU自定义算子 | -| :--- | ----------------------------------------------- | -| 1 | torch_npu.one_ | -| 2 | torch_npu.npu_sort_v2 | -| 3 | torch_npu.npu_transpose | -| 4 | torch_npu.npu_broadcast | -| 5 | torch_npu.npu_dtype_cast | -| 6 | torch_npu.empty_with_format | -| 7 | torch_npu.npu_one_hot | -| 8 | torch_npu.npu_stride_add | -| 9 | torch_npu.npu_ps_roi_pooling | -| 10 | torch_npu.npu_roi_align | -| 11 | torch_npu.npu_nms_v4 | -| 12 | torch_npu.npu_iou | -| 13 | torch_npu.npu_nms_with_mask | -| 14 | torch_npu.npu_pad | -| 15 | torch_npu.npu_bounding_box_encode | -| 16 | torch_npu.npu_bounding_box_decode | -| 17 | torch_npu.npu_batch_nms | -| 18 | torch_npu.npu_slice | -| 19 | torch_npu._npu_dropout | -| 20 | torch_npu.npu_indexing | -| 21 | torch_npu.npu_ifmr | -| 22 | torch_npu.npu_max | -| 23 | torch_npu.npu_scatter | -| 24 | torch_npu.npu_layer_norm_eval | -| 25 | torch_npu.npu_alloc_float_status | -| 26 | torch_npu.npu_confusion_transpose | -| 27 | torch_npu.npu_bmmV2 | -| 28 | torch_npu.fast_gelu | -| 29 | torch_npu.npu_sub_sample | -| 30 | torch_npu.npu_deformable_conv2d | -| 31 | torch_npu.npu_mish | -| 32 | torch_npu.npu_anchor_response_flags | -| 33 | torch_npu.npu_yolo_boxes_encode | -| 34 | torch_npu.npu_grid_assign_positive | -| 35 | torch_npu.npu_normalize_batch | -| 36 | torch_npu.npu_masked_fill_range | -| 37 | torch_npu.npu_linear | -| 38 | torch_npu.npu_bert_apply_adam | -| 39 | torch_npu.npu_giou | -| 40 | torch_npu.npu_ciou | -| 41 | torch_npu.npu_diou | -| 42 | torch_npu.npu_sign_bits_pack | -| 43 | torch_npu.npu_sign_bits_unpack | -| 44 | torch_npu.npu_flash_attention | -| 45 | torch_npu.npu_scaled_masked_softmax | -| 46 | torch_npu.npu_rotary_mul | -| 47 | torch_npu.npu_roi_align | -| 48 | torch_npu.npu_roi_alignbk | -| 49 | torch_npu.npu_ptiou | -| 50 | torch_npu.npu_fusion_attention | -| 51 | torch_npu.npu_dropout_with_add_softmax | -| 52 | torch_npu.npu_random_choice_with_mask | -| 53 | torch_npu.npu_rotated_iou | -| 54 | torch_npu.npu_conv2d | -| 55 | torch_npu.npu_conv3d | -| 56 | torch_npu.npu_softmax_cross_entropy_with_logits | -| 57 | torch_npu.npu_all_gather_base_mm | -| 58 | torch_npu.npu_swiglu | -| 59 | torch_npu.npu_rms_norm | -| 60 | torch_npu.npu_mm_reduce_scatter_base | -| 61 | torch_npu.npu_mm_all_reduce_base | -| 62 | torch_npu.npu_conv_transpose2d | -| 63 | torch_npu.npu_convolution | -| 64 | torch_npu.npu_convolution_transpose | -| 65 | torch_npu.npu_min | -| 66 | torch_npu.npu_nms_rotated | -| 67 | torch_npu.npu_reshape | -| 68 | torch_npu.npu_rotated_box_decode | -| 69 | torch_npu.npu_rotated_box_encode | -| 70 | torch_npu.npu_rotated_overlaps | -| 71 | torch_npu.npu_silu | -| 72 | torch_npu.npu_fused_attention_score | -| 73 | torch_npu.npu_multi_head_attention | -| 74 | torch_npu.npu_gru | -| 75 | torch_npu.npu_incre_flash_attention | -| 76 | torch_npu.npu_prompt_flash_attention | -| 77 | torch_npu.npu_lstm | -| 78 | torch_npu.npu_apply_adam | - -### 通信API的数据dump - -通信类API数据可以使用全量dump方式获取，若只dump通信类API数据，可以使用如下示例： - -1. 修改dump配置文件config.json。 - - ```json - { - "task": "tensor", - "dump_path": "./npu_dump", - "rank": [], - "step": [], - "level": "L1", - "seed": 1234, - "is_deterministic": false, - - "tensor": { - "scope": [], - "list": ["distributed"], - "data_mode": ["all"], - "summary_mode": "statistics" - } - } - ``` - -2. 在训练脚本内添加msprobe工具，dump整网数据。 - - ```python - from msprobe.pytorch import PrecisionDebugger - debugger = PrecisionDebugger(config_path="./config.json", dump_path="./npu_dump") - # 请勿将以上初始化流程插入到循环代码中 - - # 模型初始化 - # 下面代码也可以用PrecisionDebugger.start()和PrecisionDebugger.stop() - debugger.start() - - # 需要dump的代码片段1 - - debugger.stop() - debugger.start() - - # 需要dump的代码片段2 - - debugger.stop() - debugger.step() - ``` - -通信类API支持列表： - -| 序号 | Distributed | -| :--- | -------------------- | -| 1 | send | -| 2 | recv | -| 3 | broadcast | -| 4 | all_reduce | -| 5 | reduce | -| 6 | all_gather | -| 7 | gather | -| 8 | isend | -| 9 | irecv | -| 10 | scatter | -| 11 | reduce_scatter | -| 12 | _reduce_scatter_base | -| 13 | _all_gather_base | - diff --git "a/debug/accuracy_tools/msprobe/pytorch/doc/\345\234\250\347\272\277\347\262\276\345\272\246\346\257\224\345\257\271.md" "b/debug/accuracy_tools/msprobe/pytorch/doc/\345\234\250\347\272\277\347\262\276\345\272\246\346\257\224\345\257\271.md" deleted file mode 100644 index 05bebaf0a22d8d5d7886ec9937b32b4755caf872..0000000000000000000000000000000000000000 --- "a/debug/accuracy_tools/msprobe/pytorch/doc/\345\234\250\347\272\277\347\262\276\345\272\246\346\257\224\345\257\271.md" +++ /dev/null @@ -1,90 +0,0 @@ -# **PyTorch NPU在线精度比对工具使用指南** - -PyTorch NPU在线精度比对是ptdbg_ascend工具实现在PyTorch训练过程中直接完成精度比对并输出比对结果的功能。 - -在线精度比对实现的是NPU与CPU之间的精度比对。 - -## PyTorch NPU在线精度比对总体流程 - -1. 准备NPU训练工程。 - -2. 在NPU环境下安装ptdbg_ascend工具，参见《[PyTorch精度工具](https://gitee.com/ascend/mstt/blob/master/debug/accuracy_tools/ptdbg_ascend/README.md)》。 - -3. 在训练脚本内插入ptdbg_ascend工具在线精度比对接口。 - -4. 执行训练并获取在线精度比对NPU和CPU分别执行后的精度比对结果。 - -5. 比对结果分析。 - -## PyTorch NPU在线精度比对 -### 总体说明 -- 本节主要介绍NPU精度比对所需要的函数以及示例。 -- 在线精度比对工具通过截获PyTorch框架中部分Aten Ir及其输入输出，并将输入数据转到CPU执行，最后将NPU和CPU的执行结果进行精度比对得到比对结果。 - -### 约束 - -- Pytorch 只支持2.0及其以上版本。 -- 只支持Aten Ir级在线精度比对，所有Aten Ir可以通过dir(torch.ops.aten)查看，其中部分IR不支持在线比对：Aten Ir无对应CPU实现、NPU和CPU同AtenIR实现逻辑不一致，导致同输入不同输出。 -- 正反向不支持同时在线精度比对，不支持跨step在线精度比对。 - - -### 场景示例 -1. 在NPU训练脚本中添加在线精度比对接口，示例如下： - - ```python - from msprobe.pytorch.common.utils import seed_all - from msprobe.pytorch.online_dispatch import PtdbgDispatch - - # 在main函数开始前固定随机数 - seed_all() - - - ... - - # 在需要调试精度的正向或反向代码前设置 - # 正向示例 - with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"): - output = model_cpu(inputs) - # 反向示例 - with PtdbgDispatch(dump_mode="auto", dump_path="/home/dump"): - loss.backward() - ``` - -2. 执行训练。 - -3. 找出精度不达标的Aten IR。 - - 执行过程中会打屏Failed，Failed在比对结果csv中的Accuracy Reached or Not列标记为No，并在Dump目录下存盘精度不达标Aten IR的输入输出。 - ![图片说明](http://image.huawei.com/tiny-lts/v1/images/d83d564e337e80c7cfb557ca3600d0d4_1689x178.png@900-0-90-f.png) - -### 计算精度评价指标 - -1. Cosine < 0.99 且 MaxAbsError > 0.001时，精度不达标； -2. Cosine < 0.9，精度不达标； -3. MaxAbsError > 1，精度不达标。 - -### 在线精度比对参数设置说明 - -| 参数名称 | 说明 | 是否必选 | -| -------- |-------------------------------------------------------------------------------------------------| -------- | -| dump_mode| dump模式，可取值"all"、"list"、"auto"、"OFF"，默认值为OFF（表示不Dump数据）。 | 否 | -| api_list | dump范围，dump_mode="list"时设置，需要Dump Aten Ir API名称，默认为None，Aten Ir API名称可以通过dir(torch.ops.aten)查看。 | 否 | -| dump_path| dump文件生成的路径。 | 是 | -| tag | 传入tag字符串，成为dump文件夹名一部分，默认为None。 | 否 | -| process_num | 多进程并发数，默认为0。 | 否 | -| debug | debug信息打印，默认为False。 | 否 | -### dump数据存盘说明 -dump数据存盘目录名格式：`msprobe_tag_rankid_{timestamp}`。 - -子目录下包含1个比对结果csv文件、cpu和npudump数据目录，npu目录下包含Aten IR在NPU上的输入输出的dump数据，由于CPU的输入是直接使用NPU的输入执行，因此cpu目录下只包含执行输出的dump数据。 - -```bash -msprobe_rank4_20230911170521 -├── compare_result_rank4_20230911170521.csv -├── cpu -│   ├── native_batch_norm_backward_10_output.0.npy -│ ............ -└── npu - ├── native_batch_norm_backward_10_input.0.npy - ............ -``` diff --git a/debug/accuracy_tools/msprobe/pytorch/pt_config.py b/debug/accuracy_tools/msprobe/pytorch/pt_config.py index f86ac1580392cbd31eadce84236056ecae1075c0..d1d95c3e52217c3a8131d06f54c1a7ecc91f70dd 100644 --- a/debug/accuracy_tools/msprobe/pytorch/pt_config.py +++ b/debug/accuracy_tools/msprobe/pytorch/pt_config.py @@ -176,7 +176,7 @@ def parse_task_config(task, json_config): def parse_json_config(json_file_path, task): if not json_file_path: config_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) - json_file_path = os.path.join(os.path.join(config_dir, "config"), "config.json") + json_file_path = os.path.join(config_dir, "config.json") with FileOpen(json_file_path, 'r') as file: json_config = json.load(file) common_config = CommonConfig(json_config)