昇腾部署第 B3 课：版本对应关系与多版本共存—

编制：观澜｜日期：2026-10-05｜级别：T2 标准级 层级：B 层 · L1 基础软件（B 层第 3 课，前接 B2《算子库与算子包》）素材来源：昇腾官方文档 MCP 实时抓取（CANN 9.2.0-beta.2 官方文档）数据纪律：参数名、规则、路径、配置文件位置逐字出自官方文档；标注「归纳」的是便于记忆的整理，非官方口径。

第一段 · 章前定位

B1 给了一个结论：CANN 不能直接降级，官方规定"需卸载高版本后重新安装"。

B2 给了另一个结论：ops 包按产品型号分发，装错了就"找不到算子"。

这两条拼起来，引出这一课要解决的问题：

如果我要在一台机器上放着两个 CANN 版本、随时切换，怎么办？ 升级的时候，究竟升的是哪个目录？ 装错了怎么干净地退回去？

这一课的主角是一个很多人没注意过的东西：

安装目录下的 cann 软链接。

官方在升级文档里轻描淡写地提了一句「CANN 升级时，默认会升级安装目录下 'cann' 软链接指向的版本」—— 这一句话是理解昇腾版本管理的钥匙：它说明版本不是靠路径记住的，是靠一个软链接指向的。

这一课也接上 A3 的结论：A3 讲 hccn_tool 时强调过"软链接断"是一种独立的故障类型。现在你知道为什么软链接在昇腾环境里这么重要——它是版本切换的机制本身。

第二段 · 学习目标

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

三方版本配套关系（驱动 / 固件 / CANN）要在哪儿查
cann 软链接是什么，为什么升级"升级的是它指向的版本"
升级要满足什么条件，--upgrade 有哪些限制
为什么不能直接降级，正确的回退姿势是什么
冷补丁是什么，和整体升级有什么区别

第三段 · 三方版本配套关系：先搞清"对不对得上"

官方规则（原文）

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

两句话，两个结论：

官方这半句	说明什么
"驱动、固件和 CANN 软件配套场景下"	三者必须配套——不是各自最新就最好
"可单独升级 CANN 软件"	配套的前提下，可以只升 CANN，不必连驱动一起升

去哪儿查（三个官方入口）

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

实操建议（归纳）：动手前先把这三件事查完—— ① 我这台机器是什么型号（A2 教过 npu-smi info -t product）； ② 这个型号支持这个操作系统版本吗（兼容性助手）； ③ 我要装的 CANN 版本，跟当前驱动/固件配套吗（版本说明）。 查完再动手，比装到一半报错再回头查省时间。

⚠️ 一条容易被忽视的官方规则

官方原文：「升级后，请确保所有软件满足版本配套关系。」

注意"所有软件"——不只是 CANN 本身。 所以升级 CANN 之后要回头验证一遍：驱动、固件、CANN 三者还配套吗。

第四段 · `cann` 软链接：版本管理的钥匙（本课核心）

先看安装目录长什么样

从官方文档里反复出现的路径，可以还原出这样一个结构（归纳）：

<安装根>/                        root: /usr/local/Ascend
  │                              非root: ${HOME}/Ascend
  ├── cann/                      ← 软链接：指向当前生效的版本
  │     └── set_env.sh
  ├── nnal/atb/                  ← NNAL 的 ATB 加速库（B1 讲过）
  ├── nnal/asdsip/               ← NNAL 的 SiP 加速库
  └── <某个具体版本目录>/          ← 实际安装的版本（真身）

官方原话（升级文档）

CANN 升级时，默认会升级安装目录下，"cann" 软链接指向的版本。

这一句里藏着三个关键信息：

① cann 是个软链接，不是真目录。 A3 讲过怎么验证软链接：ls -l 看箭头指向。

② 版本"当前生效的是谁"，由这个软链接决定。

③ 升级不是"再装一个"，而是"升掉现在生效的那个"。 所以只有一份在生效——这是"单版本生效"模型，不是"多版本共存"模型（见第六段）。

