昇腾部署第 C3 课：框架适配原理——一个算子从框架到芯片走了哪条路

编制：观澜｜日期：2026-10-05｜级别：T2 标准级 层级：C 层 · L2 框架（C 层第 3 课，C 层收官；前接 C2《多框架》）素材来源：昇腾官方文档 MCP 实时抓取（CANN 9.2.0-beta.2 / TorchNPU 26.1.X 官方文档）数据纪律：执行形态、接入方式、适配插件名称、框架支持范围逐字出自官方文档；标注「归纳」的是便于记忆的整理，非官方口径。

第一段 · 章前定位

前面四课各讲了一段路，这一课把它们接通。

课	讲的哪一段
B2	算子库里有 kernel 二进制，`aclnn` 类 API 的动态库是给框架用的
B3	版本配套 —— 对不上就出问题
C1	框架怎么接进来（TorchNPU 插件、`.npu()`）
C2	图模式与 TorchAir 是什么（只给了定义）

中间那段一直没讲：

你在 PyTorch 里写 a + a，到 NPU 真的算出结果，中间发生了什么？ .npu() 之后，算子是"一个一个算"还是"整图打包算"？ 为什么官方文档里同时有 aclnn、GE、OpPlugin、TorchAir 这么多名词？

这一课回答这个问题。而且答案比你想象的整齐 —— 官方把这件事归纳成"三种执行形态"，每种的接入方式和适配插件都能对上号。

为什么部署的人要懂这个： 因为报错的形态不一样。 单算子模式下报"算子找不到"，和图模式下报"图编译失败"，是两条完全不同的排查路线。 不知道自己在哪条路上，就会拿着错的地图找路。

第二段 · 学习目标

学完这一课，你应该能回答：

官方归纳的三种执行形态分别是什么
单算子模式和图模式的核心差别（一句话说清）
单算子怎么接入（用哪个 API）、入图怎么接入（用哪一层）
单算子的适配插件和图模式的适配插件分别叫什么
不同框架支持的形态不一样 —— 这对排查意味着什么

第三段 · 官方归纳的三种执行形态（本课的基础）

官方原文（HCCL 主流框架集成一节）：

AI 框架主要有三种编程执行形态，单算子模式、图模式（Ascend IR）和图捕获模式（aclgraph），因此 HCCL 也提供了对应的工作方式。

单算子模式与图捕获模式（aclgraph）下，AI 框架直接调用 HCCL 的 C 语言接口，下发通信算子到加速引擎执行……

三种形态（官方给出的名字）

#	官方名称	括号里的补充
1	单算子模式	——
2	图模式	（Ascend IR）
3	图捕获模式	（aclgraph）

⚠️ 数据纪律提示：官方此处只给了三种形态的名字与一条关于 HCCL 调用方式的说明。三种形态的完整机制与适用场景，官方散落在不同文档里，本课只讲与"部署/排查"相关的部分，不替官方补全机制细节。

从这段原文能确定的一件事

官方明确说：单算子模式与图捕获模式下，"AI 框架直接调用 HCCL 的 C 语言接口"。

这条信息本身很有用（归纳）：它说明在这两种形态下，框架和底层库之间是"直接调用"的关系 —— 中间层少，出问题时离底层更近。

第四段 · 两条主要路径：一个一个算，还是整图打包算

部署现场最常遇到的是前两种（单算子模式、图模式）。 用一句话说清它们的差别（归纳）：

	单算子模式	图模式
谁来组织执行顺序	框架自己，一条一条下发	先编译成一张图，再整图执行
每次算什么	一个算子	一整段计算图
官方括号里的标识	——	Ascend IR
类比（归纳）	随点随做的快餐	先排版再印刷

⭐ 为什么这个差别对部署很重要

因为"报错发生的时机"不同（归纳）：

	单算子模式	图模式
错什么时候暴露	执行到那一条算子时才暴露	编译那张图的时候就可能暴露
典型报错观感	"运行到某个算子了"	"图编译/构图阶段"
排查的起点	定位到哪个算子（回 B2）	定位到图编译这一段（回 B3 的版本配套）

