昇腾平台环境搭建

昇腾平台环境搭建 — 从裸机到 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 包
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙 ArkTS 常用基础组件总结

用途：可点击交互组件，用来接收用户点击操作，实现提交、取消、删除、页面跳转、修改变量、弹出弹窗等交互逻辑。：输入框组件，允许用户手动打字输入内容，常用于登录账号、填写表单。分组使用，典型场景：性别选择、单选题选项。可设置宽高、缩放模式、圆角、透明度等样式。：静态文本组件，只用来展示文字，用来加载显示本地 / 网络图片。调用的图片路径：打开项目，可点击交互控件，绑定。

avatar 人工智能6S服务平台

鸿蒙基础组件

系统提供 5 类常用基础布局，分别为：垂直布局、水平布局、相对布局、层叠布局、弹性布局。布局通用属性：所有布局容器均支持width、height、padding、margin、justifyContent、alignItems等通用样式控制组件对齐、间距与尺寸。排列规则：可自由切换水平 / 垂直主轴方向，支持子组件自动换行、自动均分剩余空间，兼具 Row 与 Column 能力，是自适应页面首选布

avatar 人工智能6S服务平台

【昇腾/AscendC开发】AscendC DataCopyPad 写出溢出 Bug 详解

要点说明AscendC DMA burst 最小 32B的lenBurst参数必须是 32 的倍数UB→GM 方向无 padding 控制不像 GM→UB 有，UB→GM 只有 3 参数版本溢出只影响空段有数据的段会被后续写出覆盖回来，但空段不会被写 → 残留垃圾feat_dim 最好是 8 的倍数，完美对齐，从根本上避免溢出先测小维度如果我们只测 feat_dim=128，永远不会发现这个 bu

avatar 人工智能6S服务平台