这对你的三个实际影响

场景	会发生什么	你该做什么
你想换一个版本	手工改软链接指向，或按官方方式升级	先 `ls -l` 看清现在指向谁
你想升到新版本	官方升级会升掉 `cann` 指向的那个	确认这个"当前版本"就是你想升的
你以为装了两个版本、可以随便切	不一定——见第六段	先确认实际有几份安装

⚠️ 数据纪律提示：官方文档明确提到 cann 软链接这一机制，但未给出"手工修改软链接切换版本"的官方操作步骤。所以本课不教具体命令，只讲机制。 要切换版本，请走官方的安装/升级/卸载流程。

怎么确认现在生效的是哪个版本（官方给的验证方式）

cd <安装根>/cann/<arch>-linux
cat ascend_toolkit_install.info

这是官方原文给的装机验证方式：「执行如下命令查询 CANN 版本信息， 查询结果与安装软件包的版本一致时，则验证安装成功」—— 看输出里的 version 字段。路径里 <arch> 是 CPU 架构（aarch64 或 x86_64），<安装根> 按实际情况替换。

第五段 · 升级：`--upgrade` 能做什么、不能做什么

官方规则（原文）

--upgrade：升级已安装的软件，支持在低版本升级至高版本场景下使用。 如果需要从高版本回退至低版本，需卸载高版本后重新安装所需版本。 驱动&Toolkit 合一包不支持使用该参数。

拆成三条硬规则

规则	官方原文	意味着
方向单向	"支持在低版本升级至高版本场景下使用"	`--upgrade` 只能往上走
降级无路	"从高版本回退至低版本，需卸载高版本后重新安装"	想降级 ≠ 用 `--upgrade`，要先卸载
合一包例外	"驱动&Toolkit 合一包不支持该参数"	如果你装的是合一包，`--upgrade` 不可用

`--upgrade` 必须搭配的两个参数（官方）

① 升级时必须指定 --install-path

官方原文（--install-path）：指定操作路径，需配合安装 --install、升级 --upgrade 和卸载 --uninstall 参数使用。 ……若不指定，安装时工具将自动检测 Ascend 环境变量确定安装位置，升级时必须指定。

归纳：安装可以不指定路径（走默认），但升级必须指定—— 因为升级要明确"升的是哪一份"。

② 升级特性：--feature-list=<feature>

官方原文：--feature-list=<feature> 仅软件包 Toolkit 支持使用该参数。指定升级特性。仅支持升级使用，参数仅支持输入 Acclibs（独立升级算子包）。

这条很有用（归纳）： Acclibs = 独立升级算子包 —— 也就是说，可以不整包升，只升算子库那一块。（这条与 B2 直接呼应：算子库是可以单独升级的组件。）

升级时要小心的两个参数

参数	官方说明	风险
`--force`	强制安装、升级命令。当安装、升级检测不通过导致失败时，会提示使用该参数跳过安装检测	跳过检测 = 可能跳过配套性检查 → 与第三段的"必须配套"相冲突
`--quiet` / `-q`	静默安装或升级，跳过交互式信息；使用此参数安装或升级时，将默认同意 EULA	看不到提示信息；自动同意许可协议

归纳（一条实用纪律）： --force 不是"更厉害的安装"，它是"跳过检查"。用之前先想清楚：检查报的那一项，真的可以忽略吗？ 配套性检查尤其不能跳过。

第六段 · 回退与卸载：为什么"不能直接降级"

官方规定（原文，出现于多处文档）

如果需要从高版本回退至低版本，需卸载高版本后重新安装所需版本。

为什么这么设计（归纳，帮理解而非官方口径）：

因为它第四段讲的模型是"单版本生效 + 软链接指向"。 升级是"把当前生效的那份升掉"——升级结束后，旧版本的文件已经被新的覆盖了，没有留一份"旧版本"让你切回去。

