昇腾 AI 部署完整流程图：五层结构与每层用什么工具装

版本：v2（v1 只有"层 + 职责"，本版补上每层用什么工具装、按什么顺序装）编制：观澜｜日期：2026-10-04｜级别：T3 框架级 素材：昇腾官方文档实时检索（CANN 9.2.0-beta.2 / HDK / TorchNPU 26.1.X / MindIE 3.1.0 / MindCluster 26.1.0）定位：这是整套课件体系的总图。后面每一课，都挂在这张图的某个节点上。

〇、这张图补了什么

	v1（A0 那张）	v2（本图）
有几层	✅ 5 层	✅ 5 层
每层干什么	✅	✅
每层用什么工具装	❌	✅ 本版新增
装的顺序	❌	✅ 本版新增
每层怎么验、日志在哪	部分	✅ 全

一、总图：五层 + 每层的部署工具

┌──────────────────────────────────────────────────────────────────┐
│  L4  应用层                                                      │
│      职责：模型本身——权重、量化版本、配置文件                    │
│      工具：msModelSlim（量化）｜权重转换工具                     │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  L3  服务层                                                      │
│      职责：对外提供推理接口——收请求、组批、调度、返回            │
│      工具：MindIE（Docker / K8s）｜vLLM ｜SGLang                 │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  L2  框架层                                                      │
│      职责：把 PyTorch / MindSpore 的调用翻译成芯片能懂的         │
│      工具：TorchNPU（Whl / 源码 / Pip）｜MindSpore               │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  L1  基础软件层                                                  │
│      职责：算子库、编译器、运行时、通信库                        │
│      工具：Toolkit 包 + ops 包 + NNAL 包｜set_env.sh             │
│      装法：7 种官方方式                                          │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  L0  硬件与驱动层                                                │
│      职责：真正的计算；驱动让系统认得卡，固件跑在卡上            │
│      工具：HDK 驱动包 + 固件包（.run）                           │
└──────────────────────────────────────────────────────────────────┘

二、逐层详解

L0 · 硬件与驱动层

职责：驱动让操作系统认得这张卡；固件是运行在卡上的程序。

部署工具：HDK 驱动包 + 固件包（都是 .run 格式）

包名格式（官方示例）：

Ascend-hdk-310b-npu-driver_x.x.x_linux-{arch}.run      ← 驱动
Ascend-hdk-...-npu-firmware_x.x.x_linux-{arch}.run     ← 固件

⭐ 关键：装配顺序是有讲究的（官方原文）

场景	顺序
首次安装	驱动 → 固件
覆盖安装 / 升级	固件 → 驱动

⚠️ 顺序反了会出问题。 这是新手最容易踩的坑之一。

⭐ 关键参数：--install-for-all

官方原文：首次安装过程中如果使用了 --install-for-all 参数，建议覆盖安装中也保留，否则会导致 NPU 设备权限变更。

标准操作步骤（官方命令）：

# 1. 加可执行权限
chmod +x Ascend-hdk-310b-npu-driver_x.x.x_linux-{arch}.run

# 2. 校验安装包的一致性和完整性（SHA256）
./Ascend-hdk-310b-npu-driver_x.x.x_linux-{arch}.run --check

# 3. 安装
./Ascend-hdk-310b-npu-driver_x.x.x_linux-{arch}.run --full

# 3b. 指定安装路径时
./Ascend-hdk-310b-npu-driver_x.x.x_linux-{arch}.run --full --install-path=/test/HiAI/

默认安装路径：/usr/local/Ascend
安装日志路径：/var/log/ascend_seclog/ascend_install.log

怎么验证：

npu-smi info          # 能看到卡 = L0 就位
npu-smi -v            # 查 npu-smi 工具自身版本

日志：/var/log/ascend_seclog/ascend_install.log

L1 · 基础软件层（CANN）

职责：算子库、编译器、运行时（AscendCL）、通信库（HCCL）。环境变量是这一层的开关。

CANN 由几个包组成（这是新手最容易糊涂的地方）：