归纳（本课最实用的一条）： 遇到报错先问一句：现在这个模型跑的是单算子模式还是图模式？ 答案不同，排查的第一站就不同。

与 C2 的呼应：`.npu()` 属于哪一种

C1/C2 讲过：a = torch.randn(3, 4).npu(); print(a + a) 里， .npu() 是把张量搬到 NPU 上，a + a 是一次加法。

这种"写一句算一句"的写法，就是单算子模式的形态（归纳）—— 它简单、好验证，适合"刚装完、先确认能用"的场景（也就是 C1 那行验收命令的目的）。

图模式则需要额外的编译路径 —— 这正是 TorchAir 的位置（第六段）。

第五段 · 怎么"接进来"：两条接入方式

算子要能被框架调到，就得"接入"。官方把这件事按形态分了两条路。

官方原文（Aclnn 算子工程化开发一节）

aclnn 单算子 API：算子工程编译后基于算子原型自动生成的 C 语言 API，应用程序可通过该接口直接调用自定义算子。

工程化算子开发是指基于自定义算子工程完成算子实现、编译部署和调用验证的开发方式，主要面向 CANN 相关场景对接： 单算子调用场景通过 aclnn API 完成接入，算子入图场景通过 GE……

两条接入方式对照（本段核心）

	单算子调用	算子入图
接入方式（官方原文）	通过 `aclnn` API 完成接入	通过 GE
`aclnn` 是什么（官方原文）	算子工程编译后基于算子原型自动生成的 C 语言 API	——
特点	应用程序可直接调用	走图那一层

⭐ 这里解答了 B2 留下的一个悬念（归纳）：

B2 说过：ops 包里有「单算子 API 执行（如 aclnn 类 API）动态库/静态库文件」。 现在知道它给谁用了 —— 给"单算子模式"这条接入路径用。

所以 B2 的算子库和 C 层的框架，是通过 aclnn 接口连起来的。

`aclnn` 这个名字怎么读（归纳）

acl = Ascend Computing Language（昇腾计算语言，这是昇腾的原生 API 体系）
nn = neural network（神经网络）
合起来 = 面向神经网络的昇腾单算子 API

记住这个命名规律：昇腾很多 API 都以 acl 开头 —— 看到 acl 就知道"这是到昇腾这一步了"。

第六段 · 适配插件：两种形态，两个名字

自定义算子要接到框架上，光有 CANN 侧的代码还不够，还要"插件适配"。 官方把这件事也按形态分了两条路 —— 两个插件名字。

官方原文（TBE&AI CPU 算子开发 · 适配插件开发（PyTorch 框架））

PyTorch 框架单算子模式下的适配插件开发流程和具体样例请参见《TorchNPU 框架特性》中的基于 OpPlugin 算子适配开发章节。 图模式下自定义算子入图的开发指导请参见《TorchAir 使用指南》中的自定义算子入图章节。

归纳成一张表（本节最有价值）

形态	适配插件（官方名称）	官方文档在哪
单算子模式	OpPlugin	《TorchNPU 框架特性 · 基于 OpPlugin 算子适配开发》
图模式	TorchAir	《TorchAir 使用指南 · 自定义算子入图》

⭐ 这样看下来，"那一串名词"其实是有结构的（归纳）：

执行形态              接入方式              适配插件
────────────────────────────────────────────────
单算子模式    →     aclnn API     →     OpPlugin
图模式        →     GE            →     TorchAir

四个名词，就是两条路的两端。 看官方文档时遇到任何一个，都能靠这张表找到它的邻居。

再回到 TorchAir（把 C2 的定义接上）

C2 引过的官方定义：

TorchAir 是为 TorchNPU 提供图模式能力的扩展库…… 对接 PyTorch 的 dynamo 特性，将 PyTorch 的 FX 计算图转换为昇腾的 GE 计算图……

现在这句话的位置清楚了（归纳）：

TorchAir 是"图模式"这条路上的适配插件。 它做的事：把 PyTorch 那边的计算图（FX 计算图）翻译成昇腾这边能执行的图（GE 计算图）。 这就是第五段说的"通过 GE 接入"的具体落地。