所以"降级"在机制上就不存在：不是不允许，是没有可回退的对象。

正确的回退姿势（官方口径）

① 卸载当前（高）版本
② 重新安装目标（低）版本
③ 重新配置环境变量（source set_env.sh）
④ 验证版本（cat ascend_toolkit_install.info）

卸载相关：官方给出的两条路径

run 包（通过 --uninstall 参数）

官方原文（--install-path）：指定操作路径，需配合安装 --install、升级 --upgrade 和卸载 --uninstall 参数使用。

rpm 包（用系统包管理器）

官方原文：若您获取的是 xxx.rpm 的 CANN 软件包，卸载命令参考如下（命令中的 <arch> 请根据实际架构替换）： rpm 方式： - root 用户：rpm -e Ascend-cann-toolkit.<arch> - 非 root 用户（请自行获取所需的 sudo 权限）：（官方文档同节给出对应命令）

升级用 --force 跳过检测（官方原文）：

若安装、升级检测不通过……则可使用 --force 强制升级：rpm -Uvh xxx.rpm --force

⚠️ 关于"多版本共存"：本课必须说清的一件事

用户常有的期待：装两份 CANN，随时切换。

官方文档给出的模型是：一份在生效（cann 软链接指向的那份），升级时"默认升级 cann 软链接指向的版本"。

所以（归纳）： - 同一安装根目录下，实际生效的是一份。 - 想同时留两份，需要用不同的安装根目录（例如 root 装一份在 /usr/local/Ascend，另一份装到别的 --install-path）——但官方文档未给出"多份安装如何切换"的操作指引，本课不做推测。

⚠️ 数据纪律提示：本课不教"手工改软链接切换版本"，因为那不在官方文档口径内。如果确实需要多版本共存与切换，请以官方文档或官方技术支持为准。

第七段 · 冷补丁：另一种升级方式

官方提出了一个和"整包升级"不同的概念：

CANN 软件包支持冷补丁升级，即支持独立升级单个或多个库文件的功能。因此发布 CANN 冷补丁包。

官方给出的约束（原文，逐条）

冷补丁仅能支持对应的基线版本或相关的冷补丁版本进行升级。

基于同一基线版本的冷补丁，需保证后续安装的冷补丁版本大于之前安装的冷补丁版本。

仅支持回退一个冷补丁版本。

冷补丁包提供 run 和 rpm 格式的软件包。

安装、回退过程禁止进行其他维护操作动作。

逐条翻译（归纳）

官方约束	意思
"仅能支持对应的基线版本"	冷补丁是给特定基线版本用的，不能乱配
"后续冷补丁版本大于之前的"	冷补丁只能往上加，不能往回装
"仅支持回退一个冷补丁版本"	冷补丁比整包多一条路：可以退一步
"提供 run 和 rpm 格式"	两种格式都有
"禁止进行其他维护操作"	装/退冷补丁期间别同时干别的维护操作

冷补丁 vs 整包升级（归纳对比）

	整包 `--upgrade`	冷补丁
改什么	整个 CANN	单个或多个库文件
方向	只能升级（降级要卸载重装）	升级；可回退一个版本
适用	版本跃迁	小范围修复（比如只换算子库那部分）
期间能别的操作吗	——	官方明确禁止

理解这个区别的意义（归纳）： "只改一小块"和"整体换版本"是两种不同的变更，二者的风险、回退能力、注意事项都不同。 遇到官方发冷补丁的场景，不要按整包升级的思路去处理。

第八段 · 出问题怎么查