包	是什么
Toolkit 包（开发套件）	开发所需的主体（编译、运行时等）
ops 包（算子包）	算子基础框架 + 算子库（math / nn / cv / transformer / ras）+ TBE 算子 + HCCL 集合通信库 + HIXL 单边通信库 + DVPP 库
NNAL 包	神经网络加速库，含 ATB 加速库等

⭐ 官方安装方式一共 7 种（官方 InstallType 取值，原文）：

安装方式	官方 ID	适用系统
在线安装（Yum）	`netyum`	openEuler、CentOS、Kylin、BCLinux、UOS、AntOS、AliOS、CTyunOS、CULinux、Tlinux、MTOS、vesselOS
在线安装（Apt-get）	`netapt`	Ubuntu、Debian、veLinux
在线安装（Conda）	`netconda`	全部
在线安装（Pip）	`netpip`	全部
离线安装（驱动 & Toolkit 合一包）	`localpack`	全部
离线安装（驱动 & Toolkit 独立包）	`local`	全部
容器镜像安装	`netdocker`	全部

官方建议：初次上手或想快速装，参考《CANN 快速安装》。

离线安装的标准命令（官方原文）：

# 安装 Toolkit
bash ./Ascend-cann-toolkit_9.2.0-beta.2_linux-aarch64.run --install

# 安装 ops 包（示例：Ascend 950 系列 / aarch64）
wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%209.2.T3/Ascend-cann-950-ops_9.2.0-beta.2_linux-aarch64.run
bash ./Ascend-cann-950-ops_9.2.0-beta.2_linux-aarch64.run --install

默认安装路径： - root 用户：/usr/local/Ascend - 非 root 用户：${HOME}/Ascend

⭐ 环境变量配置（装完必须做，否则一开新终端就失效）：

source /usr/local/Ascend/cann/set_env.sh          # root 安装
source ${HOME}/Ascend/cann/set_env.sh             # 非 root 安装

# NNAL 的额外环境变量
source /usr/local/Ascend/nnal/atb/set_env.sh      # ATB 加速库

关键环境变量（官方定义）：

变量	管什么
`ASCEND_HOME_PATH`	同 `ASCEND_TOOLKIT_HOME`，Toolkit 安装路径
`ASCEND_OPP_PATH`	算子库根目录
`ASCEND_AICPU_PATH`	AI CPU 组件安装路径
`PATH` / `LD_LIBRARY_PATH` / `PYTHONPATH`	可执行文件 / 动态库 / Python 模块查找路径
`TOOLCHAIN_HOME`	工具链安装路径

怎么验证：

cd ${HOME}/Ascend/cann/$(arch)-linux      # 进安装信息目录
cat ascend_toolkit_install.info           # 看 version 字段 = 装的版本
echo $ASCEND_HOME_PATH                    # 非空
echo $ASCEND_OPP_PATH                     # 非空

⚠️ 一个重要的官方说明：CANN 可以在非昇腾设备上安装（官方有专门章节）。但要注意：这解决的是"能装、能编译"——没有卡仍然跑不了推理和训练。

L2 · 框架层

职责：把上层写的算法，翻译成芯片能懂的东西。

部署工具：TorchNPU（PyTorch 场景），官方给三种安装方式：

方式	说明
方式一：离线安装（Whl）	下载 whl 包本地装
方式二：源码安装	从源码编译
方式三：在线安装（Pip）	用 Pip 装（官方有《快速安装》页面）

官方建议路径：Pip 方式最快，官方提供了 PyTorch + TorchNPU 的配套版本选择页。

怎么验证：

import torch
import torch_npu
from torch_npu.contrib import transfer_to_npu   # 开启自动迁移
print(torch.npu.is_available())                 # 期望 True

L3 · 服务层

职责：对外开端口、收请求、组批、调度、返回结果。

三条官方路径：

框架	官方部署方式
MindIE	Docker 镜像（《准备 MindIE Motor 镜像》）｜K8s（《基于 K8s 多容器 PD 分离服务部署》）
vLLM	昇腾侧 vLLM 推理开发路径
SGLang	昇腾侧 SGLang 推理开发路径

