昇腾平台环境搭建

昇腾平台环境搭建 — 从裸机到 CANN 跑通

适用: 运维 / 平台工程师 / 刚拿到昇腾服务器的开发者
内容参考: 华为昇腾官方文档 (hiascend.com/document) + 开发者学院课程 1970379749278314497

一、安装方案

1.1 推荐部署架构

1.2 软件栈分层

┌─────────────────────────────────────────┐
│  应用层: PyTorch / MindSpore / 推理引擎     │
├─────────────────────────────────────────┤
│  框架层: torch_npu / torch_npu.npu        │
├─────────────────────────────────────────┤
│  算子层: AscendC 自定义算子 / 标准算子库    │
├─────────────────────────────────────────┤
│  ★ CANN 异构计算架构 (本次安装重点)        │
│     ├─ Toolkit  (开发套件)                │
│     ├─ Kernels (算子包)                  │
│     └─ NNAL   (神经网络加速库, 可选)       │
├─────────────────────────────────────────┤
│  ★ 驱动固件 (NPU 必需)                    │
└─────────────────────────────────────────┘

1.3 安装前检查清单

项	最低要求	推荐
OS	Ubuntu 18.04+	Ubuntu 22.04 LTS (昇腾主力适配)
Kernel	5.4+	5.15+
内存	NPU 数量 × 16GB	NPU 数量 × 32GB
磁盘	200GB	500GB SSD
网络	千兆	万兆 (集群必备)
Python	3.7+	3.10
权限	root 或 sudo	root (简化操作)

---

二、安装 NPU 驱动

2.1 用户类型说明

组件	安装用户	运行用户
NPU 驱动	root	HwHiAiUser (默认)

由于安装驱动时, 运行用户和用户组默认指定为 HwHiAiUser, 需在安装软件包前自行创建 HwHiAiUser 的运行用户和用户组。

若创建的用户和用户组是非 HwHiAiUser (含 root), 安装驱动时必须指定运行用户。

本文档中的示例步骤使用的用户:

• 以 root 用户 安装驱动
• 以 非 root 用户 HwHiAiUser (驱动的默认运行用户) 为运行用户

默认用户 HwHiAiUser 的用途和配置要求, 请以《Atlas 系列硬件产品 账户清单》为准。

2.2 准备 HwHiAiUser 用户

# 创建用户组
groupadd HwHiAiUser

# 创建运行用户 (驱动的默认运行用户)
useradd -g HwHiAiUser -d /home/HwHiAiUser -m HwHiAiUser -s /bin/bash

# 验证
id HwHiAiUser
# 期望: uid=1000(HwHiAiUser) gid=1000(HwHiAiUser) groups=1000(HwHiAiUser)

若想创建其他非 root 用户, 请用户自行创建。

2.3 安装依赖和配置昇腾源

2.3.1 检查源是否可用

# 执行如下命令检查源是否可用
sudo apt-get update

如果命令执行报错或者等待时间过长, 则检查网络是否连接, 或修改 /etc/apt/sources.list 文件为可用源 (以配置华为镜像源为例, 可参考华为开源镜像站中镜像源对应的配置方法操作)。

2.3.2 安装编译依赖

# 执行命令安装所需依赖
sudo apt-get install -y make dkms gcc linux-headers-$(uname -r)

2.3.3 配置昇腾源

# 下载签名 keyring
wget https://ascend.devcloud.huaweicloud.com/cann/debian/cann-keyring_1.0.0_all.deb

# 安装 keyring (信任昇腾源签名)
sudo dpkg -i cann-keyring_1.0.0_all.deb

# 刷新源
sudo apt-get update

2.4 安装 NPU 驱动

2.4.1 选择产品类型包名

产品类型	apt 包名
Atlas 350 加速卡	atlas-350-hdk-npu-driver
Atlas A3 系列产品	atlas-a3-hdk-npu-driver
Atlas A2 系列产品	atlas-a2-hdk-npu-driver
Atlas 训练系列产品	atlas-train-hdk-npu-driver
Atlas 推理系列产品	atlas-infer-hdk-npu-driver

本文以 Atlas A3 系列产品为例。

2.4.2 安装命令

# 1. 搜索可用版本
apt-cache search atlas-a3-hdk-npu-driver
# 输出示例:
# atlas-a3-hdk-npu-driver/noble 26.0.rc1 [upgradable from: 26.0.rc1]

