什么是 cann-learning-hub？

cann-learning-hub 是昇腾 CANN 开源社区的官方学习仓库，专门为零基础开发者提供一步步的上手教程。

它的定位很明确：让没接触过昇腾 NPU 的人也能快速跑起来。仓库里提供了完整的开发环境配置、基础算子调用、模型推理等教程，每个教程都有详细的步骤说明和可运行的代码。

仓库地址：https://atomgit.com/cann/cann-learning-hub

这篇文章面向零基础读者，手把手带你配置昇腾 NPU 开发环境，跑通第一个推理脚本。不涉及任何前置知识，全部从零开始。

环境要求

硬件

昇腾 NPU 设备，常见型号：

• Atlas 300I Pro（推理卡，单卡，适合入门）
• Atlas 300T Pro（训练卡，单卡）
• Atlas 800（服务器，8 卡）
• Atlas 200I DK（开发板，适合学习，性价比高）

新手推荐用 Atlas 200I DK（开发板，价格便宜，~3000 元）或 Atlas 300I Pro（推理卡，~2 万元）。

软件

• Linux 系统：Ubuntu 20.04 / 22.04 / EulerOS（推荐 Ubuntu 22.04）
• CANN Toolkit：昇腾 CANN 工具链，这是最核心的软件包
• Python 3.8+：推荐 3.10
• CUDA 可选：如果要在同一台机器上跑 NVIDIA GPU，CUDA 版本要和 CANN 兼容

Windows 用户注意：CANN 只支持 Linux，不能在 Windows 上直接用。如果只有 Windows 机器，有两个选择：

1. 装双系统（Linux + Windows）
2. 用云服务器（华为云、阿里云有昇腾 NPU 实例）

第一步：安装 CANN Toolkit

CANN（Compute Architecture for Neural Networks）是昇腾 NPU 的软件开发平台，类似于 NVIDIA 的 CUDA Toolkit。

下载 CANN

去昇腾官网下载 CANN Toolkit：

下载地址（昇腾社区）：https://www.hiascend.com/developer/download/community/result

选择对应版本：

• CANN 版本要和硬件匹配（Atlas 300I Pro 用 CANN 8.0，Atlas 200I DK 用 CANN 6.x）
• 推荐下载 CANN Toolkit（包含开发工具 + 运行时），不要只下 Runtime（没有编译器）

文件大概 2-3GB，下载时间取决于网速。

安装 CANN

# 1. 把下载的 CANN 包传到 Linux 服务器上（用 scp 或 U 盘）

# 2. 给安装脚本加执行权限
chmod +x cann't*.run

# 3. 运行安装（推荐用 root 安装到系统目录）
sudo ./cann'8.0*.run --install

# 如果想安装到用户目录（不需要 root）
./cann'8.0*.run --install --install-for-all

# 4. 设置环境变量（每次开终端都要用，可以加到 ~/.bashrc）
source /usr/local/Ascend/ascend-toolkit/set_env.sh

⚠️ 坑 1：安装时报 “包依赖不满足”。

CANN 的安装脚本会检查系统依赖，缺什么报什么。常见缺失的包：

# Ubuntu/Debian 系统，缺啥装啥
sudo apt update
sudo apt install -y gcc g++ make cmake libfreeimage3 libopencv-dev python3-dev python3-pip

# 如果 CANN 报 glibc 版本不对
# 检查当前 glibc 版本
ldd --version

# glibc 版本 >= 2.17 就行，如果太旧要升级系统

⚠️ 坑 2：多用户同时用同一张 NPU 会冲突。

CANN 的运行时不支持多用户并发访问同一 NPU 设备。实验室多用户场景建议用 npu-smi 分配设备：

# 查看当前 NPU 状态
npu-smi info

# 分配设备给当前用户（假设分配第 0 张卡）
export ASCEND_VISIBLE_DEVICES=0

# 验证安装成功
npu-smi info | grep "Chip"
# 应该输出类似：HiSilicon Hi1930AC C20 （Atlas 300I Pro）

验证 CANN 安装

# test_cann.py
import acl

