上周刚入职，接到的第一个任务是：在昇腾 NPU 上跑通一个预训练模型。

leader 丢给我一个 cann-learning-hub 的链接，说：“先从这个学，跟着走就行。”

我打开仓库一看，55 个子目录。我懵了。

这篇教程记录我从零到跑通模型的全过程，包括踩过的三个坑。不废话，直接开始。

---

第一步：先搞清楚你要的环境对不对

很多人上来就 clone 仓库，然后照着 README 敲命令。敲到一半报错了，问 leader，leader 看了眼说：“版本不对。”

我第一遍就是这个结局。

在你做任何事情之前，先执行这几条命令：

# 检查 NPU 能否识别
npu-smi info

# 看 CANN 版本
cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg

# 看 Python 版本（CANN 要求 3.7-3.11）
python3 --version

我的机器上 npu-smi 能识别，但 CANN 版本是 7.1，cann-learning-hub 里的示例要求 8.0+。

第一个坑：版本不匹配导致编译失败。

CANN 版本号看的是 ascend-toolkit 目录下的 version.cfg，不是驱动版本。如果你不知道当前版本是多少，执行上面的命令。

如果版本低于 8.0，去昇腾官网下载 CANN 社区版，升级后再继续

# 我的环境输出来是这样的（对照检查）
$ npu-smi info
+-----------------------------------------------------------------------------+
| npu-smi 23.0.3 Version: 23.0.3 |
+-----------------------------------------------------------------------------+
| 芯片 | 物理ID | 健康状态 | 功耗 | 温度 | 算力使用率 | 内存使用率 |
|--------|--------|---------|------|------|-----------|-----------|
| 910 | 0 | OK | 86W | 47C | 0% | 34% |
+-----------------------------------------------------------------------------+

$ cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
[version]
CANN_version = 8.0.RC2

CANN 8.0 以上才能用 cann-learning-hub 里的新特性。低于这个版本，部分示例跑不通。

---

第二步：把仓库 clone 下来，别急着跑

git clone https://atomgit.com/cann/cann-learning-hub.git
cd cann-learning-hub

进去之后你会看到一堆目录：

cann-learning-hub/
├── L0c_Samples/ # 基础样例
├── L1c_Fundamentals/ # 基础知识
├── L2e_Inference/ # 推理入门
├── L3a_Operator/ # 算子开发
├── L4d_Framework/ # 框架适配
├── README.md
└── setup_env.sh # 自动环境配置脚本

第二个坑：不要从 L0c_Samples 开始。

我第一次是从 L0c_Samples 开始学的，照着 README 敲命令，每一步都报莫名其妙的错。后来才知道，那个目录里的样例依赖的东西太多，新手环境很难配齐。

正确的路径是：

1. 先跑 setup_env.sh（自动装依赖）
2. 再从 README.md 开始，按文档推荐的顺序走
3. 最后才碰样例代码

# 先跑环境配置脚本
bash setup_env.sh

# 脚本执行完后，检查环境
python3 -c "import acl; print('ACL OK')"
python3 -c "import torch; print(f'PyTorch {torch.__version__}')"

setup_env.sh 会自动检查并安装缺失的依赖。如果脚本执行失败，大概率是因为网络问题——昇腾的工具链下载站有时候访问不稳定。

遇到网络问题怎么办？

# 方法1：设置国内镜像
export ASCEND_HOME=/usr/local/Ascend/ascend-toolkit/latest
export ASCEND_PACKAGE_PATH=/path/to/your/package

# 方法2：跳过在线安装，手动指定本地路径
# 先去昇腾官网下载完整包，解压后设置路径
export ASCEND_HOME=/path/to/your/cann-package/ascend-toolkit/latest

---

第三步：跑通第一个示例

环境配好之后，找一个最简单的示例跑一下验证。

cann-learning-hub 里最基础的是 L0c_Samples/1_acl/ 目录下的 ACL 推理示例。

cd L0c_Samples/1_acl

# 看目录结构
ls -la
# 应该看到这些文件：
# ├── CMakeLists.txt
# ├── run.sh
# ├── model/
# └── src/

编译前先看 README，不要跳过这一步：

cat README.md
# 里面会告诉你：
# 1. 依赖哪些库
# 2. 环境变量怎么设
# 3. 怎么编译
# 4. 怎么运行

按照 README 的步骤来：

# 设置环境变量
source set_env.sh

# 编译
bash build.sh

# 运行
bash run.sh

第三个坑：编译报错了不要慌，先看错误信息。

我第一次编译时报这个错：

/usr/bin/ld: cannot find -lascend_cl

原因是我漏执行了 source set_env.sh。环境变量没设置，编译器找不到 CANN 的库。

解决方案很简单：

# 每次编译前都执行这一行
source set_env.sh

# 然后再编译
bash build.sh

这个坑我踩了两次才记住——每次新开终端都要重新 source。

---

完整代码：从环境到运行的最小示例

把上面的步骤串起来，完整的操作流程：

# ========== 第一步：检查环境 ==========
npu-smi info
cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
python3 --version

# 确认 CANN >= 8.0，否则先升级

# ========== 第二步：clone 并设置环境 ==========
git clone https://atomgit.com/cann/cann-learning-hub.git
cd cann-learning-hub

# 跑自动环境配置（可能需要几分钟）
bash setup_env.sh

# 验证环境
python3 -c "import acl; print('ACL OK')"
python3 -c "import torch; print(f'PyTorch {torch.__version__}')"

# ========== 第三步：跑第一个示例 ==========
cd L0c_Samples/1_acl

# 设置环境变量（每次新终端都要执行）
source set_env.sh

# 编译
bash build.sh

# 运行
bash run.sh

# 预期输出：
# [ACL] Device init success
# [ACL] Model load success
# [ACL] Inference completed

如果 run.sh 执行后看到 Inference completed，说明环境配对了。

---

踩坑总结

坑	原因	解决
编译报 cannot find -lascend_cl	没 source set_env.sh	每次编译前先 source
示例跑不通	CANN 版本低于 8.0	升级 CANN
setup_env.sh 执行失败	网络问题	用离线包或镜像源

---

给新手的建议

跑通第一个示例之后，你会发现 cann-learning-hhub 的内容很多，很容易迷失方向。

我的建议是：按这个顺序走，不要跳级。

1. L0c_Samples：先跑通基础样例，知道昇腾 NPU 能做什么
2. L1c_Fundamentals：学核心概念，搞清楚 CANN 的五层架构是什么
3. L2e_Inference：学推理，从官方预训练模型开始
4. L3a_Operator：学算子开发，这个是进阶内容，先放一放

不要一上来就想学 L3/L4，那个需要前置知识。L0/L1/L2 搞透了再往上学，效率更高。

cann-learning-hub 的链接：https://atomgit.com/cann/cann-learning-hub

有问题去仓库的 Issues 问，社区响应挺快的。我入职第一周就是靠看 Issues 解决了三个问题，比看文档高效多了。