MindIE 日志：~/mindie/log（+ debug / security）命名格式：mindie-<组件名称>_<pid>_<时间戳>.log

怎么验证：端口监听 + 从外面 curl 调一次。

L4 · 应用层

职责：模型本身——权重、量化版本、配置文件。

工具： - msModelSlim（模型量化，MindStudio 26.1.0 组件）—— 含《快速入门》《权重转换与使用》 - 权重转换工具（含 AutoAWQ / AutoGPTQ 等案例）

三、横向工具：贯穿各层的"通用件"

这些不属于某一层，而是随时要用。

工具	干什么	主要用在	什么时候用
`npu-smi`	看卡：型号、温度、显存、进程	L0	随时（第一件事）
`ascend-dmi`	设备检测	L0	验机、上线前体检
`set_env.sh`	配置 CANN 环境变量	L1	装完 + 每次开新终端
`msnpureport`	导出 Device 侧日志（slog / syslog / 黑匣子）	L0/L1	出故障时
`asys`	一键收集全部故障信息	全局	出故障时（⚠️ 集群/容器/虚机/云不支持）
`msModelSlim`	模型量化	L4	模型准备阶段

⚠️ 官方提示：npu-smi 不支持多线程并发使用。

四、完整部署顺序（照这个顺序做）

第 1 步  确认硬件
         └─ 卡装好、上电；确认机器架构（aarch64 / x86_64）

第 2 步  【L0】装驱动 + 固件
         └─ 首次：驱动 → 固件      ⚠️ 顺序不能反
         └─ 升级：固件 → 驱动
         └─ 用 --install-for-all 就一路都用
         └─ 验证：npu-smi info 能看到卡

第 3 步  【L1】装 CANN
         └─ 选一种装法（7 种 · 初学者用《CANN 快速安装》）
         └─ Toolkit 包 → ops 包 →（如需）NNAL 包
         └─ 验证：cat ascend_toolkit_install.info

第 4 步  【L1】配环境变量
         └─ source .../cann/set_env.sh
         └─ 写进 ~/.bashrc（否则新终端失效）
         └─ 验证：echo $ASCEND_HOME_PATH 非空

第 5 步  【L2】装框架（TorchNPU）
         └─ 三选一：Whl 离线 / 源码 / Pip 在线
         └─ 验证：torch.npu.is_available() == True

第 6 步  【L3】部署推理服务
         └─ 三选一：MindIE（Docker / K8s）/ vLLM / SGLang
         └─ 验证：端口监听 + curl 调通

第 7 步  【L4】准备模型
         └─ 权重转换 / 量化（msModelSlim）
         └─ 验证：模型能加载、结果正确

第 8 步  体检
         └─ 把上面每步的验证命令跑一遍

五、一页速查（建议存手机）

每层：用什么装 → 怎么验 → 坏在哪看日志

层	装什么	用什么装	怎么验证	日志
L0	驱动 + 固件	`.run` 包（HDK）	`npu-smi info`	`/var/log/ascend_seclog/ascend_install.log`
L1	Toolkit / ops / NNAL	7 种方式（run 包 / yum / apt / conda / pip / 容器）	`cat ascend_toolkit_install.info`	`${HOME}/ascend/log`
L2	TorchNPU	Whl / 源码 / Pip	`torch.npu.is_available()`	同上
L3	MindIE / vLLM / SGLang	Docker 镜像 / K8s / 源码	端口 + curl	`~/mindie/log`
L4	模型	msModelSlim / 权重转换	能加载、结果对	—

三条最容易踩的坑

驱动/固件顺序：首次驱动→固件，升级固件→驱动。
环境变量不写进 ~/.bashrc → 新终端就失效，报"找不到库"。
--install-for-all 中途丢掉 → NPU 设备权限变化。

六、这张图怎么用（和课件的对应关系）

