TorchAir图模式优化系列教程

TorchAir（Torch Ascend Intermediate Representation）是昇腾Ascend Extension for PyTorch（torch_npu）的图模式能力扩展库，提供了昇腾设备亲和的torch.compile图模式后端，实现了PyTorch网络在昇腾NPU上的图模式推理加速以及性能优化。

本教程面向对昇腾 NPU 图模式编译加速技术（尤其是基于 torch.compile 的 npugraph_ex 后端）感兴趣的深度学习与大模型推理开发者。内容涵盖了从 npugraph_ex 的基本原理与问题定界，到静态内存复用、高阶多流并行优化、以及实践与问题的定位。

教程按章节划分，每个章节均包含以下内容：

• Notebooks：包含详细的章节知识精讲、代码配置实例与交互式操作，可直接在 GitCode 提供的昇腾云端开发环境（CANNLab）中一键启动，也可在本地搭建 Jupyter Lab 运行。
• Answer：包含每章配套章节练习的参考答案。

---

适用人群

• 在华为昇腾 NPU 上进行 PyTorch 模型推理的算法/工程同学
• 希望了解npugraph_ex原理与最佳实践的框架开发同学
• 遇到npugraph_ex性能或正确性问题的定位者

开发前置要求

在开始本教程之前，建议你具备以下基础知识与技能：

• 熟悉 Python 语言，以及 PyTorch 深度学习框架的基本用法。
• 了解 torch.compile 机制与 FX 计算图（FX Graph）的基本概念。
• 了解昇腾 NPU 硬件加速与 torch_npu 驱动的基本概念。

产品支持

• Ascend 950PR/Ascend 950DT
• Atlas A3 训练系列产品/Atlas A3 推理系列产品
• Atlas A2 训练系列产品/Atlas A2 推理系列产品

TorchAir 版本配套表

TorchAir暂无独立安装包，该组件属于PyTorch昇腾适配插件Ascend Extension for PyTorch的内置三方库，随着torch_npu软件包统一发布，直接安装torch_npu即可调用TorchAir能力。 TorchAir 需匹配对应版本的PyTorch、TorchNPU、CANN固件与Python 环境。以下为当前各版本的匹配关系：

TorchAir 主仓分支	TorchNPU版本	TorchNPU 主仓分支	PyTorch版本	CANN版本	Python版本
26.0.0	2.9.0.post2	v2.9.0-26.0.0	2.9.0	9.0.0	Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
26.0.0	2.8.0.post4	v2.8.0-26.0.0	2.8.0	9.0.0	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
26.0.0	2.7.1.post4	v2.7.1-26.0.0	2.7.1	9.0.0	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.3.0	2.9.0	v2.9.0-7.3.0	2.9.0	8.5.0	Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.3.0	2.8.0.post2	v2.8.0-7.3.0	2.8.0	8.5.0	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.3.0	2.7.1.post2	v2.7.1-7.3.0	2.7.1	8.5.0	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.3.0	2.6.0.post5	v2.6.0-7.3.0	2.6.0	8.5.0	Python3.9.x / Python3.10.x / Python3.11.x
7.2.0	2.8.0	v2.8.0-7.2.0	2.8.0	8.3.RC1	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.2.0	2.7.1	v2.7.1-7.2.0	2.7.1	8.3.RC1	Python3.9.x / Python3.10.x / Python3.11.x / Python3.12.x / Python3.13.x
7.2.0	2.6.0.post3	v2.6.0-7.2.0	2.6.0	8.3.RC1	Python3.9.x / Python3.10.x / Python3.11.x
7.2.0	2.1.0.post17	v2.1.0-7.2.0	2.1.0	8.3.RC1	Python3.8.x / Python3.9.x / Python3.10.x / Python3.11.x
7.1.0	2.6.0	v2.6.0-7.1.0	2.6.0	8.2.RC1	Python3.9.x / Python3.10.x / Python3.11.x
7.1.0	2.5.1.post1	v2.5.1-7.1.0	2.5.1	8.2.RC1	Python3.9.x / Python3.10.x / Python3.11.x
7.1.0	2.1.0.post13	v2.1.0-7.1.0	2.1.0	8.2.RC1	Python3.8.x / Python3.9.x / Python3.10.x / Python3.11.x
7.0.0	2.5.1	v2.5.1-7.0.0	2.5.1	8.1.RC1	Python3.9.x / Python3.10.x / Python3.11.x
7.0.0	2.4.0.post4	v2.4.0-7.0.0	2.4.0	8.1.RC1	Python3.8.x / Python3.9.x / Python3.10.x / Python3.11.x
7.0.0	2.3.1.post6	v2.3.1-7.0.0	2.3.1	8.1.RC1	Python3.8.x / Python3.9.x / Python3.10.x / Python3.11.x
7.0.0	2.1.0.post12	v2.1.0-7.0.0	2.1.0	8.1.RC1	Python3.8.x / Python3.9.x / Python3.10.x / Python3.11.x