# 2. 安装指定版本 (推荐固定版本)
sudo apt-get install atlas-a3-hdk-npu-driver=26.0.rc1

安装完成后, 可根据系统提示信息决定是否重启系统, 若需要重启, 请执行 reboot 命令。

2.4.3 验证驱动加载

# 重启后登录, 查看 NPU 是否识别
npu-smi info

# 期望输出: N 张 Atlas A3 卡, Health: OK
# +----------------------------------------------------------------------------+
# | npu-smi 25.5.0    Version: 25.5.0                                          |
# +========================+============+===========+...+
# | NPU  Name             | Health     | Power(W)  |...+
# | 0     Atlas-A3        | OK         | 89.6      |...+
# | 1     Atlas-A3        | OK         | 89.6      |...+
# | ...                                                                        |
# +========================+============+===========+...+

2.5 常见驱动问题

现象	根因	解决
apt-get install 找不到包	昇腾源没配	重做 §2.3.3, 确认 cann-keyring 装好
npu-smi: command not found	PATH 没配	重连 ssh (驱动装时会自动写 PATH)
NPU 显示 Unhealthy	固件版本不匹配	查官方兼容性表, 重装匹配固件
装完重启黑屏	内核版本不对	查昇腾兼容性列表, 换兼容内核
报 “用户不存在”	没建 HwHiAiUser	重做 §2.2

---

三、安装 CANN

本节介绍通过 apt-get 快速安装 CANN 软件的操作步骤。

3.1 安装依赖

安装前需确保已具备 Python 环境及 pip3。

3.1.1 当前 CANN 支持的 Python 版本

Python 3.7.x 至 3.13.x

3.1.2 不满足时安装 Python

sudo apt-get install -y python3 python3-pip

若安装失败、版本不满足, 或者未包含动态库 libpython3.x.so, 请参考编译安装 Python 操作。

3.2 配置昇腾源

驱动装好后, 源已经配过了 (cann-keyring 已装)。如未装, 重新执行:

wget https://ascend.devcloud.huaweicloud.com/cann/debian/cann-keyring_1.0.0_all.deb
sudo dpkg -i cann-keyring_1.0.0_all.deb
sudo apt-get update

3.3 安装 Toolkit 开发套件包

CANN Toolkit 开发套件包, 在训练&推理&开发调试场景下安装, 主要用于训练和推理业务、模型转换、算子/应用/模型的开发和编译。

须知

• 安装 Toolkit 软件前请确保安装目录可用空间大于 10G, 如不满足请清理空间或更换安装目录
• apt-get 在线安装时仅支持安装在默认路径 /usr/local/Ascend 下

安装命令

# 1. 搜索
apt-cache search ascend-cann-toolkit
# 输出: ascend-cann-toolkit/noble 9.1.0-beta.1

# 2. 安装指定版本
sudo apt-get install ascend-cann-toolkit=9.1.0-beta.1

配置环境变量

# 激活 CANN 环境
source /usr/local/Ascend/cann/set_env.sh

# 验证
echo $ASCEND_HOME_PATH
# 期望: /usr/local/Ascend/cann

上述环境变量配置只在当前窗口生效, 用户可以按需将以上命令写入环境变量配置文件 (如 .bashrc 文件)。

永久生效

echo "source /usr/local/Ascend/cann/set_env.sh" >> ~/.bashrc
source ~/.bashrc

3.4 安装 ops 算子包

CANN 算子包集成一系列库文件, 包括:

• 算子基础框架
• 算子库 (包含 math、nn、cv 和 transformer)
• TBE 算子
• HCCL 集合通信库
• HIXL 单边通信库
• DVPP 库

具体文件包括单算子 API 执行 (如 aclnn 类 API) 动态库/静态库文件、算子源码以及 kernel 二进制文件, 优化高性能计算场景下的整体运行能力。

须知

• 安装 ops 算子包前, 需已安装兼容版本的 Toolkit 软件包, 并安装在统一路径下
• 请选择运行设备对应的 ops 软件包
• 多个芯片的 ops 算子包暂不支持安装在同一路径下, 用户可以在不同路径下分别安装 Toolkit 和不同芯片的 ops, 以满足多芯片环境下的开发和部署需求

选择产品类型包名

产品类型	apt 包名
Atlas 350 加速卡	atlas-350-cann-ops
Atlas A3 系列产品	ascend-cann-a3-ops
Atlas A2 系列产品	ascend-cann-a2-ops
Atlas 训练系列产品	ascend-cann-train-ops
Atlas 推理系列产品	ascend-cann-infer-ops
Atlas 200I/500 A2 推理产品	ascend-cann-a200i-a2-ops