图上节点	对应课件	现在状态
总览	总纲 · 完整流程图 · 一页速查	✅ 已完成
全图	A0 一张地图	✅ 已完成
报错怎么读	E1 报错定位法	✅ 已完成
L0 硬件与驱动	A1–A3	✅ 已完成
L1 CANN	B1–B5	✅ 已完成
L2 框架	C1–C3	✅ 已完成
L3 服务	D1–D5	✅ 已完成
场景实战	F1–F7 全部写完并上线	✅ 已完成（含开源模型部署上架 F6、模型能力到业务落地 F7）
企业落地（G 层）	G1–G10 全部写完并上线	✅ 已完成（私有化与安全、RAG、知识库、检索精排、问答编排、评估、容量成本、企业安全、进阶检索） ⚠️ 合规部分（等保/数据分级/审计留存）按用户安排另出文章，不进课件
排障展开	E1–E4 全部写完	✅ 已完成

进度：38 篇课件 + 总纲 / 完整流程图 / 一页速查 + 7 篇浓缩指南全部写完并上线（A–G 七层无缺课）。

F 层（场景实战）规划：把前面 A–D 的零件串成真实场景，按官方文档四条主线展开 —— 模型迁移（手工 / 自动 / 迁移报告）、单卡推理闭环、多卡与分布式、精度调试、性能调优、国产算力适配。

附录 · 本图引用的官方出处

内容	官方来源
7 种安装方式（InstallType 取值表）	CANN 9.2.0-beta.2《选择安装场景》
离线安装命令 / 默认路径 / 环境变量	CANN 9.2.0-beta.2《在非昇腾设备上安装 CANN》
ops 包内容与 wget 地址	同上
`set_env.sh` 路径与变量清单	CANN 9.2.0-beta.2《安装后自动配置环境变量》
驱动/固件顺序、`--install-for-all`、安装命令、日志路径	《NPU 驱动和固件安装指南 · 物理机安装与卸载》
CANN 安装方式目录（yum/apt/conda/pip/容器/deb/rpm/冷补丁）	CANN 9.2.0-beta.2 软件安装目录树
TorchNPU 三种安装方式	TorchNPU 26.1.X《安装 TorchNPU》
MindIE 镜像与 K8s 部署	MindIE 3.1.0《MindIE Motor》
MindIE 日志路径	MindIE 3.1.0《查看日志》
msModelSlim	MindStudio 26.1.0《模型量化 msModelSlim》
`msnpureport` / `asys`	CANN 9.2.0-beta.2《收集进程中断问题信息》

⚠️ 数据说明： - 所有命令、路径、参数名均来自官方文档原文，未做推测性补充。 - .run 包的具体文件名随产品型号和版本变化，本图用官方示例格式 + x.x.x / {arch} 占位。 - "非昇腾设备可装 CANN" 解决的是"能装能编译"，不等于没有卡也能跑 —— 这一点我按官方口径写明，未夸大。

附录 B · 本图出现的命令详解（安装步骤逐条拆开）

看图对照：本附录按"部署 8 步"的顺序排列，和第四节的流程一一对应。

第 2 步：装驱动和固件

chmod +x 文件 - 含义：给文件加上"可执行"权限。chmod = change mode（改权限），+x = 加上 execute（执行）权限。 - 拆解：chmod（命令）＋ +x（加执行权限）＋文件名 - 用法：

chmod +x Ascend-hdk-310b-npu-driver_x.x.x_linux-aarch64.run

期望：没有任何输出（命令无输出 = 成功）
不过会怎样：不加这一步直接运行，会报 Permission denied（权限不够）

./文件 --check - 含义：运行当前目录下的这个文件，并带上 --check 参数，用来校验安装包的一致性和完整性（官方说明使用 SHA256 校验）。 - 拆解：./（表示"当前目录下的这个文件"）＋文件名＋ --check（参数）

⭐ 为什么必须加 ./：不加 ./ 时，系统会去 PATH 环境变量里列出的那些目录找这个命令——而你下载的安装包不在那些目录里，所以会报 command not found。加了 ./ 就是明确告诉系统"就在当前目录找"。 - 用法：