所以 C2 留下的"图模式"这个钩子，在 C3 收口了。

第七段 · 不同框架支持的形态不一样（部署要留意的差异）

官方原文（AI 框架算子适配 · 概述）：

本章节内容介绍 AI 框架调用自定义算子的方法。如下图所示， PyTorch 支持单算子和图模式两种，TensorFlow 仅支持图模式。

AI 框架调用时，除了需要提供 CANN 框架调用时需要的代码实现文件， 还需要进行插件适配开发。

从这一句能读出三件事

① 框架和形态不是自由组合的

框架	支持单算子模式	支持图模式
PyTorch	✅	✅
TensorFlow	❌	✅（仅支持图模式）

② 不管哪种框架，"插件适配开发"这一步都躲不掉 （官方原文："除了需要提供……代码实现文件，还需要进行插件适配开发"）。 这与 C1/C2 的结论一致：昇腾不是一个"装完就能用"的普通设备，它是需要"适配"的。

③ 报错时"我在哪条路"这件事，可能不是你能选的（归纳）——

如果你用的是 TensorFlow，那就只有图模式一条路 —— 遇到问题直接往"图"这条线查，不用在单算子模式上浪费时间。

⭐ 部署视角的一个实用提醒

"我的模型跑的是哪种模式"这个问题，有明确的答案来源（归纳）：

情况	大概是哪种
刚装完环境，跑 C1 那行验收命令	单算子（写一句算一句）
用 TensorFlow	只能是图模式
用 PyTorch，代码里调用了 `torch.compile` 或框架的图化特性	图模式（涉及 TorchAir / dynamo）
不确定	查你用的推理/训练框架的文档——它决定了这件事

⚠️ 本课不替官方给出"怎么强制指定模式"的方法 —— 那是各框架文档的内容，本课只讲"这个概念存在、它影响排查方向"。

第八段 · 出问题怎么查

先定位"我在哪条路"

排查的第一步不是看报错，是先确定这条路（归纳）：

① 我的框架是哪个？          → C2（PyTorch / MindSpore / TensorFlow …）
② 它支持哪些执行形态？      → 本课第七段（TensorFlow 只有图模式）
③ 我这次跑的是哪种形态？    → 看代码里的写法 / 框架特性是否开启
④ 然后才是看报错

按形态分流的排查表

形态	典型问题	第一站
单算子模式	"算子找不到""算子不支持"	B2（算子库 / ops 包按型号）
单算子模式	某个算子算错	B2（算子实现）+ 该算子的文档
图模式	图编译失败 / 构图阶段报错	B3（版本配套）+ GE 相关文档
图模式	图能建但不能执行	版本配套 + B3 的算子库
两种都可能	换了终端就不行	B1（环境变量）
两种都可能	容器里不行	B5（`--device` / 挂载）
自定义算子	自己写的算子在单算子模式下不生效	OpPlugin（官方文档）
自定义算子	自己写的算子不能入图	TorchAir（官方文档）

⭐ 一个最省时间的判断法

遇到框架层的报错，先回答一个问题：报错发生在"跑的时候"还是"建图的时候"。

答案	方向
跑的时候（执行到某一步才报）	单算子模式 → 往 B2（算子库）查
建图的时候（一开始就报，还没出结果）	图模式 → 往 B3（版本配套）+ GE 查

这个时间点上的差别，比报错文字本身更能指示方向。

第九段 · 小结与下一课

三句话带走

官方把 AI 框架的编程执行形态归为三种：单算子模式、图模式（Ascend IR）、图捕获模式（aclgraph）。部署现场遇到的主要是前两种。
两条路的四个名词，是有结构的： 单算子模式 → aclnn API → OpPlugin； 图模式 → GE → TorchAir。
框架支持的形态不一样：官方原文PyTorch 支持单算子和图模式两种，TensorFlow 仅支持图模式 —— 这决定了你遇到问题时该往哪条线查。

C 层到这里收口