在线体验环境

本教程支持以下在线体验环境：

体验环境	镜像模板 / 版本	Python 内核	说明
cann-learning-hub 在线体验 notebook	cann_9.0.0_py3.11-A2-arm	Python 3.11.15	各 Notebook 表格中的"在线体验"链接可直接打开运行
CANNLab 云开发环境	cann_9.0.0_py3.11-A2-arm	Python 3.11.4	参考 CANNLab 环境体验指南创建CANNLab环境运行notebook

注意： 如在本地环境离线体验，需自行安装配套的 CANN 软件，具体请参考 CANN 安装指南。

---

教程章节导航

本教程共分为三个部分，循序渐进得讲解npugraph_ex图模式相关能力。

第一部分：npugraph_ex 背景知识介绍及快速入门篇

第一章节 前置背景

本小节为前置的理论介绍， 开发者通过对npugraph_ex 原理与基础概念、torch.compile机制的学习了解，建立底层理论体系，全面理解昇腾专属图模式后端的设计逻辑与核心加速机制。

Notebook	Link	状态
1.1 章节介绍	在线体验	✅ 已发布
1.2 torch.compile原理介绍	在线体验	✅ 已发布
1.3 NPUGraph原理介绍	在线体验	✅ 已发布
1.4 npugraph_ex基础概念	在线体验	✅ 已发布
1.5 章节练习	在线体验	✅ 已发布

第二章节 快速上手

本小节为开发者提供一套完整的实操案例，从零演示如何校验昇腾运行环境、构建测试模型、启用npugraph_ex后端进行图编译的全流程，有助于开发者直观感受 npugraph_ex捕获（ Capture）和回放（Replay）机制带来的推理加速成效，从而快速掌握TorchAir 图模式的基础使用方法。

Notebook	Link	状态
2.1 章节介绍	在线体验	✅ 已发布
2.2 上手案例	在线体验	✅ 已发布
2.3 章节练习	在线体验	✅ 已发布

---

第二部分 npugraph_ex 进阶优化篇

第三章节 基础功能

本小节为npugraph_ex常用的基础功能介绍，涉及 Host 侧与 Device 侧的异构内存优化、跨硬件流水线调度及算子硬件特化刷新等，帮助开发者了解 npugraph_ex 的内存分配机制与优化策略。

Notebook	Link	状态
3.1 章节介绍	在线体验建设中	🚧 开发中
3.2 基础功能介绍	在线体验建设中	🚧 开发中
3.3 原地算子优化	在线体验建设中	🚧 开发中
3.4 内存复用	在线体验建设中	🚧 开发中
3.5 FX pass 优化	在线体验建设中	🚧 开发中
3.6 章节练习	在线体验建设中	🚧 开发中

第四章节 深度优化

本章节为npugraph_ex高阶功能的介绍，涉及编译产物持久化、芯片底层计算核资源的精细化调配及异构算子的生成与调度策略，针对大模型推理中的高并发、长序列等特殊场景优化效果明显。

Notebook	Link	状态
4.1 章节介绍	在线体验建设中	🚧 开发中
4.2 模型编译缓存功能	在线体验建设中	🚧 开发中
4.3 多流表达功能	在线体验建设中	🚧 开发中
4.4 AI-Core 和 Vector-Core 限核功能	在线体验建设中	🚧 开发中
4.5 静态 Kernel 编译功能	在线体验建设中	🚧 开发中
4.6 SuperKernel功能	在线体验建设中	🚧 开发中
4.7 章节练习	在线体验建设中	🚧 开发中

第三部分 npugraph_ex 实践与问题定位篇

第五章节 实践与问题定位

本章节为npugraph_ex常用 DFX功能的介绍，涉及图编译期中间表征（IR）保存、芯片运行时算子数据溢出监测等，针对模型编译失败、精度异常等故障场景定位效果明显。

Notebook	Link	状态
5.1 章节介绍	在线体验建设中	🚧 开发中
5.2 图编译Debug信息保存功能	在线体验建设中	🚧 开发中
5.3 算子Data-Dump功能	在线体验建设中	🚧 开发中
5.4 多流并发死锁检测功能	在线体验建设中	🚧 开发中
5.5 常见问题的定位方法	在线体验建设中	🚧 开发中
5.6 章节练习	在线体验建设中	🚧 开发中