./Ascend-hdk-310b-npu-driver_x.x.x_linux-aarch64.run --check

期望：提示校验通过
不过会怎样：提示 MD5/SHA256 相关警告 → 包可能下载不完整，重新下载

./文件 --full - 含义：完整安装。官方安装命令。 - 拆解：--full 是安装参数（完整安装模式） - 用法：

./Ascend-hdk-310b-npu-driver_x.x.x_linux-aarch64.run --full

# 指定安装路径时（--install-path= 后面跟路径）
./Ascend-hdk-310b-npu-driver_x.x.x_linux-aarch64.run --full --install-path=/test/HiAI/

期望：安装过程有输出，最后提示成功
不过会怎样：看报错 → 常见是权限问题（username not permission for root，官方案例 case_92819）
日志：/var/log/ascend_seclog/ascend_install.log

第 3 步：装 CANN

wget 网址 - 含义：从网上下载文件。wget = web get。 - 拆解：wget（命令）＋文件的网址 - 用法：

wget https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/.../xxx.run

期望：当前目录出现下载好的文件，并显示下载进度
不过会怎样：command not found → 系统没装 wget（yum install wget 或 apt-get install wget）

bash ./文件 --install - 含义：用 bash 这个解释器来执行安装脚本，并带上 --install 参数（表示安装动作）。 - 拆解：bash（解释器名）＋ ./文件（要执行的脚本）＋ --install（参数）

和 ./文件 的区别：./xxx.run 也执行，但依赖文件自己带的可执行权限；bash ./xxx.run 是明确指定用 bash 来跑，不受"有没有可执行权限"影响。官方给的 CANN 安装命令用的是 bash ./... --install 这种写法。 - 用法：

bash ./Ascend-cann-toolkit_9.2.0-beta.2_linux-aarch64.run --install

期望：安装过程输出，最后提示成功
默认装到哪：
root 用户 → /usr/local/Ascend
非 root 用户 → ${HOME}/Ascend

cd 目录 - 含义：切换当前所在目录。cd = change directory。 - 拆解：cd（命令）＋目标目录路径 - 用法：

cd ${HOME}/Ascend/cann/aarch64-linux      # 进安装信息目录

配合使用：官方验证步骤是"进入安装信息文件目录"→ 再看文件
不过会怎样：No such file or directory → 路径不对，CANN 装的位置和你想的不一样

cat ascend_toolkit_install.info - 含义：看这个安装信息文件的内容。 - 期望：里面 version 字段显示的版本，和你要装的版本一致 → 安装成功 - 不过会怎样：文件不存在 → Toolkit 没装上

第 4 步：配环境变量

source .../set_env.sh - 含义：在当前终端窗口里执行环境变量配置脚本。 - 拆解：source（命令）＋ set_env.sh（官方提供的一键配置脚本） - ⭐ 关键点：source 不新开进程，所以脚本里的环境变量会留在当前窗口。反过来，如果你关掉终端再开一个，这些变量就没了——这就是"装完能用、新开终端就报错"的根本原因。 - 官方命令：

source /usr/local/Ascend/cann/set_env.sh          # root 安装
source ${HOME}/Ascend/cann/set_env.sh             # 非 root 安装
source /usr/local/Ascend/nnal/atb/set_env.sh      # 如装了 ATB 加速库

想永久生效：官方给的做法是把这些命令写进 ~/.bashrc，然后 source ~/.bashrc 立刻生效
不过会怎样：报"找不到文件" → 路径不对；或者没报错但新终端失效 → 没写进 .bashrc

export 变量=值 - 含义：定义一个环境变量，并让它传给后面启动的子进程。 - 拆解：export（命令）＋ 变量名=值 - 用法（官方给的 LD_LIBRARY_PATH 配置示例）：

export LD_LIBRARY_PATH=${HOME}/Ascend/cann/aarch64-linux/devlib/:$LD_LIBRARY_PATH