现象	先查什么
不确定现在生效的是哪个版本	`cat ascend_toolkit_install.info` 看 `version` 字段（第四段）
想降级，找不到命令	官方规定没有直接降级：卸高版本 → 装低版本
`--upgrade` 报错说没指定路径	官方要求升级必须指定 `--install-path`
装的是"驱动&Toolkit 合一包"，`--upgrade` 不认	官方明确：合一包不支持 `--upgrade`
升级后业务反而异常	回头核对配套关系（官方："升级后请确保所有软件满足版本配套关系"）
安装/升级"检测不通过"	先想清楚检测报的是什么——`--force` 是跳过检查，不是修复问题
想只升级算子库那一块	`--feature-list=Acclibs`（仅 Toolkit 支持，仅升级可用）
冷补丁装/退的时候	官方：期间禁止进行其他维护操作
不确定配置文件在哪	全局配置文件 `ascend_cann_install.info`：root 在 `/etc/Ascend`，非 root 在 `${HOME}/Ascend`

⭐ 一个最省时间的判断法

昇腾的版本问题，先分清是"装错了"还是"配错了"。

装错了 → ascend_toolkit_install.info 里的 version 和别人/文档对不上 → 回安装流程
配错了 → 版本对，但 echo $ASCEND_HOME_PATH 指到了别的地方 / 为空 → 回环境变量（B1）
配套不对 → 版本本身没错，但三者不配套 → 查《版本说明》

这三类的处置完全不同。别在"版本问题"这个大帽子下面乱试。

一个很实用的官方细节：`--install-path` 会改全局配置

官方原文：当环境上已存在全局配置文件 ascend_cann_install.info 时， 该参数指定的路径会自动重置该文件中的安装路径，并在原路径下创建时间戳文件夹，备份旧配置文件。

归纳两句： 1. 安装路径这个信息，是记在一个全局配置文件里的——不是靠环境变量"猜"的。 2. 官方会自动备份旧配置（带时间戳）——所以改了路径是有痕迹可查的，将来要回退，找那些时间戳文件夹。

第九段 · 小结与下一课

三句话带走

版本管理的钥匙是 cann 软链接——"当前生效哪个版本"由它指向决定；升级升的是它指向的那份（官方原文）。
--upgrade 只能往上走；降级没有捷径——卸载高版本、重装低版本；而且升级必须指定 --install-path（合一包不支持 --upgrade）。
--force 是"跳过检测"不是"更强的安装"；配套性检查不能跳—— 官方明确要求"升级后确保所有软件满足版本配套关系"。

本课在体系里的位置

─── L0 硬件与环境（A 层，已完成）───
A0 一张地图 / A1 驱动与固件 / A2 产品线与形态 / A3 HDK 到底指什么
─── L1 基础软件（B 层）───
B1 CANN 是什么、装在哪、环境变量怎么配        ✅
B2 算子库与算子包：为什么会"找不到算子"        ✅
B3 版本对应关系与多版本共存                    ★ 本课
B4（拟）七种安装方式与 run 包常用参数
B5（拟）CANN 装进容器

本课留下的"钩子"

钩子	在哪一课填
`--devel` / `--full` / `--check` 这些参数具体怎么用	B4
无驱动场景下怎么装（`--full` 的用途）	B4
容器里怎么装、能不能复用宿主机的 CANN	B5
冷补丁与本课的整体关系（版本跃迁 vs 小范围修复）	已在本课讲清

课后自测（3 题）

官方文档说"CANN 升级时默认会升级 cann 软链接指向的版本"。这句话说明了版本管理的什么机制？
你想把 CANN 从 9.2 退回到 9.0。官方允许直接用 --upgrade 吗？正确做法是什么？
安装时提示"检测不通过"，同事说"加 --force 就行"。你该怎么判断要不要加？

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

