昇腾部署第 B1 课：CANN 是什么、装在哪、环境变量怎么配

编制：观澜｜日期：2026-10-05｜级别：T2 标准级 层级：B 层 · L1 基础软件（B 层第 1 课；L0 已在 A0–A3 讲完）素材来源：昇腾官方文档 MCP 实时抓取（CANN 9.2.0-beta.2 官方文档）数据纪律：定义、路径、环境变量名与释义逐字出自官方文档；标注「归纳」的是便于记忆的整理，非官方口径。

第一段 · 章前定位

A 层（A0→A3）走完了 L0 硬件与环境：有哪几层 → 卡怎么被认出来 → 卡是哪一代 → HDK 这一片包含什么。

从这一课开始，进入 L1 基础软件层。

这一层的核心只有一个东西：CANN。

A0 那张地图里，CANN 是判据 ② 的主角——「CANN 装好了、环境变量配上了吗」。 但当时没讲 CANN 到底是什么、装在哪、环境变量为什么非配不可。这一课补上。

为什么这一课重要：A0 的那条铁律是「下面的不对，上面的全废」。 CANN 正好卡在中间——它在 L0 之上、L2 之下。CANN 没配对，上面的框架、服务全都起不来，而报错信息往往指向"上面"（比如"找不到算子"），让人查错方向。

第二段 · 学习目标

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

CANN 到底是什么——它向上、向下各接什么（官方定义）
CANN 里有哪些包，各干什么
装在哪——root 与非 root 安装路径为什么不一样
set_env.sh 干什么用的，为什么要 source 它，为什么"进程结束就失效"
版本对应关系去哪儿查（CANN 与驱动/固件）

第三段 · CANN 到底是什么（官方定义）

官方原文：

异构计算架构 CANN（Compute Architecture for Neural Networks）是昇腾针对 AI 场景推出的 异构计算架构，向上支持多种 AI 框架，包括 MindSpore、PyTorch、TensorFlow 等，向下服务 AI 处理器与编程，发挥承上启下的关键作用，是提升昇腾 AI 处理器计算效率的关键平台。同时针对多样化应用场景，提供多层次编程接口，支持用户快速构建基于昇腾平台的 AI 应用和业务。

拆开看三个要点

① 全称是 Compute Architecture for Neural Networks —— 注意 Architecture（架构），不是"库"、不是"驱动"。它是一层结构，不是单个程序。

② 它的位置就是"承上启下"：

        MindSpore / PyTorch / TensorFlow      ← 向上（AI 框架）
                     ↑
                    CANN                     ← 本课（L1）
                     ↓
              AI 处理器与编程                 ← 向下（L0 硬件）

③ 它不只服务"跑模型"，还服务"写程序" —— 官方说它"向下服务 AI 处理器与编程""提供多层次编程接口"。 所以 CANN 里既有"给框架用的东西"，也有"给开发者写算子用的东西"——这就是第四段要讲的多包结构。

一句话记住：CANN 是昇腾的"中间层"——上面接框架，下面接芯片，中间还提供写程序的接口。

第四段 · CANN 里有哪些包（为什么它不是"一个软件"）

从官方文档的安装与环境变量章节可以看出，CANN 不是一个包，而是一组包。按官方文档的分类，至少包含：

包	官方文档中的名称	干什么
Toolkit	开发套件包（Toolkit）	主包：编译、执行、算子库路径都在它名下
Kernels / ops	算子包	算子库本体（`ASCEND_OPP_PATH` 指向它的根目录）
NNAL	神经网络加速库	一组加速库，其中包含
↳ ATB	ATB 加速库	一个加速库（有独立的 `set_env.sh` 与一批专属环境变量）
↳ SiP	SiP 加速库	另一个加速库（同样有独立 `set_env.sh`）

⚠️ 口径说明：上表的结构出自官方安装与环境变量文档的实际分组（Toolkit 一套变量、NNAL 的 ATB/SiP 各自一套变量）。 各版本包的确切拆分以《版本说明》和下载页为准——本课不臆测包的数量与命名。

这解释了一个常见困惑：为什么文档里一会儿说"装 CANN"、一会儿说"装 Toolkit"、一会儿又说"装 ops 包"？

因为"CANN"是这一组东西的总名。 就像 A3 里说的 HDK ——先有总名，再拆具体包。

第五段 · CANN 装在哪（root 与非 root 不一样）

这是本课最容易踩的地方：CANN 的安装路径取决于你用什么用户装的。

root 用户安装

# Toolkit 包
/usr/local/Ascend/cann/set_env.sh
# NNAL 包 ATB 加速库
/usr/local/Ascend/nnal/atb/set_env.sh
# NNAL 包 SiP 加速库
/usr/local/Ascend/nnal/asdsip/set_env.sh