末尾的 :$LD_LIBRARY_PATH 意思是"把新的路径拼在原有路径前面"，这样不会把原来的库路径覆盖掉。这是个很常见的写法。 - 不过会怎样：只在当前窗口有效 —— 关掉终端就没了

echo $变量名 - 含义：把变量的值打印出来，用来确认它到底有没有设置成功。 - 拆解：echo（打印）＋ $变量名（$ = 取值） - 用法：

echo $ASCEND_HOME_PATH      # 期望：打印出一个真实路径
echo $ASCEND_OPP_PATH       # 期望：打印出算子库目录

不过会怎样：打印出空白 → 变量没设置 → set_env.sh 没 source

对照实验：echo ASCEND_HOME_PATH（不加 $）会把这一串字母原样打印出来——这样你就知道"没加 $"和"变量为空"是两回事。

第 5、6 步

（npu-smi info / npu-smi -v / Python 验证写法，详见第 A0 课附录 B，此处不重复。）

`~/.bashrc`

含义：这是当前用户的终端启动脚本——每开一个新的终端窗口，系统会自动执行它里面的内容。
~ 表示"当前用户的家目录"（如 /root 或 /home/xxx）
为什么重要：把 source set_env.sh 写进这里，就实现了"每次开终端自动配置好"，不用手动敲
用法（官方步骤）：

vi ~/.bashrc          # 打开这个文件，在最后一行后面添加 source 命令
                      # 在 vi 里按 :wq! 保存退出
source ~/.bashrc      # 让它立刻生效

不过会怎样：忘了写 → 每次新开终端都要手动 source 一遍，很容易忘

参数速查表

参数写法	含义
`--check`	只校验，不安装
`--full`	完整安装
`--install`	执行安装
`--install-path=路径`	指定装到哪个目录
`--install-for-all`	⚠️ 让所有用户可用；首次用了，覆盖安装也要保留，否则 NPU 设备权限会变
`-v`	version，看版本
`-d 0`	device 0，指定第 0 张卡
`-f 目录`	指定目标目录

进度快照（2026-10-09）

A–G 七层课件已全部写完（38 篇 / 约 24,700 行）：

层	课数	内容
A	4	A0 一张地图 / A1 驱动与固件 / A2 产品线与形态 / A3 HDK 是什么
B	5	B1 CANN 是什么 / B2 算子库与算子包 / B3 版本与共存 / B4 七种装法 / B5 装进容器
C	3	C1 TorchNPU / C2 多框架 / C3 框架适配原理
D	5	D1 L3 服务层 / D2 vLLM Ascend / D3 MindIE Motor / D4 PD 分离 / D5 可用性与调优
E	4	E1 报错定位法 / E2 日志在哪里 / E3 官方案例库用法 / E4 报错码速查
F	7	F1 模型迁移 / F2 精度调试 / F3 多卡与分布式 / F4 性能调优 / F5 国产算力适配 / F6 开源模型部署上架 / F7 模型能力到业务落地
G	10	G1 私有化 / G2 RAG 基础 / G3 知识库搭建 / G4 文档解析与切分 / G5 检索与精排 / G6 问答编排 / G7 效果评估 / G8 容量与成本 / G9 企业安全 / G10 进阶检索

并已产出七篇浓缩版《昇腾部署指南》（A–G，共 2,723 行；F 篇已并入 F6/F7）：

篇	文件
A	`昇腾部署指南_A_L0硬件与环境_20261006.md`
B	`昇腾部署指南_B_L1基础软件CANN_20261006.md`
C	`昇腾部署指南_C_L2框架_20261006.md`
D	`昇腾部署指南_D_L3服务_20261006.md`
E	`昇腾部署指南_E_排障_20261006.md`
F	`昇腾部署指南_F_场景实战_20261006.md`
G	`昇腾部署指南_G_企业落地_20261006.md`

待立项：H 层 · 模型定制（训练侧：MindSpeed LLM / 单样本微调 / 分布式训练）—— A–G 全在推理侧，官方四大开发场景里的「训练开发」仍是空白。