回头看这一层讲了什么：

C1  TorchNPU 是什么      → 框架怎么"接进来"（插件路线、五维版本对应）
C2  多框架               → 有哪些路可走（插件 vs 原生）、图模式是什么
C3  框架适配原理         → 接进来之后，"算子怎么跑到芯片上"（三种形态、两条接入方式）

C 层的一句话总结：

L2 这一层的全部内容，是"翻译" —— 把框架的语言（张量、计算图）翻译成昇腾能执行的语言（kernel、GE 图）。 TorchNPU 是这本词典的封面，aclnn 和 GE 是两条装订线。

本课在体系里的位置

─── L0 硬件与环境（A 层，已完成）─── A0 / A1 / A2 / A3
─── L1 基础软件（B 层，已完成）─── B1 / B2 / B3 / B4 / B5
─── L2 框架（C 层，本课收官）───
C1 TorchNPU 是什么：PyTorch 怎么接到昇腾上        ✅
C2 多框架：昇腾上装哪个框架，几条路有什么不一样     ✅
C3 框架适配原理：一个算子从框架到芯片走了哪条路      ★ 本课
─── 排障（E 层）─── E1

本课留下的"钩子"

钩子	在哪一课填
推理服务层（MindIE / vLLM / SGLang）怎么搭在这层之上	D 层
服务怎么起停、怎么调优、端口怎么配	D 层
图编译失败的完整排查	E 层 / D 层
`msModelSlim` 量化属于哪一层（A0 地图里在 L4 应用层）	D 层 / 后续

课后自测（3 题）

官方归纳的三种编程执行形态分别叫什么？括号里的补充分别是什么？
把四个名词配对：aclnn / GE / OpPlugin / TorchAir —— 哪个属于单算子模式、哪个属于图模式？
一个报错在"模型刚开始跑"的时候就出现了，另一个在"跑到第 200 步"才出现。按本课的判断法，它们更可能分别属于哪种形态？各该往哪查？

附录 A · 本课引用的官方出处

内容	出处
三种编程执行形态（单算子模式 / 图模式（Ascend IR）/ 图捕获模式（aclgraph））与 HCCL 的对应工作方式	官方《HCCL 集合通信库 · 主流框架集成》 `zh/CANNCommunityEdition/920beta2/commlib/hcclug/docs/zh/user_guide/framework_integration.md`
`aclnn` 单算子 API 的定义（基于算子原型自动生成的 C 语言 API）；「单算子调用场景通过 aclnn API 完成接入，算子入图场景通过 GE」	官方《Ascend C 算子开发 · 高级编程 · Aclnn 算子工程化开发 · 概述》 `.../aclnn_operator_development/overview.md`
「PyTorch 框架单算子模式下的适配插件开发……基于 OpPlugin 算子适配开发」；「图模式下自定义算子入图……《TorchAir 使用指南》」	官方《TBE&AI CPU 算子开发 · 算子开发过程 · 算子适配 · 适配插件开发（PyTorch 框架）》 `zh/CANNCommunityEdition/920beta2/others/tbeaicpudevg/atlasopdev_10_0086.html`
「PyTorch 支持单算子和图模式两种，TensorFlow 仅支持图模式」	官方《Ascend C 算子开发 · 高级编程 · AI 框架算子适配 · 概述》 `.../advanced_programming/ai_framework_adaptation/overview.md`
TorchAir 的定义（对接 dynamo、FX 计算图 → GE 计算图）	官方 TorchNPU《TorchAir · 简介》（另见 C1/C2）
「基于 OpPlugin 算子适配开发」章节与「自定义算子入图」章节的指引	官方 TorchNPU《框架特性 · 自定义算子适配开发》 `zh/Pytorch/2610/devguide/fwfeatures/docs/zh/framework_feature_guide_pytorch/adaptation_overview_opplugin.md`
ACL（Ascend Computing Language，昇腾计算语言）：官方描述为「一套用于在昇腾平台上开发深度神经网络应用的 C 语言 API 库，提供运行资源管理、内存管理、模型加载与执行、算子加载与执行、媒体数据处理等 API」	官方 ACL 相关文档（`search_docs` 检索「Ascend Computing Language」命中）
ops 包中含 aclnn 类 API 动态库/静态库（与 B2 呼应）	官方《安装 CANN · 安装 ops》（另见 B2）