非 root 用户安装

# Toolkit
${HOME}/Ascend/cann/set_env.sh
# NNAL 包 ATB 加速库
${HOME}/Ascend/nnal/atb/set_env.sh
# NNAL 包 SiP 加速库
${HOME}/Ascend/nnal/asdsip/set_env.sh

从这两组路径能读出三件事（归纳）

根目录不同：root 用系统级的 /usr/local/Ascend/；非 root 用用户家目录下的 ${HOME}/Ascend/。
子目录结构一致：都是 <根>/cann/、<根>/nnal/atb/、<根>/nnal/asdsip/ —— 认识一个，另一个就认识了。
"cann" 这个目录名是个入口：官方在讲升级时提到「CANN 升级时，默认会升级安装目录下 'cann' 软链接指向的版本」—— 说明 cann 很可能是个软链接，指向当前生效的那个版本目录。 这是一条实用的判断线索：版本切换不一定要改路径，可能是改这个软链接的指向。

⚠️ 这一条直接决定你该翻哪份文档：你的环境是 root 装还是普通用户装，环境变量脚本路径完全不同。照着别人的教程 source /usr/local/Ascend/cann/set_env.sh 却报"文件不存在"，先别怀疑装错了——先确认是不是非 root 装的。

第六段 · 环境变量：为什么非配不可、怎么配（本课的核心）

官方对这件事的说明（原文）

CANN 软件安装完成后，默认会自动配置程序编译、执行所依赖的基础环境变量，但用户进程结束后相关环境变量自动失效，您也可以通过如下环境变量脚本一键式配置。

这句话里有两个关键信息，都很实用：

信息	意味着什么
安装后默认已自动配置	不是"不配就不能用"——新开的 shell 里通常已经能用
进程结束后自动失效	你在一个 shell 里配好，换个窗口、重登录就没了

所以"环境变量没配"这个现象，典型表现是：

在 A 窗口能跑的程序，到 B 窗口报"找不到命令 / 找不到库"。

怎么配：`source` 三个脚本

source /usr/local/Ascend/cann/set_env.sh          # Toolkit（root 安装）
source /usr/local/Ascend/nnal/atb/set_env.sh      # ATB（若装了 NNAL）
source /usr/local/Ascend/nnal/asdsip/set_env.sh   # SiP（若装了 NNAL）

想永久生效：写进 `~/.bashrc`（官方给的步骤）

以运行用户在任意目录下执行 vi ~/.bashrc 命令，打开 .bashrc 文件，在文件最后一行后面添加上述内容。

执行 :wq! 命令保存文件并退出。

执行 source ~/.bashrc 命令使其立即生效。

Toolkit 会配哪些变量（官方清单，逐条）

环境变量	官方释义
`PATH`	可执行文件查找路径
`LD_LIBRARY_PATH`	动态库的查找路径
`PYTHONPATH`	Python 搜索路径
`ASCEND_OPP_PATH`	算子库根目录
`ASCEND_AICPU_PATH`	AI CPU 组件的安装路径
`TOOLCHAIN_HOME`	工具链安装路径
`ASCEND_HOME_PATH`	同 `ASCEND_TOOLKIT_HOME`，代表 Toolkit 软件安装后文件存储路径
`ASCEND_TOOLKIT_HOME`	Toolkit 软件包安装后文件存储路径
`CMAKE_PREFIX_PATH`	CMAKE 的内置环境变量，用于指定 CMake 库配置文件路径，供 `find_package()` 等命令检索

其中三个最该记住（归纳，便于排障）：

ASCEND_OPP_PATH —— 算子库根目录。 "找不到算子""算子版本不对"这类报错，第一站就是查它。
ASCEND_HOME_PATH / ASCEND_TOOLKIT_HOME —— 这两个是同一个意思（官方明说 ASCEND_HOME_PATH 同 ASCEND_TOOLKIT_HOME）。 "CANN 装在哪"的答案，就是这两个变量的值。
LD_LIBRARY_PATH / PYTHONPATH —— 动态库与 Python 包找不到时的第一站。

NNAL 的 ATB 还会配一批（举几个有用的）

官方在同一页列出了 ATB 的完整变量清单。除了 ATB_HOME_PATH（ATB 安装路径）、 LD_LIBRARY_PATH、PATH 这三条基础项，其余大多是调优与排障开关。挑三条实际会用到的：

变量	官方释义（摘要）
`ATB_STREAM_SYNC_EVERY_KERNEL_ENABLE`	用于问题定位，确定报错所在的 kernel；配为 1 时每个 Kernel 的 Execute 结束时做流同步
`ATB_COMPARE_TILING_EVERY_KERNEL`	每个 Kernel 运行后，比较运行前后的 NPU 上 tiling 内容是否变化，一般用于检查是否发生 tiling 内存踩踏
`LCCL_DETERMINISTIC`	LCCL 确定性 AllReduce（保序加）是否开启；开启后在 rankSize ≤ 8 时生效，会影响部分通信算子性能与累加序