安装命令

# 以 Atlas A3 为例
sudo apt-get install ascend-cann-a3-ops=9.1.0-beta.1

3.5 安装 NNAL 神经网络加速库 (可选)

NNAL 神经网络加速库中提供了:

• ATB (Ascend Transformer Boost) 加速库
• SiP (AscendSiPBoost) 信号处理加速库

须知

• 加速库安装之前, 需已安装同一版本的 Toolkit 并配置环境变量
• apt-get 在线安装时仅支持安装在默认路径 /usr/local/Ascend 下

安装命令

sudo apt-get install ascend-cann-nnal=9.1.0-beta.1

配置环境变量

# ATB 加速库
source /usr/local/Ascend/nnal/atb/set_env.sh

# 或 SiP 加速库
source /usr/local/Ascend/nnal/asdsip/set_env.sh

上述环境变量配置只在当前窗口生效, 用户可以按需将以上命令写入环境变量配置文件 (如 .bashrc 文件)。

3.6 装 torch_npu (Python 包)

# 推荐清华镜像 (下载快)
python3 -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 装 torch + torch_npu (版本必须匹配!)
# 查 https://www.hiascend.com/document 找最新版本对应表
python3 -m pip install torch==2.7.1
python3 -m pip install torch-npu==2.7.1.post1

# 验证
python3 -c "import torch, torch_npu; print(torch.__version__, torch_npu.__version__)"

3.7 apt 包版本一致性 (★ 重要)

# 一键检查所有昇腾包版本
dpkg -l | grep -E "atlas-a3-hdk|ascend-cann" | sort
# 期望看到清晰的版本号, 4 个包版本前缀一致
# 示例:
# ii  ascend-cann-a3-ops           9.1.0-beta.1
# ii  ascend-cann-nnal             9.1.0-beta.1
# ii  ascend-cann-toolkit          9.1.0-beta.1
# ii  atlas-a3-hdk-npu-driver      26.0.rc1

CANN 三个包必须严格同版本 (本例都是 9.1.0-beta.1), 驱动独立编号 (26.0.rc1)。

3.8 apt 包常用管理命令

# 列出已装昇腾包
dpkg -l | grep -E "atlas|ascend-cann"

# 升级指定包
sudo apt-get install --only-upgrade ascend-cann-toolkit=9.1.0.1

# 卸载
sudo apt-get purge ascend-cann-toolkit
sudo apt-get autoremove

# 锁版本 (生产推荐)
sudo apt-mark hold ascend-cann-toolkit ascend-cann-a3-ops

# 查包内文件
dpkg -L ascend-cann-toolkit

---

四、环境验证

按"硬件 → 驱动 → CANN → Python"四层顺序验证, 任一失败立刻定位。

4.1 硬件层: NPU 设备可见

# 检查 NPU 数量和健康
npu-smi info -l
# 期望: N 个 Atlas A3, 全部 Health: OK

# 检查 NPU 拓扑
npu-smi info -t topo
# 期望: 看到 HCCS 互联拓扑图

4.2 驱动层: 设备文件

# 设备文件应存在
ls -l /dev/davinci*
# 期望: N 个 /dev/davinci0 ~ /dev/davinci(N-1)

# 内核模块已加载
lsmod | grep -E "drv_pcie_ascend|davinci"
# 期望: 看到 drv_pcie_ascend 等模块

# dpkg 包确认
dpkg -l | grep atlas-a3-hdk-npu-driver
# 期望: ii  atlas-a3-hdk-npu-driver  26.0.rc1

4.3 CANN 层: 工具链

# 确认环境已激活
echo $ASCEND_HOME_PATH
# 期望: /usr/local/Ascend/cann

# Python 能 import ACL 包
python3 -c "import acl; print('ACL:', acl.get_version())"
# 期望: ACL: x.x.x

4.4 Python 层: torch_npu 跑通

python3 << 'PY'
import torch
import torch_npu

print(f"NPU available: {torch.npu.is_available()}")
print(f"NPU count: {torch.npu.device_count()}")
print(f"torch version: {torch.__version__}")
print(f"torch_npu version: {torch_npu.__version__}")

# tensor 转换
x = torch.randn(3, 4).npu()
print(f"x device: {x.device}")