⚠️ 数据纪律提示： ① 本课只讲三种执行形态的"名字、官方给的一句话说明、以及与部署排查的关系"； 三种形态的完整机制、性能差异、如何强制指定，官方文档另有专门章节 —— 本课不替代、不推测； ② ACL 的全称（Ascend Computing Language，昇腾计算语言）已核实为官方表述；但 aclnn 的命名解读（acl+nn）仍是归纳，非官方口径； ③ 本课未给出"某框架某版本支持哪些形态"的完整矩阵 —— 以官方《版本说明》与框架文档为准； ④ 所有标注「归纳」的部分（模式与报错时机的对应、两级判断法）非官方口径。

附录 B · 本课出现的名词与命令详解

名词：三种执行形态

名词	官方给出的说明	拆解（归纳）
单算子模式	AI 框架直接调用底层 C 语言接口，下发算子执行	一条一条算
图模式（Ascend IR）	——	先编译成图，整图执行；`IR` = 中间表示
图捕获模式（aclgraph）	与单算子模式一样，AI 框架直接调用 C 语言接口	把执行过程"录"成一张图（`graph` 字面即"图"）

名词：`aclnn`

全称拆解（归纳）：acl（Ascend Computing Language，昇腾计算语言）+ nn（neural network）
官方定义：算子工程编译后基于算子原型自动生成的 C 语言 API，应用程序可通过该接口直接调用自定义算子
用在哪：单算子调用场景
为什么部署的人会遇到它：ops 包里就带着 aclnn 类 API 的动态库/静态库（B2）—— 它是框架和算子库之间的那个接口

名词：GE

官方原文语境：「算子入图场景通过 GE……」
它是什么（归纳）：图执行那一层的组件
和 TorchAir 的关系：官方说 TorchAir 将 PyTorch 的 FX 计算图转换为昇腾的 GE 计算图 —— GE 计算图就是"昇腾侧的图"

名词：OpPlugin 与 TorchAir

名词	官方定位	对应形态
OpPlugin	《TorchNPU 框架特性》中的算子适配开发章节	单算子模式
TorchAir	为 TorchNPU 提供图模式能力的扩展库；随 TorchNPU 包发布	图模式

名词：Ascend IR

出现在：官方对"图模式"的括注里 —— 图模式（Ascend IR）
IR 是编译器领域通用缩写（Intermediate Representation，中间表示）
归纳："图模式"在昇腾这边的图，叫 Ascend IR

命令：C1 那行验收命令属于哪种形态（回顾）

python3 -c "import torch;import torch_npu; a = torch.randn(3, 4).npu(); print(a + a);"

属于：单算子模式（写一句算一句，没有整图编译）
验证目的（C1）：版本对不对、能不能算、算在昇腾上
本课补充：它验的是"单算子这条路通不通"，不保证图模式那条路也通 —— 这是它作为验收命令的边界

参数/名词速查表

名词	一句话
单算子模式	一条一条算
图模式（Ascend IR）	先编译成图，整图算
图捕获模式（aclgraph）	把执行过程录成图
`aclnn`	单算子调用的 C 语言 API（在 ops 包里）
GE	图执行那一层
OpPlugin	单算子模式的适配插件
TorchAir	图模式的适配插件（随 TorchNPU 发布）
Ascend IR	昇腾侧的中间表示

附：C1 / C2 / C3 的分工（避免重复）

问题	在哪一课
TorchNPU 是什么、五维版本对应、验收命令拆解	C1
昇腾支持哪些框架、插件路线 vs 原生路线、MindSpore 怎么装、图模式是什么	C2
三种执行形态、两条接入方式（aclnn / GE）、两个适配插件（OpPlugin / TorchAir）、框架支持差异	本课（C3）
推理服务层怎么搭在上面	D 层
按报错定位层	E1