# 初始化 ACL（Ascend Computing Language，CANN 的运行时 API）
ret = acl.init()
if ret == 0:
 print("✅ CANN 初始化成功")
else:
 print(f"❌ CANN 初始化失败，错误码: {ret}")

# 查询设备信息
device_count = acl.getDeviceCount()
print(f"检测到 {device_count} 个昇腾 NPU 设备")

# 申请一个设备
device_id = 0
ret = acl.setDevice(device_id)
if ret == 0:
 print(f"✅ 成功绑定设备 {device_id}")
else:
 print(f"❌ 绑定设备失败，错误码: {ret}")

# 清理资源
acl.finalize()

运行：

python test_cann.py

输出类似：

✅ CANN 初始化成功
检测到 1 个昇腾 NPU 设备
✅ 成功绑定设备 0

CANN 安装成功。

第二步：安装 PyTorch + torch-npu

昇腾 NPU 的 PyTorch 适配层，让 PyTorch 模型能自动调度到 NPU 上运行。

安装 torch-npu

# 1. 先装 PyTorch（CPU 版本，不要装 CUDA 版本）
pip install torch==2.1.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# 2. 再装 torch-npu（PyTorch 昇腾后端）
# torch-npu 版本必须和 CANN 版本配套
# CANN 8.0 → torch-npu 2.1.0
# CANN 8.5 → torch-npu 2.3.0
pip install torch-npu==2.1.0

⚠️ 坑 3：torch-npu 版本和 CANN 版本不匹配。

这是最常见的报错原因。CANN 8.0 装 torch-npu 2.3.0 会报 RuntimeError: Ascend CL version mismatch。

版本对应表（在昇腾官网搜"CANN 配套 PyTorch"）：

CANN 版本	torch-npu 版本	PyTorch 版本
CANN 6.3	1.8.2	1.11
CANN 7.0	2.0.0	2.0
CANN 8.0	2.1.0	2.1
CANN 8.5	2.3.0	2.3

⚠️ 坑 4：安装 torch-npu 报 SSL 证书错误。

国内网络访问 PyPI 源有时会 SSL 报错，换国内镜像源：

pip install torch-npu==2.1.0 -i https://mirrors.aliyun.com/pypi/simple/

验证 torch-npu

# test_torch_npu.py
import torch
import torch_npu

print(f"PyTorch 版本: {torch.__version__}")
print(f"torch-npu 版本: {torch_npu.__version__}")

# 检查 NPU 是否可用
if torch.npu.is_available():
 print(f"✅ NPU 可用，设备数量: {torch.npu.device_count()}")
 print(f"设备名称: {torch.npu.get_device_name(0)}")

 # 简单测试：在 NPU 上跑个矩阵乘法
 a = torch.randn(1000, 1000).npu()
 b = torch.randn(1000, 1000).npu()
 c = torch.mm(a, b)
 print(f"✅ NPU 矩阵乘法测试通过，结果形状: {c.shape}")
else:
 print("❌ NPU 不可用")

运行：

python test_torch_npu.py

输出类似：

PyTorch 版本: 2.1.0
torch-npu 版本: 2.1.0
✅ NPU 可用，设备数量: 1
设备名称: Ascend 910
✅ NPU 矩阵乘法测试通过，结果形状: torch.Size([1000, 1000])

PyTorch + torch-npu 安装成功。

第三步：跑通第一个推理脚本

环境配好了，现在跑一个真正的模型推理——用 transformers 在昇腾 NPU 上跑 Qwen2.5-7B。

安装依赖

# transformers 库
pip install transformers==4.36.0

# accelerate（加速加载）
pip install accelerate

# 其他依赖
pip install sentencepiece protobuf tiktoken

下载模型

昇腾 NPU 目前不支持直接加载 HuggingFace 格式的模型，要用华为的 ModelLink 格式。

两种方式：

方式 A：用 ModelScope 下载（国内快，推荐）

# 1. 安装 ModelScope
pip install modelscope

# 2. 下载 Qwen2.5-7B 模型
python -c "
from modelscope import snapshot_download
snapshot_download('Qwen/Qwen2.5-7B-Instruct', cache_dir='./models')
"

方式 B：用 ModelLink 转换（昇腾推荐格式）