内容	出处
「驱动、固件和 CANN 软件配套场景下可单独升级 CANN」「版本配套关系参见《版本说明》」	官方《升级前必读》 `zh/CANNCommunityEdition/920beta2/softwareinst/instg/instg_0028.html`
「从高版本回退至低版本需卸载高版本后重新安装」「升级默认升级 `cann` 软链接指向的版本」「升级后请确保所有软件满足版本配套关系」	同上
`--upgrade` 规则（仅低→高、合一包不支持）、`--feature-list`（仅 Toolkit、仅升级、仅支持 `Acclibs`）	官方《参数说明》 `zh/CANNCommunityEdition/920beta2/softwareinst/instg/instg_0043.html`
`--install-path` 的完整说明（配合参数、全局配置文件 `ascend_cann_install.info` 位置、时间戳备份、默认路径、目录权限）	同上
`--force` / `--quiet` 的说明与风险提示	同上
冷补丁的约束（基线版本、版本递增、仅回退一个、run/rpm、禁止其他维护操作）	官方《安装、回退和卸载 CANN 冷补丁包》 `zh/CANNCommunityEdition/920beta2/softwareinst/instg/instg_0056.html`
rpm 格式的升级与卸载命令	官方《安装、升级和卸载 CANN 软件包（适用于 rpm 格式）》 `zh/CANNCommunityEdition/920beta2/softwareinst/instg/instg_0058.html`
`ascend_toolkit_install.info` 验证方式	官方《安装 CANN》安装后检查一节
兼容性查询助手 / 固件与驱动下载入口	`https://www.hiascend.com/hardware/compatibility`、`https://www.hiascend.com/hardware/firmware-drivers`

⚠️ 数据纪律提示： ① 多版本共存与切换：官方文档给出的机制是"cann 软链接指向当前生效版本"，但未提供"手工切换多份安装"的官方步骤 → 本课不教具体命令、不做推测； ② 本课未给出具体的版本号配套矩阵（那是《版本说明》的内容，且随版本变化）； ③ 标注「归纳」的解读（"单版本生效模型""三类版本问题的区分"）非官方口径。

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

`ls -l <路径>`

见 A3《HDK 到底指什么》附录 B——A3 讲它用来判断"软链接断"，本课讲它用来"看当前生效的是哪个版本"（cann 是软链接）。

`cat <安装根>/cann/<arch>-linux/ascend_toolkit_install.info`

含义：查看 Toolkit 的安装信息（官方给出的装机验证方式）。
拆解：ascend_toolkit_install.info = Toolkit 安装信息文件；<arch> = aarch64 或 x86_64。
用法： bash # 非 root 用户（默认路径） cd ${HOME}/Ascend/cann/aarch64-linux && cat ascend_toolkit_install.info # root 用户 cd /usr/local/Ascend/cann/aarch64-linux && cat ascend_toolkit_install.info
期望结果：输出中有 version 字段。
官方口径：「查询结果与安装软件包的版本一致时，则验证安装成功」。
不用会怎样：无法回答"我现在装的是哪个版本"——这是版本类问题的第一个必答题。

`bash ./Ascend-cann-<包名>_<版本>_linux-<arch>.run --install [--install-path=<path>]`

含义：安装 CANN 软件包（run 格式）。
拆解：bash = 用 shell 执行；.run = 自解压安装包；--install = 安装动作；--install-path= = 指定安装路径（可选）。
用法：bash ./Ascend-cann-toolkit_9.2.0-beta.2_linux-aarch64.run --install
期望结果：安装过程输出各组件安装信息；不指定路径时装到默认路径。
官方补充：安装 Toolkit 前请确保安装目录可用空间大于 10GB。

`bash ./xxx.run --check`

含义：检查软件包的一致性和完整性（官方参数说明）。
用法：bash ./Ascend-cann-toolkit_9.2.0-beta.2_linux-aarch64.run --check
为什么值得用：装之前先验包——传输损坏、下载不全这两类问题，在这一步就能发现，不必等到装到一半失败。
不用会怎样：包有问题时，错误可能在安装中途才暴露，排查更麻烦。

`.run` 包的常用查询参数

参数	官方说明
`--help` / `-h`	查询帮助信息
`--info`	查询软件包构建信息
`--list`	查询软件包文件列表
`--check`	检查软件包的一致性和完整性
`--tar xvf`	对软件包执行 tar 命令（`--tar xvf` = 解压到当前目录）
`--noexec --extract=<path>`	只解压不安装（目录会自动创建）