# 基础计算
y = x + 1
torch.npu.synchronize()
print(f"y mean: {y.mean().item():.4f}")

print("✅ torch_npu 验证通过")
PY

期望:

NPU available: True
NPU count: 8
x device: npu:0
y mean: 1.xxxx
✅ torch_npu 验证通过

4.5 端到端: ResNet-50 推理

python3 << 'PY'
import torch
import torch_npu
import torchvision.models as models

model = models.resnet50(weights=models.ResNet50_Weights.DEFAULT)
model = model.npu().eval()

x = torch.randn(1, 3, 224, 224).npu()
with torch.no_grad():
    y = model(x)
    pred = y.argmax(dim=1).item()

print(f"Predicted class: {pred}")
print("✅ 真实模型跑通")
PY

期望: 输出 0-999 的 ImageNet 类别, 无报错。

4.6 验证清单总结

层	验证命令	期望
硬件	npu-smi info -l	N 卡 OK
设备	ls /dev/davinci*	N 个文件
驱动包	dpkg -l | grep atlas-a3-hdk-npu-driver	26.0.rc1 已装
CANN	python -c "import acl"	成功
Toolkit	echo $ASCEND_HOME_PATH	/usr/local/Ascend/cann
ops	dpkg -l | grep ascend-cann-a3-ops	9.1.0-beta.1 已装
torch	python -c "import torch_npu"	成功
NPU 可用	torch.npu.is_available()	True
端到端	ResNet-50 推理	输出预测

全部通过 = 环境搭建完成 ✅

---

五、常见问题排查

现象	根因	解决
apt-get install 找不到包	昇腾源没配或 keyring 没装	重做 §2.3.3, 确认 dpkg -i cann-keyring_*.deb 成功
apt-get install 报 GPG 错误	昇腾源没签名	必须装 cann-keyring, 不要 --allow-unauthenticated
npu-smi: command not found	PATH 没配	重连 ssh (驱动装时会自动写 PATH)
Toolkit 装完 atc 找不到	没 source set_env.sh	source /usr/local/Ascend/cann/set_env.sh
import torch_npu 报 “找不到版本匹配的 torch”	torch 与 torch_npu 版本不匹配	用 pip install torch==X.Y.Z torch-npu==X.Y.Z.postN 严格匹配
torch.npu.is_available() 返回 False	驱动没装 / 用户无 NPU 设备权限	1) npu-smi info 检查 2) 把用户加进 HwHiAiUser 组
报 “user HwHiAiUser does not exist”	没建运行用户	重做 §2.2
报 “directory not empty” (Toolkit 装)	旧版本残留	卸载干净后重装, 或换路径装
ops 装时报 “no matching toolkit”	Toolkit 和 ops 版本不一致	用相同版本号 (本例都是 9.1.0-beta.1)
8 卡跑 ResNet 慢如 CPU	CPU 模式没切	检查 torch.npu.is_available() 必须是 True

---

六、参考链接

资源	链接
昇腾官方文档 (CANN 9.1.0-beta.1)	https://www.hiascend.com/document
驱动/固件/CANN 下载	https://www.hiascend.com/developer/download
华为云 ascend 镜像	https://ascend.devcloud.huaweicloud.com
昇腾 apt 源 keyring	https://ascend.devcloud.huaweicloud.com/cann/debian/cann-keyring_1.0.0_all.deb
开发者学院	https://www.hiascend.com/developer/courses
torch_npu 官方	https://gitee.com/ascend/pytorch
昇腾开发者论坛	https://www.hiascend.com/forum

---

总结

Ubuntu 在线 apt-get 安装 = 1 个 keyring + 5 个 apt-get install 命令。

1. 创建 HwHiAiUser 用户 (驱动默认运行用户)
2. wget cann-keyring_1.0.0_all.deb && sudo dpkg -i ... && sudo apt-get update 配源
3. sudo apt-get install -y make dkms gcc linux-headers-$(uname -r) 装编译依赖
4. sudo apt-get install atlas-a3-hdk-npu-driver=26.0.rc1 装驱动
5. sudo apt-get install ascend-cann-toolkit=9.1.0-beta.1 装 Toolkit
6. sudo apt-get install ascend-cann-a3-ops=9.1.0-beta.1 装算子
7. sudo apt-get install ascend-cann-nnal=9.1.0-beta.1 (可选)
8. pip install torch==2.7.1 torch-npu==2.7.1.post1 装 Python 包