B 层部署指南 · L1基础软件CANN
一页读懂这一层：让程序找得到算子、找得到库。 这一层装的是 CANN —— 它不是一个软件，是一组包。 装完的标准：
echo $ASCEND_HOME_PATH有值（环境变量生效了才算数）。本指南是 B 层 5 课的浓缩版（B1 CANN 是什么 / B2 算子库 / B3 版本与共存 / B4 七种装法 / B5 装进容器）， 只保留"装什么、干什么用、怎么装、怎么验"。
一、这一层的职能
| 项 | 内容 |
|---|---|
| 层号 | L1（基础软件层） |
| 一句话职责 | 承上启下 —— 向上接 AI 框架，向下接芯片，中间还提供写程序的接口。 |
| CANN 全称 | Compute Architecture for Neural Networks（架构，不是库、不是驱动） |
| 它装的是 | 算子库、编译器、运行时、通信库 —— 一组包 |
| 装完的判据 | echo $ASCEND_HOME_PATH 有值 |
| 拿掉它会怎样 | 看得见卡，但程序找不到算子库、找不到动态库（报 check driver compatibility failed、Failed to load the libdcmi.so 之类） |
| 上电后的顺序 | 必须先过 L0（npu-smi info 有表），再动 L1 |
二、这一层装什么（软件清单）
⭐ CANN 不是一个包，是一组 —— 这解释了一个常见困惑： 为什么文档里一会儿说"装 CANN"、一会儿说"装 Toolkit"、一会儿又说"装 ops 包"？
因为"CANN"是这一组东西的总名。
| 包 | 官方名称 | 干什么 |
|---|---|---|
| Toolkit | 开发套件包（Toolkit） | 主包：编译、执行、算子库路径都在它名下 |
| Kernels / ops | 算子包 | 算子库本体（ASCEND_OPP_PATH 指向它的根目录） |
| NNAL | 神经网络加速库 | 一组加速库，其中包含 ↓ |
| ↳ ATB | ATB 加速库 | 一个加速库（有独立的 set_env.sh 与专属环境变量） |
| ↳ SiP | SiP 加速库 | 另一个加速库（同样有独立 set_env.sh） |
⚠️ 口径说明：上表结构出自官方安装与环境变量文档的实际分组。 各版本包的确切拆分以《版本说明》和下载页为准。
⭐ 算子包里到底有什么（官方清单）
官方原文：CANN 算子包集成一系列库文件，包括算子基础框架、 算子库（包含 math、nn、cv、transformer 和 ras）、TBE 算子、 HCCL 集合通信库、HIXL 单边通信库和 DVPP 库， 具体文件包括单算子 API 执行（如 aclnn 类 API）动态库/静态库文件、 算子源码以及 kernel 二进制文件。
| 算子库的五个域 | 大概是干什么的 |
|---|---|
| math | 数学类算子 |
| nn | 神经网络类算子（最常见的那批） |
| cv | 计算机视觉类算子 |
| transformer | Transformer 结构专用算子（大模型重度依赖） |
| ras | 随机数与采样类 |
| 包里的三类文件 | 谁在用 |
|---|---|
| aclnn 类 API 的动态库/静态库 | 框架层（PyTorch 等）调用 |
| 算子源码 | 想看实现、改算子的开发者 |
| kernel 二进制 | 真正下发到芯片执行的那份 |
⭐ 这条对排查很有用："找不到算子" 具体就是 —— 框架按名字去查 kernel 二进制，没查到（或查到的不匹配当前芯片）。
三、每个东西干什么用（一句话）
| 东西 | 一句话功能 |
|---|---|
| Toolkit | CANN 的主包，装了它才算"装了 CANN" |
| ops 包（Kernels） | 算子库本体 —— 大模型跑的每个算子都从这里找 |
| NNAL / ATB / SiP | 加速库，各有各的 set_env.sh，要单独 source |
set_env.sh |
环境变量的"总开关" —— 不 source，CANN 装了也用不了 |
ASCEND_OPP_PATH |
算子库根目录 —— "找不到算子"排查的第一站 |
ASCEND_HOME_PATH |
CANN 装在哪的答案（官方明说同 ASCEND_TOOLKIT_HOME） |
LD_LIBRARY_PATH / PYTHONPATH |
动态库 / Python 包找不到时的第一站 |
四、怎么装（安装方法）
4.1 ⭐ 先选装法：官方有 7 种（InstallType）
| # | 官方 InstallType |
中文 | 装什么 |
|---|---|---|---|
| 1 | netyum |
在线安装（Yum） | 驱动、Toolkit、ops |
| 2 | netapt |
在线安装（Apt-get） | 驱动、Toolkit、ops |
| 3 | netconda |
在线安装（Conda） | Toolkit、ops（不含驱动） |
| 4 | netpip |
在线安装（Pip） | 见官方页面 |
| 5 | local |
离线安装（独立包） | 驱动与 Toolkit 分开的包 |
| 6 | localpack |
离线安装（合一包） | 驱动与 Toolkit 合并的包 |
| 7 | netdocker |
在线安装（Docker 镜像） | 容器镜像形态 |
⭐ 按操作系统选：
| 操作系统 | 支持的 InstallType |
|---|---|
| openEuler / Kylin / UOS / BCLinux / CTyunOS / CULinux / AliOS … | netyum、netconda、netpip、local、localpack、netdocker |
| Ubuntu / veLinux / Debian … | netapt、netconda、netpip、local、localpack、netdocker |
⚠️ 两个要点： ① Conda 装法不含驱动 —— 别指望它把驱动也装上； ②
--force是"跳过检测"，不是"更强的安装" —— 它不会解决不兼容。
4.2 ⭐⭐ 最容易装错的一步：ops 包按产品型号分发
包名里带着"这是给谁的"：
| 包名前缀 | 对应产品 |
|---|---|
950 |
Ascend 950 系列 |
A3 |
Atlas A3 系列 |
910b |
Atlas A2 系列 ⚠️ |
⚠️ 那个坑：官方表里 Atlas A2 系列 对应的 ops 包名是 910b ——
如果你凭直觉"Atlas A2 应该找 A2 的包"，就会下错。
正确做法：照官方表的行来选，不要靠包名猜。
而且每个型号下还分两种架构：aarch（aarch64）与 x86_64。
⭐ 这直接解释了"找不到算子"的头号原因：
给 A2 的机器装了
950-ops或A3-ops，算子库里的 kernel 二进制和目标芯片对不上 → 表现成"找不到算子"。
4.3 安装命令（三条）
命令 chmod u+x <安装包>.run
含义：给安装包加"属主可执行"权限 拆解：
chmod（改权限）＋u（属主）＋+x（加执行） 用法：chmod u+x Ascend-cann-toolkit_<版本>_linux-aarch64.run期望：无输出（成功即沉默） 不过会怎样：不加就报Permission denied
命令 ./<安装包>.run --check
含义：只校验不安装 —— 查包完整性与一致性 用法：
./Ascend-cann-toolkit_<版本>_linux-aarch64.run --check期望：Verifying archive integrity... 100% SHA256 checksums are OK. All good.不过会怎样：校验不过 → 重新获取安装包，不要硬装
命令 ./<安装包>.run --install
含义：执行安装 拆解：
--install（安装）／可选--install-path=<路径>（须以/或~开头） 跳许可交互：在命令前加echo y |用法：./Ascend-cann-toolkit_<版本>_linux-aarch64.run --install期望：出现Do you accept the LICENSE...? [Y/N]→ 输Y→ 最后提示安装成功 不过会怎样：输入非Y→ 停止安装并退出 ⚠️ 官方明确：不建议安装在/tmp路径下
4.4 装完加载环境（不 source 等于没装）
命令 source /usr/local/Ascend/cann/set_env.sh
含义：加载 CANN 环境变量（在当前终端生效） 拆解：
source在当前 shell 执行，不新开进程 —— 所以变量留得住 用法：root 与非 root 路径不同（见下表） 期望：无输出；随后echo $ASCEND_HOME_PATH有值 不过会怎样：报No such file or directory→ 路径不对，用find找
三套需要 source 的脚本（官方口径）：
| 包 | root | 非 root |
|---|---|---|
| CANN / Toolkit | /usr/local/Ascend/cann/set_env.sh |
${HOME}/Ascend/cann/set_env.sh |
| NNAL 的 ATB | /usr/local/Ascend/nnal/atb/set_env.sh |
${HOME}/Ascend/nnal/atb/set_env.sh |
| NNAL 的 SiP | /usr/local/Ascend/nnal/asdsip/set_env.sh |
${HOME}/Ascend/nnal/asdsip/set_env.sh |
从两组路径能读出三件事：
1. 根目录不同：root 用系统级 /usr/local/Ascend/，非 root 用 ${HOME}/Ascend/；
2. 子目录结构一致 —— 认识一个，另一个就认识了；
3. cann 这个目录名是个入口 —— 官方在讲升级时提到
「CANN 升级时，默认会升级安装目录下 cann 软链接指向的版本」。
⚠️ 环境变量是"进程级"的：新开一个终端就没了 → 要持久化就写进 ~/.bashrc，并 source ~/.bashrc。
4.5 装进容器（如果这条路上用容器）
⭐ 根本差别：驱动在宿主机，不在容器里
| 裸机 | 容器 | |
|---|---|---|
| 驱动 / 固件 | 装在这台机器上 | 在宿主机上（容器里不装） |
| CANN | 装在这台机器上 | 容器里装（或镜像里已带） |
| 卡 | 本来就是这台机器的 | 靠 --device 从宿主机"交"进来 |
官方原文印证（MindIE 镜像安装的前提条件）：
宿主机已经安装过 NPU 驱动和固件。
→ 容器方案默认驱动在宿主机上备好。
容器要"看见"卡，必须挂这几个设备节点：
| 设备路径 | 作用 |
|---|---|
/dev/davinci0、/dev/davinci1 … |
每一张 AI 处理器（编号从 0 开始） |
/dev/davinci_manager |
设备管理接口 |
/dev/hisi_hdc |
主机与设备间的通信通道 |
/dev/devmm_svm |
内存管理相关 |
⭐ 两个容器专属要点：
1. --device 的权限必须是 rwm，不能用 rw（官方有具体说明）；
2. 容器里要有 npu-smi，得把宿主机那份挂进来 ——
因为 npu-smi 是随驱动装在宿主机的 /usr/local/sbin/ 和 /usr/local/bin/，
容器里没有驱动，自然也没有 npu-smi。
五、怎么验证装对了（验证方法）
三步确认
命令 echo $ASCEND_HOME_PATH
含义：这一层的头号判据 —— CANN 环境是否生效 用法：
echo "ASCEND_HOME_PATH=[$ASCEND_HOME_PATH]"期望：打印出安装路径（如/usr/local/Ascend/cann） 不过会怎样：打印空行 → 环境变量没加载（回 4.4 去 source） ⭐ 记法：装了 CANN ≠ CANN 能用 —— 变量没加载等于没用
命令 echo $ASCEND_OPP_PATH
含义：看算子库根目录指向哪里 期望：打印算子库路径 不过会怎样：为空 → "找不到算子"的高概率原因
命令 npu-smi info -t board -i <设备号>
含义：查驱动/固件版本，用来和 CANN 版本对配套 期望：
Software Version（驱动）与Firmware Version（固件）有值 不过会怎样：字段为空 → 回 A 层
⭐ 验收清单（四条全过 = 这一层完工）
| # | 判据 | 命令 | 通过标准 |
|---|---|---|---|
| ① | CANN 装了 | ls <安装根>/cann |
目录存在 |
| ② | 环境变量生效 | echo $ASCEND_HOME_PATH |
有值 |
| ③ | 算子库就位 | echo $ASCEND_OPP_PATH |
有值 |
| ④ | 版本配套 | npu-smi info -t board -i <ID> 对比官方《版本说明》 |
驱动 / 固件 / CANN 三者配套 |
⭐ 第 ④ 条的口径（官方原话）：
「驱动、固件和 CANN 软件配套场景下，可单独升级 CANN 软件。」
读出来两件事： - 三者必须配套 —— 不是各自最新就最好； - 配套的前提下，可以只升 CANN，不必连驱动一起升。
去这里查配套：
| 要查什么 | 官方入口 |
|---|---|
| 版本配套关系 | 官方《版本说明》 |
| 硬件与操作系统兼容性 | 官方兼容性查询助手：https://www.hiascend.com/hardware/compatibility |
| 固件与驱动下载 | https://www.hiascend.com/hardware/firmware-drivers |
六、三个最容易踩的坑
| # | 坑 | 症状 | 怎么办 |
|---|---|---|---|
| 1 | ops 包装错型号 | "找不到算子" | 照官方表的行选包，别靠包名猜（A2 对应的是 910b） |
| 2 | 装完没 source | "import 失败 / 找不到库" —— 容易误判成"没装" | echo $ASCEND_HOME_PATH 为空 → 去 source |
| 3 | 容器里以为要装驱动 | 到处找不到驱动 / 装不上 | 驱动在宿主机，容器只要 --device 拿卡 |
⚠️ 还有一条"看起来像故障但不是"的：
容器里 /etc/Ascend/ascend_cann_install.info 看不到 —— 不代表 CANN 没装。
判据要用"命令能不能跑 / 变量有没有值"，不用文件存在性判。
版本升级（B3 的三条硬约束）
| 约束 | 说明 |
|---|---|
--upgrade 是单向的 |
只能升，降级要卸载重装 |
合一包不支持 --upgrade |
用合一包就只能卸装 |
升级默认升 cann 软链接指向的版本 |
想换版本，就是换这个软链接的指向 |
七、这一层和其他层的关系
↑ L2 框架（PyTorch + TorchNPU） ← 靠 L1 提供的算子库和接口
│
│ ★ 你在这一层 装：Toolkit + ops（+ NNAL）
│ 验：echo $ASCEND_HOME_PATH 有值
│
↓ L0 硬件与驱动（HDK） ← L1 依赖它；L0 不对，L1 装了也白装
| 关系 | 说明 |
|---|---|
| 它依赖谁 | L0 —— npu-smi info 有表才轮到 L1 |
| 谁依赖它 | L2 / L3 / L4 全部 |
| 上一层怎么验 | 一行验四层：python3 -c "import torch; import torch_npu; a=torch.randn(3,4).npu(); print(a+a)" |
附 · 命令速查（复制即用）
# 选装法（在线）
# Ubuntu/Debian 系 → netapt ；openEuler/麒麟等 → netyum
# 不想装驱动（容器里）→ netconda
# 装（以离线包为例）
chmod u+x <安装包>.run
./<安装包>.run --check # 校验
./<安装包>.run --install # 安装（不推荐装到 /tmp）
# 加载环境（root / 非 root 路径不同）
source /usr/local/Ascend/cann/set_env.sh # root
source ${HOME}/Ascend/cann/set_env.sh # 非 root
# 验
echo "ASCEND_HOME_PATH=[$ASCEND_HOME_PATH]" # 有值 = 生效
echo "ASCEND_OPP_PATH=[$ASCEND_OPP_PATH]" # 算子库根
ls /usr/local/Ascend/cann # 装在哪
npu-smi info -t board -i <设备号> # 驱动/固件版本
# 找 set_env.sh（路径不确定时）
find / -maxdepth 6 -name set_env.sh -path "*Ascend*" 2>/dev/null
附 · 本层的"包从哪下"
| 要下什么 | 地址 |
|---|---|
| CANN（Toolkit / Kernels） | https://www.hiascend.com/cann/download |
| 兼容性查询助手 | https://www.hiascend.com/hardware/compatibility |
| 版本配套关系 | 官方《版本说明》 |
| 包名规律 | Toolkit：Ascend-cann-toolkit_{版本}_linux-{架构}.runKernels/ops： Ascend-cann-kernels-{型号}_{版本}_linux-{架构}.run |
⚠️ 下之前先确认三件事：
1. 架构（uname -m）—— aarch 还是 x86_64，下错装不上
2. 产品型号 —— 决定 ops 包选哪个（950 / A3 / 910b 对应 Atlas A2）
3. 驱动版本 —— 先查驱动，再按配套表选 CANN（顺序不能反）
本层浓缩自：
昇腾部署课件_B1_CANN是什么/_B2_算子库与算子包/_B3_版本与多版本共存/_B4_七种安装方式/_B5_装进容器上一层：A 层 · L0 硬件与环境 下一层：C 层 · L2 框架