实用场景（归纳）：想在装之前看看包里到底有什么 → 用 --list 或 --noexec --extract=./package 解开看，不用真装。

参数速查表（安装 / 升级 / 卸载）

参数	作用	关键限制
`--install`	安装	可带 `--install-path`
`--upgrade`	升级	仅低→高；合一包不支持；必须指定 `--install-path`
`--uninstall`	卸载	配合 `--install-path`
`--install-path=<path>`	指定安装路径	root 需 755、非 root 需 750 权限
`--feature-list=Acclibs`	独立升级算子包	仅 Toolkit；仅升级可用
`--full`	无驱动场景下全量安装	仅 Toolkit 支持
`--devel`	开发模式安装（只装开发环境所需）	仅驱动&Toolkit 合一包 / Toolkit / ops
`--install-for-all`	允许同组其他用户使用	会放宽目录权限，有安全风险
`--force`	跳过安装/升级检测	与"必须配套"相冲突，慎用
`--quiet` / `-q`	静默安装/升级	默认同意 EULA
`--torch_atb`	安装 Python 库时使用	仅 nnal

附：B1 / B2 / B3 的分工（避免重复）

问题	在哪一课
CANN 是什么、有哪些包、装在哪、环境变量怎么配	B1
算子库装了什么、为什么按型号分、"找不到算子"怎么查	B2
版本怎么配套、`cann` 软链接是什么、升级/回退规则、冷补丁	本课（B3）
安装参数逐个怎么用、怎么选装法	B4
容器场景	B5

昇腾部署第 B3 课：版本对应关系与多版本共存——cann 软链接那条线

第一段 · 章前定位

第二段 · 学习目标

第三段 · 三方版本配套关系：先搞清"对不对得上"

官方规则（原文）

去哪儿查（三个官方入口）

⚠️ 一条容易被忽视的官方规则

第四段 · cann 软链接：版本管理的钥匙（本课核心）

先看安装目录长什么样

官方原话（升级文档）

这对你的三个实际影响

怎么确认现在生效的是哪个版本（官方给的验证方式）

第五段 · 升级：--upgrade 能做什么、不能做什么

官方规则（原文）

拆成三条硬规则

--upgrade 必须搭配的两个参数（官方）

升级时要小心的两个参数

第六段 · 回退与卸载：为什么"不能直接降级"

官方规定（原文，出现于多处文档）

正确的回退姿势（官方口径）

卸载相关：官方给出的两条路径

⚠️ 关于"多版本共存"：本课必须说清的一件事

第七段 · 冷补丁：另一种升级方式

官方给出的约束（原文，逐条）

逐条翻译（归纳）

冷补丁 vs 整包升级（归纳对比）

第八段 · 出问题怎么查

⭐ 一个最省时间的判断法

一个很实用的官方细节：--install-path 会改全局配置

第九段 · 小结与下一课

三句话带走

本课在体系里的位置

本课留下的"钩子"

课后自测（3 题）

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

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

ls -l <路径>

cat <安装根>/cann/<arch>-linux/ascend_toolkit_install.info

bash ./Ascend-cann-<包名>_<版本>_linux-<arch>.run --install [--install-path=<path>]

bash ./xxx.run --check

.run 包的常用查询参数

参数速查表（安装 / 升级 / 卸载）

附：B1 / B2 / B3 的分工（避免重复）

第四段 · `cann` 软链接：版本管理的钥匙（本课核心）

第五段 · 升级：`--upgrade` 能做什么、不能做什么

`--upgrade` 必须搭配的两个参数（官方）

一个很实用的官方细节：`--install-path` 会改全局配置

`ls -l <路径>`

`cat <安装根>/cann/<arch>-linux/ascend_toolkit_install.info`

`bash ./Ascend-cann-<包名>_<版本>_linux-<arch>.run --install [--install-path=<path>]`

`bash ./xxx.run --check`

`.run` 包的常用查询参数