这一段的用法：不要背。知道"ATB 有一批排障开关、官方文档里能查到"就够了—— 真遇到问题，按关键词去官方《环境变量参考》里查。

第七段 · 版本对应关系：去哪儿查（A3 留下的钩子）

A3 结尾留了这个问题：「CANN 与 HDK 的版本对应关系」。答案在这里。

官方口径（原文）

在驱动、固件和 CANN 软件配套场景下，可单独升级 CANN 软件，版本配套关系请参见《版本说明》。

这句话里有两个直接可用的结论：

三者要配套（驱动 / 固件 / CANN）——不是随便装的
配套的前提下可以只升 CANN——不必连驱动一起升

另外两条官方规则（升级文档原文）

规则	官方原文
升级前	升级后请确保所有软件满足版本配套关系
降级	如果需要从高版本回退至低版本，需卸载高版本后重新安装所需版本
升级目录	CANN 升级时，默认会升级安装目录下 `cann` 软链接指向的版本

⚠️ 第二条很关键：CANN 不能直接"降级"，要卸载再装。装错版本后想回退时，别去找"降级命令"——没有，先卸载。

查版本配套关系的三个官方入口

要查什么	官方入口
版本配套关系	官方《版本说明》文档
硬件与操作系统兼容性	官方兼容性查询助手：`https://www.hiascend.com/hardware/compatibility`
固件与驱动下载	`https://www.hiascend.com/hardware/firmware-drivers`（按系统与硬件产品型号选对应版本）

实操动作（和 A2 的结论一致）： 装之前先查配套，不要拿到一条安装命令就敲。 A2 说的是"查组件支持的产品列表"，这里说的是"查版本配套关系"—— 两件事都要查，查的是同一个官方文档体系。

第八段 · 出问题了怎么查

现象	先查什么
`source .../set_env.sh` 报文件不存在	① 是不是非 root 装的（路径换成 `${HOME}/Ascend/...`）② 确认实际安装根目录
换个终端窗口程序就跑不起来	环境变量只在当前 shell 有效（官方：进程结束自动失效）→ 写进 `~/.bashrc`
报找不到算子 / 算子版本不对	`ASCEND_OPP_PATH`（算子库根目录）指得对不对
报找不到动态库 / 找不到 Python 包	`LD_LIBRARY_PATH` / `PYTHONPATH`
不知道 CANN 到底装在哪	`ASCEND_HOME_PATH`（同 `ASCEND_TOOLKIT_HOME`）
装 CANN 报配套关系不满足	查官方《版本说明》；驱动/固件/CANN 三者要配套
想把 CANN 降级	官方规定：先卸载高版本，再装低版本（没有直接降级）
装了多个版本，不确定当前用哪个	看安装目录下 `cann` 软链接指向谁（官方升级文档提到这个机制）

⭐ 一个最省时间的判断法

「环境变量没配」的表现，几乎总是"同一个程序在不同终端行为不同"。

所以遇到"刚才还能跑，现在不行了"，第一件事不是查代码，是问自己：

我这会儿在哪个 shell？刚才那个 source 是在这个 shell 里执行的吗？

这一类问题的修法极简单（重新 source 一次），但不知道成因时会查很久。

第九段 · 小结与下一课

三句话带走

CANN 不是一个软件，是一层架构（Compute Architecture for Neural Networks）—— 上接框架、下接芯片，包含 Toolkit、算子包、NNAL（ATB / SiP）等多组包。
装在哪取决于用户：root 在 /usr/local/Ascend/，非 root 在 ${HOME}/Ascend/—— 子目录结构一致，照着别人的命令报"文件不存在"，先看这一条。
环境变量脚本 set_env.sh 要 source，而且只在当前 shell 有效；要长期生效就写进 ~/.bashrc。ASCEND_OPP_PATH（算子库根目录）是排障第一站。

本课在体系里的位置

─── L0 硬件与环境（A 层，已走完）───
A0 一张地图        ← 有哪几层，谁依赖谁
A1 驱动与固件      ← 卡怎么被系统认出来
A2 产品线与形态    ← 认出来的是张什么卡
A3 HDK 到底指什么  ← 驱动、固件、工具集的关系
─── L1 基础软件（B 层）───
B1 CANN 是什么、装在哪、环境变量怎么配   ★ 本课
B2（拟）算子库与算子包：为什么"找不到算子"
C1（拟）TorchNPU / MindSpore：框架层怎么接上来

本课留下的"钩子"