# 1. 安装 ModelLink
pip install model_link

# 2. 从 HuggingFace 下载模型（需要梯子）
# huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct

# 3. 转换成昇腾格式
python -m model_link.convert \
 --input ./models/Qwen2.5-7B-Instruct \
 --output ./models/Qwen2.5-7B-NPU \
 --dtype fp16

⚠️ 坑 5：模型下载失败或下载很慢。

ModelScope 有时下载中断，断点续传：

from modelscope import snapshot_download
snapshot_download(
 'Qwen/Qwen2.5-7B-Instruct',
 cache_dir='./models',
 revision='master'
)

如果下载中断，直接重新运行即可，ModelScope 会自动续传。

运行推理

# infer_qwen.py
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载模型到昇腾 NPU
model_path = "./models/Qwen2.5-7B-NPU"

print("加载模型中（首次加载需要几分钟）...")
model = AutoModelForCausalLM.from_pretrained(
 model_path,
 torch_dtype=torch.float16,
 device_map="npu:0" # 关键：指定 NPU 设备
)

tokenizer = AutoTokenizer.from_pretrained(model_path)
print("模型加载完成！")

# 构造输入
prompt = "用 Python 写一个快速排序函数"
messages = [
 {"role": "system", "content": "你是一个专业的 Python 程序员。"},
 {"role": "user", "content": prompt}
]

text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
input_ids = tokenizer([text], return_tensors="pt").to("npu:0")

# 生成
print("推理中...")
with torch.no_grad():
 output_ids = model.generate(
 **input_ids,
 max_new_tokens=512,
 do_sample=True,
 temperature=0.7,
 top_p=0.9
 )

# 解码输出
response = tokenizer.decode(output_ids[0][input_ids.input_ids.shape[1]:], skip_special_tokens=True)
print("\n=== 模型输出 ===")
print(response)

运行：

python infer_qwen.py

如果一切正常，应该能看到模型输出类似：

加载模型中（首次加载需要几分钟）...
模型加载完成！
推理中...
=== 模型输出 ===
以下是快速排序的实现：

def quicksort(arr):
 if len(arr) <= 1:
 return arr
 
 pivot = arr[len(arr) // 2] # 选择中间元素作为枢轴
 
 left = [x for x in arr if x < pivot]
 middle = [x for x in arr if x == pivot]
 right = [x for x in arr if x > pivot]
 
 return quicksort(left) + middle + quicksort(right)

# 示例
arr = [3, 6, 8, 10, 1, 2, 1]
print(quicksort(arr)) # 输出: [1, 1, 2, 3, 6, 8, 10]

恭喜，第一个昇腾 NPU 推理脚本跑通了！

cann-learning-hub 里还有什么？

cann-learning-hub 提供了多个逐步教程，覆盖不同层次的需求：

入门教程（适合新手）：

• 环境配置（CANN + torch-npu + 推理框架）
• 基础算子调用（ACL 接口调用）
• 模型转换（HuggingFace → 昇腾格式）
• 简单推理（用 transformers 跑小模型）

进阶教程（适合有经验的开发者）：

• 自定义算子开发（Ascend C 编程）
• 性能调优（Profiling + NPU-SMI）
• 分布式训练（多卡训练）
• 模型部署（TensorRT 风格加速）

场景教程（按应用分类）：

• LLM 推理（Qwen、LLaMA、ChatGLM 等）
• 多模态模型（CLIP、BLIP 等）
• CV 模型（ResNet、YOLO 等）
• 强化学习（PPO、DQN 等）

每个教程都有对应的示例代码（在仓库的 examples/ 目录下），可以直接下载运行。

常见问题汇总

问题	原因	解法
npu-smi: command not found	CANN 没装好	重新安装 CANN，或 source /usr/local/Ascend/ascend-toolkit/set_env.sh
RuntimeError: device count is 0	NPU 驱动没加载	`lsmod
torch.npu.is_available() 返回 False	torch-npu 没装或版本不匹配	检查 torch-npu 版本，参考上面的版本表
推理报 OOM（显存不足）	模型太大或 batch 太大	减小 seq_le
…(truncated)…