C 层部署指南 · L2框架
一页读懂这一层：让 Python 认得那张卡。 这一层要装的是让 AI 框架把调用翻译成对芯片的操作的东西 —— TorchNPU 就是干这个的。 装完的标准：那条"一行验四层"的命令能打印出矩阵。
本指南是 C 层 3 课的浓缩版（C1 TorchNPU 是什么 / C2 多框架 / C3 框架适配原理）， 只保留"装什么、干什么用、怎么装、怎么验"。
一、这一层的职能
| 项 | 内容 |
|---|---|
| 层号 | L2（框架层） |
| 一句话职责 | 把 PyTorch / MindSpore 的调用翻译成对芯片的操作。 |
| 它装的是 | 框架本体 + 昇腾适配组件（插件或原生包） |
| 装完的判据 | python3 -c "import torch; import torch_npu; a=torch.randn(3,4).npu(); print(a+a)" 能打印出矩阵 |
| 拿掉它会怎样 | 能跑普通 Python，但一碰 NPU 就报错（set_device 失败、EL0003 之类） |
| 它上面的谁 | L3 服务层（vLLM / MindIE）—— 服务是建在框架上的 |
⭐ 这一层最特殊的点：它要配的版本最多。
| 要配套的 | 说明 |
|---|---|
| PyTorch 版本 | 框架本体 |
| TorchNPU 版本 | 插件 —— 必须和 PyTorch 版本对上 |
| Python 版本 | 不同组件要求不同 |
| CPU 架构 | aarch64 / x86_64 |
| CANN 版本 | 下一层的接口 |
框架层的"五个版本要配套" —— 这是"能 import 但一跑就错"的头号原因。
二、这一层装什么（软件清单）
两条路线（选一条，不要都装）
| 路线 | 装几个包 | 包名特征 | 典型代表 |
|---|---|---|---|
| 插件路线 | 装两个：框架本体 + 插件 | 插件名带 npu |
PyTorch + TorchNPU |
| 原生路线 | 装一个 | 包名带 -ascend |
MindSpore（昇思） |
| PyTorch | MindSpore | |
|---|---|---|
| 装的东西 | PyTorch 本体 + 插件 | 一个包（包名带 -ascend） |
| 验证命令 | import torch_npu + .npu() |
mindspore.run_check() |
| 谁的框架 | PyTorch 官方的 | 昇思的 |
官方口径：CANN 向上支持「多种 AI 框架」，「包括 MindSpore、PyTorch、TensorFlow 等」 → 不止这三个，具体列表以官方为准。
⭐ PyTorch 侧的两个包
| 包 | 是什么 |
|---|---|
| PyTorch | 框架本体 —— ⚠️ 必须装 +cpu 版 |
| TorchNPU | 昇腾适配插件 —— 它让 PyTorch 认得 NPU |
为什么 PyTorch 要 +cpu 版：
昇腾不靠 CUDA —— 装带 CUDA 的版本没意义，还会冲突。
三、每个东西干什么用（一句话）
| 东西 | 一句话功能 |
|---|---|
| TorchNPU | 一个插件 —— 让 PyTorch 的调用能落到昇腾芯片上 |
.npu() |
把张量搬到 NPU 上（插件加的动作） |
torch.npu.device_count() |
看框架认了几张卡 |
torch.npu.is_available() |
框架认不认这张卡 |
run_check() |
MindSpore 的自检入口（看 platform [Ascend]） |
| TorchAir | 负责图模式那条编译路径（见第五节） |
| OpPlugin | 单算子模式下，把框架算子接到昇腾算子库（见第五节） |
四、怎么装（安装方法）
4.1 装两个包
# ① PyTorch —— 必须是 +cpu 版（昇腾不靠 CUDA）
pip3 install torch --index-url https://download.pytorch.org/whl/cpu
# ② TorchNPU 插件 —— 版本必须和上面的 PyTorch 对上
pip3 install torch-npu
⚠️ 装之前先确认三件事：
| 确认什么 | 命令 | 为什么 |
|---|---|---|
| Python 版本 | python3 -V |
不同组件要求不同 |
| 架构 | uname -m |
决定装哪个 wheel |
| CANN 是否生效 | echo $ASCEND_HOME_PATH |
没生效就装框架 = 装了也用不了 |
| 磁盘余量 | df -h / |
⚠️ 容器里根分区常常很小 |
⭐ 官方要求：装框架前，CANN 环境必须先
source好。 顺序：L0 → L1 → L2，跳层装一定出问题。
4.2 装完立刻验（这条命令值得背下来）
命令 python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
含义：官方给的验收命令 —— 一次验四件事 拆解：见下表（每个片段验的是不同的一层） 用法：直接执行（前提：已
sourceCANN 环境） 期望：打印一个 3×4 的数字矩阵 不过会怎样：报错的位置就是该查的层 —— 见下面的分层判断表
⭐⭐ 这一行短命令，其实一次性验了四件事（这就是"一行验四层"）：
| 命令片段 | 验的是什么 | 问题出在哪一层 |
|---|---|---|
import torch |
PyTorch 装上了 | L2 —— 框架本体没装 |
import torch_npu |
TorchNPU 插件装上了 | L2 —— 插件没装 / 装了非 +cpu 版 |
torch.randn(3, 4).npu() |
能把张量放到 NPU 上 | L0 / L1 —— 驱动、容器里卡没挂进来 |
print(a + a) |
NPU 上真能算出结果 | L1 —— 算子库（ops 包）或版本配套 |
⭐ 最有价值的一条：
a + a能打印出来，说明"算子库里有这个算子、而且能跑"。 如果import都成功、但一算就报算子相关的错 —— 那不是框架的问题，是 B 层的问题。
4.3 顺手再确认一次"框架认了几张卡"
命令 python3 -c "import torch, torch_npu; print('device count =', torch.npu.device_count())"
含义：看框架认了几张卡 期望：数字 ≥ 1 不过会怎样：
0→ 卡没被框架认出来 —— 回 A 层（驱动）和 B5（容器挂载） ⭐ 注意：框架看到的设备编号，可能和npu-smi里的编号不一样 —— 一律以实际为准
命令 python3 -c "import torch_npu; print(torch_npu.npu.is_available())"
含义：框架认不认这张卡 期望：
True不过会怎样：False→ 回 A / B 层查
五、怎么验证装对了（验证方法）
⭐ 先分「执行形态」—— 报错时机不同，排查起点不同
官方口径：AI 框架主要有三种编程执行形态 —— 单算子模式 / 图模式（Ascend IR）/ 图捕获模式（aclgraph）。
部署现场最常遇到前两种：
| 单算子模式 | 图模式 | |
|---|---|---|
| 谁来组织执行顺序 | 框架自己，一条一条下发 | 先编译成一张图，再整图执行 |
| 每次算什么 | 一个算子 | 一整段计算图 |
| 官方括号里的标识 | —— | Ascend IR |
| 什么时候出问题 | 执行到那一条算子时才暴露 | 编译那张图的时候就可能暴露 |
| 排查第一站 | 定位到哪个算子（回 B2） | 定位到图编译这一段（回 B3 版本配套） |
⭐ 本层最实用的一条归纳： 遇到报错先问一句：现在跑的是单算子模式还是图模式？ 答案不同，排查的第一站就不同。
那条"一行验四层"的验收命令属于哪种 ✓ —— 它写一句算一句，是典型的单算子模式 ✓（简单、好验证，适合"刚装完先确认能用" ✓）
图模式则需要额外的编译路径 —— 这正是 TorchAir 的位置（官方物，在 CANN 侧）。
⭐ 验收清单（四条全过 = 这一层完工）
| # | 判据 | 命令 | 通过标准 |
|---|---|---|---|
| ① | 框架本体装了 | python3 -c "import torch; print(torch.__version__)" |
打印版本号 |
| ② | 插件装了 | python3 -c "import torch_npu; print(torch_npu.__version__)" |
打印版本号 |
| ③ | 框架认得卡 | torch.npu.device_count() / is_available() |
≥1 / True |
| ④ | 卡上能真算 | 一行验四层那条命令 | 打印出矩阵 |
⭐ 第 ④ 条是最终判据 —— 前三条都过了但第 ④ 条不过，问题不在框架层。
六、三个最容易踩的坑
| # | 坑 | 症状 | 怎么办 |
|---|---|---|---|
| 1 | PyTorch 装成了 CUDA 版 | import torch_npu 失败 / 行为异常 |
卸掉重装 +cpu 版 |
| 2 | 两个包版本不配套 | 能 import，一跑就报错 | 查官方配套表，框架层要配五个版本 |
| 3 | 没 source CANN 就装框架 | import 失败，误以为包没装 |
先 source set_env.sh，再重试 |
⚠️ 还有一条容易误判的：
容器里 .npu() 报错 —— 先看是不是卡没挂进容器（回 B5）✓
不是框架的问题，装多少遍框架都没用 ✓
一个反直觉但很关键的点
| 现象 | 不是哪里坏了 | 该回哪层 |
|---|---|---|
.npu() 报错 |
❌ 不是"框架没装好" | L0 驱动 / B5 容器挂载 |
a + a 报算子相关错 |
❌ 不是"框架没装好" | B2 算子库 / B3 版本配套 |
⭐ 记法：框架层只负责"翻译"，不负责"有没有卡"和"有没有算子"。
七、这一层和其他层的关系
↑ L3 服务层（vLLM / MindIE） ← 服务建在框架之上
│
│ ★ 你在这一层 装：框架本体 + 适配组件（插件或原生包）
│ 验：一行验四层能打印出矩阵
│
↓ L1 基础软件（CANN） ← 框架靠它提供的算子库与接口
↓ L0 硬件与驱动 ← 卡得先被系统认出来
| 关系 | 说明 |
|---|---|
| 它依赖谁 | L1 + L0 —— CANN 没 source 好，装框架等于白装 |
| 谁依赖它 | L3 / L4 |
| 一句话定位 | 它是"翻译层" —— 上接框架语法，下接算子与芯片 |
附 · 命令速查（复制即用）
# 装（PyTorch 侧：装两个）
pip3 install torch --index-url https://download.pytorch.org/whl/cpu
pip3 install torch-npu
# 验（一条命令验四层 —— 最该记住的一条）
python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
# 分开验（定位到层）
python3 -c "import torch; print('torch', torch.__version__)"
python3 -c "import torch_npu; print('torch_npu', torch_npu.__version__)"
python3 -c "import torch, torch_npu; print('device count =', torch.npu.device_count())"
python3 -c "import torch_npu; print('available =', torch_npu.npu.is_available())"
# MindSpore 侧（原生路线：装一个包，包名带 -ascend）
python3 -c "import mindspore; mindspore.run_check()"
# 期望：输出里能看到 platform [Ascend]
# 前置确认
python3 -V ; uname -m ; echo "ASCEND_HOME_PATH=[$ASCEND_HOME_PATH]"
⭐ 判据速记：
- device count ≥ 1 ✓ → 框架认得卡
- 打印出矩阵 ✓ → 卡上真能算（这才是完工）
附 · 三个层的报错如何区分（这一节能省很多时间）
| 你看到 | 大概率在哪一层 | 先查什么 |
|---|---|---|
npu-smi: command not found |
L0 | 驱动装了吗 |
$ASCEND_HOME_PATH 为空 |
L1 | 有没有 source set_env.sh |
No module named 'torch' |
L2 | 框架没装 |
No module named 'torch_npu' |
L2 | 插件没装 / PyTorch 装错版本 |
.npu() 报错 |
L0 / 容器 | 卡在不在、挂进容器了吗 |
| 算子相关报错 | L1 | ops 包型号对不对（B2） |
本层浓缩自：
昇腾部署课件_C1_TorchNPU是什么/_C2_多框架/_C3_框架适配原理上一层：B 层 · L1 基础软件（CANN） 下一层：D 层 · L3 服务层