钩子	在哪一课填
`ASCEND_OPP_PATH` 里到底装了什么、"找不到算子"怎么查	B2
`torch.npu.is_available()` 返回 False 时怎么定位	C1
多用户 / 多版本共存时的环境隔离	F 场景实战

课后自测（3 题）

用一句话说清 CANN 在分层里的位置，以及它"承上启下"具体承什么、启什么。
你在机器上敲 source /usr/local/Ascend/cann/set_env.sh 报"没有那个文件"，可能的原因有几个？按可能性排序。
装错 CANN 版本了，想退回上一个版本。官方允许直接降级吗？该怎么操作？

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

内容	出处
CANN 的定义、向上/向下范围、"承上启下"	官方《CANN - 使用导读》 `https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920beta2/index/index.html`
安装后自动配置环境变量的说明、root/非 root 脚本路径、`~/.bashrc` 步骤	官方《安装后自动配置环境变量》（环境变量参考） `zh/CANNCommunityEdition/920beta2/maintenref/envvar/docs/zh/env-vars/install.md`
Toolkit 环境变量清单与逐条释义	同上
NNAL ATB 加速库环境变量清单与释义	同上
「驱动、固件和 CANN 软件配套」「可单独升级 CANN」「参见《版本说明》」	官方《升级前必读》 `zh/CANNCommunityEdition/920beta2/softwareinst/instg/instg_0028.html`
「降级需卸载高版本后重新安装」「升级默认升级 `cann` 软链接指向的版本」	同上
兼容性查询助手 / 固件与驱动下载入口	`https://www.hiascend.com/hardware/compatibility`、`https://www.hiascend.com/hardware/firmware-drivers`
当前 CANN 版本号（9.2.0-beta.2）	官方 CANN 文档站版本标识

⚠️ 数据纪律提示：本课未给出 CANN 各包的确切数量与命名细则—— 各版本的包拆分以官方《版本说明》和下载页为准。本课只讲结构关系与实操路径。

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

`source <脚本路径>`

含义：在当前 shell 进程内执行这个脚本。 source 是 shell 内置命令，执行后脚本里设的环境变量留在当前 shell 里。
拆解：source（在当前 shell 里执行）+ 脚本路径。
用法：source /usr/local/Ascend/cann/set_env.sh
为什么必须 source 而不能直接 ./set_env.sh：直接执行脚本会新开一个子进程，脚本里的 export 只影响那个子进程， 子进程退出，变量就没了——你在当前 shell 里什么都得不到。 source 是"不新开进程，就在这儿执行"。
期望结果：命令没有任何输出（除非有错），但环境变量已生效。
验证方式：执行后敲 echo $ASCEND_HOME_PATH，能打印出路径就说明生效了。
不用会怎样：子进程拿到变量、你这边没有 → 表现为"配了但没生效"。

`vi ~/.bashrc` / `source ~/.bashrc`

含义：编辑当前用户的 shell 启动脚本，让环境变量每次开 shell 都自动生效。
拆解：~/.bashrc = 家目录下的 bash 配置文件；vi = 文本编辑器。
用法（官方步骤）：vi ~/.bashrc → 在最后一行后面追加 source .../set_env.sh → :wq! 保存退出 → source ~/.bashrc 立即生效。
期望结果：新开的终端里 echo $ASCEND_HOME_PATH 直接有值，不需要再手工 source。
不用会怎样：每开一个新终端都要手工 source 一次；忘了就出现"刚才还能跑、现在不行"。

`echo $<变量名>`

含义：打印某个环境变量的当前值。
拆解：echo（输出）+ $变量名（取变量值）。
用法：echo $ASCEND_HOME_PATH、echo $ASCEND_OPP_PATH、echo $LD_LIBRARY_PATH
期望结果：有值 = 已配；输出空行 = 没配（注意：空行不是报错，别以为命令没执行）。
这是本课最该养成的习惯：说"环境变量配好了"之前，先 echo 一下。

参数速查表

命令 / 变量	用途
`source <set_env.sh>`	在当前 shell 生效环境变量
`vi ~/.bashrc` + `source ~/.bashrc`	让环境变量永久生效
`echo $ASCEND_HOME_PATH`	查 CANN/Toolkit 安装路径
`echo $ASCEND_OPP_PATH`	查算子库根目录（排"找不到算子"）
`echo $LD_LIBRARY_PATH`	查动态库搜索路径
`echo $PYTHONPATH`	查 Python 搜索路径

附：A 层与 B 层的分工（避免重复）

问题	在哪一课
有哪几层、每层判据是什么	A0
驱动、固件怎么装、怎么看版本	A1
卡是哪一代、什么形态	A2
HDK 包含什么、四个工具各干什么	A3
CANN 是什么、装在哪、环境变量怎么配、版本配套怎么查	本课（B1）
算子库细节、"找不到算子"怎么排	B2（拟）