学 CANN 开发第一步看什么：cann-learning-hub 与加速库快速上手

旧梦735

406人浏览 · 2026-05-22 23:10:54

旧梦735 · 2026-05-22 23:10:54 发布

学 CANN 开发，第一步该看什么？

这个问题在社区里被问了无数次。新人在 AtomGit 上搜"CANN"，出来 55 个仓库，一脸茫然——不知道从哪个点进去，不知道哪些是必看的，不知道哪些可以等以后再说。

认知纠偏一：CANN 的学习资源不是 API 文档，是一套分层知识体系。 很多人以为 cann-learning-hub 就是一个文档站，打开一看有教程、有示例、有 recipes、有算子仓库链接，又懵了——这些之间是什么关系？为什么看完教程还是不会写算子？

答案在 CANN 的五层架构里。学习资源是按架构层级组织的，不是按"入门→进阶→高级"这种线性路径组织的。你如果跳过架构直接看算子代码，就像没学加减乘除直接看微积分。

cann-learning-hub 的价值正在于此：它把 55 个仓库按架构层级重新组织了学习路径，告诉你哪层先看、哪个仓库先碰、每个仓库学完能达到什么水平。这篇文章把这个学习路径拆开了讲，顺便把加速库（catlass、ATB、asnumpy）的快速上手方法一并讲清楚。

cann-learning-hub 到底是什么

先说清楚它不是什么。

它不是 API 参考手册。 你想查某个算子的参数列表，去 ops-transformer 的 README 或者 pyACL 的 API 文档，不要在 cann-learning-hub 里翻。

它不是视频课程集合。 里面确实有少量视频链接，但主体是文字教程、可运行示例、和 recipes（端到端模型训练/推理脚本）。

它不是仅面向新手的"入门指南"。 里面有面向初学者的"昇腾 NPU 开发入门"，也有面向算子开发者的"Ascend C 高级特性"，还有面向框架开发者的"GE Pass 开发指南"——它覆盖的是从零到深入的全路径。

那它到底是什么？

cann-learning-hub 是 CANN 开源社区的导航中心。 它解决的是一个很实际的问题：CANN 有 55 个仓库，一个新手开发者不知道从哪里开始，一个算子开发者不知道去哪个仓库提 PR，一个算法工程师不知道哪个加速库适合他的模型——cann-learning-hub 给每个人指路。

具体包含四类内容：

教程文章（tutorials/ 目录）：按架构层级组织的系统性教程，从 AscendCL 基础用法到 GE 编译原理，每个主题都是一篇独立文章，互相之间有跳转链接。

可运行示例（notebooks/ 目录）：Jupyter Notebook 格式，每个示例对应一个具体任务（比如"用 ops-transformer 跑 FlashAttention 推理"），代码可以直接运行，环境配置写在 Notebook 第一行。

Recipes 索引（recipes/ 目录）：指向 cann-recipes-* 系列仓库的入口，每个 recipe 是一个端到端可运行的模型训练/推理脚本，覆盖 LLM 推理、多模态、具身智能等场景。

社区资源汇总（community/ 目录）：算子开发规范、PR 提交流程、社区竞赛信息、技术博客链接。

认知纠偏二：看完教程不等于学会，动手跑示例才是

cann-learning-hub 里有一个很常见的"学习陷阱"：把教程文章从头到尾读一遍，觉得都看懂了，关掉浏览器，一行代码写不出来。

这不是你的问题，是学习资源的使用方式问题。CANN 是系统级软件栈，不是一门编程语言，光看不练等于没看。

正确的使用方式是：教程文章定方向，Notebook 示例定手感，recipes 定工程能力。

以 FlashAttention 为例，完整的学习路径是：

第一步：读 cann-learning-hub 的教程文章《FlashAttention 在昇腾 NPU 上的优化原理》，搞清楚 tile 策略、内存布局、DMA 预取这三个核心概念。这篇文章不长，20 分钟可以读完，读完后你应该能回答：FlashAttention 的中间分数矩阵 S 存在哪里？为什么 seq_len 要对齐到 64 的倍数？

第二步：打开 notebooks/flash_attention_benchmark.ipynb，按 Notebook 里的步骤跑一遍 benchmark，对比 ops-transformer 的实现和 PyTorch 原生实现的性能差距。跑完之后你会看到实际的性能数字，对"优化原理"那篇文章里的概念有直观感受。

第三步：去 cann-recipes-infer 仓，找 llama2-7b 的推理 recipe，看 FlashAttention 在一个完整模型里是怎么被调用的，GE 的融合策略是怎么配的，KV Cache 是怎么管理的。这一步是把"算子级理解"上升到"模型级理解"。

三步完成后，你才真正"学会"了 FlashAttention 在昇腾 NPU 上的用法。只看教程，停在第一步，等于没开始。

加速库快速上手：catlass、ATB、asnumpy 各解决什么问题

讲完学习路径，具体到加速库的上手，很多人会卡在"选哪个"这个问题上。

catlass、ATB（ascend-transformer-boost）、asnumpy 是三个定位完全不同的加速库，解决的不是同一个问题，不存在"哪个更好"的比较。

先用一张表把三者的定位说清楚：

加速库	定位	解决的核心问题	适用场景
catlass	算子模板库	“我想写高性能算子，但不想从零开始写 Ascend C”	算子开发者、需要自定义算子的工程师
ATB	Transformer 模型加速库	“我想让 Transformer 模型跑得更快，不想自己拼算子”	模型开发者、推理/训练性能优化工程师
asnumpy	NPU 原生 NumPy	“我想在 NPU 上跑 NumPy 风格的数值计算”	科学计算、需要 NumPy API 兼容性的场景

认知纠偏三：加速库不是"更快的算子实现"，是更高层的抽象。 catlass 不是"更快的 MatMul"，它是一套算子模板——你填模板参数，它生成针对昇腾 NPU 优化过的算子实现。你不写 Ascend C 代码，但你能得到接近手写 Ascend C 的性能。

ATB 更不是"更快的 FlashAttention"——它是把 FlashAttention、RMSNorm、FFN 等算子按最优方式组合好了，你调一个 TransformerLayer.forward()，内部所有算子的融合策略、KV Cache 管理、梯度检查点编排都已经按 CANN 的最佳实践配好了。

理解了这个定位差异，上手方法就清晰了。

catlass 快速上手：从模板到算子

catlass 的上手路径最短，因为它本质上是"填模板生成算子"，学习曲线平缓。

第一步：装 catlass。

# 克隆 catlass 仓
$ git clone https://atomgit.com/cann/catlass.git
$ cd catlass

# 安装依赖（需要 CANN 基础环境，包括 AscendCL 和 Ascend C 编译器）
$ pip install -r requirements.txt

# 验证安装
$ python -c "import catlass; print(catlass.__version__)"

第二步：跑一个 FlashAttention 的模板示例，感受"填模板"是什么体验。

# catlass 的 FlashAttention 模板调用（简化示例）
import catlass
from catlass.templates import FlashAttentionTemplate

# 创建一个 FlashAttention 算子实例
# 只需要填模板参数，不需要写 Ascend C 代码
fa_template = FlashAttentionTemplate(
    head_dim=128,
    tile_size=64,           # tile 大小，影响 L1 命中率
    softmax_scale=0.088,    # 1/sqrt(128)
    causal=False,           # 是否因果注意力
)

# 根据模板参数，catlass 自动生成针对当前硬件的算子实现
# 生成的算子已经做了 tile 划分、内存布局优化、DMA 预取
fa_op = fa_template.build(device="npu")

# 调用生成的算子
import torch
Q = torch.randn(4, 32, 2048, 128, dtype=torch.float16, device="npu")
K = torch.randn(4, 32, 2048, 128, dtype=torch.float16, device="npu")
V = torch.randn(4, 32, 2048, 128, dtype=torch.float16, device="npu")

output = fa_op(Q, K, V)
print(output.shape)  # (4, 32, 2048, 128)

这段代码里，你没有写一行 Ascend C 代码，但得到的 fa_op 是一个针对昇腾 NPU 达芬奇架构优化过的 FlashAttention 算子。模板参数（tile_size、causal、softmax_scale）决定了生成的算子的行为，catlass 在背后做了所有的底层优化。

第三步：把自己的自定义算子用 catlass 模板重写，对比性能。

如果你有一个自定义的注意力变体（比如加了相对位置编码的 Attention），用 Ascend C 从零写大概需要 3-5 天，用 catlass 模板改，可能半天就完成了，性能差距在 5% 以内。

ATB 快速上手：从 Layer 到模型

ATB 的上手比 catlass 更简单，因为它封装层级更高——你甚至不需要关心算子，直接调 Transformer Layer。

# ATB 快速上手：跑一个 LLaMA Layer
from ascend_transformer_boost import TransformerLayer

# 创建一个 LLaMA 风格的 Transformer Layer
# ATB 内部已经把所有算子（FlashAttention、RMSNorm、SwiGLU）按最优方式组合好了
layer = TransformerLayer(
    hidden_size=4096,
    num_heads=32,
    head_dim=128,
    intermediate_size=11008,
    layernorm_type="rmsnorm",
    attention_type="flash",   # 使用 FlashAttention
)

# 移动到 NPU
layer = layer.to("npu")

# 前向计算
hidden_states = torch.randn(4, 2048, 4096, dtype=torch.float16, device="npu")
outputs = layer(hidden_states)

print(outputs[0].shape)  # (4, 2048, 4096)

这就是 ATB 的核心价值：一行代码创建一个最优配置的 Transformer Layer。 你不需要关心 FlashAttention 的 tile_level 怎么设、RMSNorm 和哪个算子融合、KV Cache 怎么管理——ATB 内部已经按 CANN 的最佳实践配好了。

如果要做推理，加一个 mode="inference" 参数，ATB 自动开启 KV Cache 的分页管理和 DMA 预取：

# 推理模式
layer = TransformerLayer(
    hidden_size=4096,
    num_heads=32,
    head_dim=128,
    intermediate_size=11008,
    layernorm_type="rmsnorm",
    attention_type="flash",
    mode="inference",      # 推理模式（自动管理 KV Cache）
)

# 推理循环
past_key_values = None
for token_id in range(seq_len):
    hidden_states = ...  # 当前 token 的 hidden states
    outputs = layer(hidden_states, use_cache=True, past_key_values=past_key_values)
    hidden_states = outputs[0]
    past_key_values = outputs[1]  # KV Cache（ATB 内部管理）

asnumpy 快速上手：NPU 上的 NumPy

asnumpy 的上手是最简单的，因为它的 API 和 NumPy 几乎一模一样。

# asnumpy 快速上手
import asnumpy as anp
import numpy as np

# 创建一个 NPU 上的数组（API 和 NumPy 一样）
x_npu = anp.array([[1, 2, 3], [4, 5, 6]], dtype=anp.float16)
print(x_npu.device)  # npu:0

# 计算（和 NumPy 一样的 API）
y = anp.matmul(x_npu, x_npu.T)
print(y)

# 和 NumPy 数组互转
x_cpu = x_npu.to_numpy()   # NPU → CPU（NumPy）
x_npu2 = anp.from_numpy(x_cpu)  # CPU（NumPy）→ NPU

# FlashAttention 也可以用 asnumpy 风格调用
#（asnumpy 内部调用了 ops-transformer 的 FlashAttention 实现）
Q = anp.randn(4, 32, 2048, 128, dtype=anp.float16)
K = anp.randn(4, 32, 2048, 128, dtype=anp.float16)
V = anp.randn(4, 32, 2048, 128, dtype=anp.float16)

O = anp.nn.functional.scaled_dot_product_attention(Q, K, V)
print(O.shape)  # (4, 32, 2048, 128)

asnumpy 的核心价值：让 NumPy 用户零成本迁移到 NPU。 你会 NumPy，就会 asnumpy，不需要学 Ascend C，不需要学 AscendCL，甚至不需要知道 FlashAttention 的 tile 策略——scaled_dot_product_attention 内部已经调用了 ops-transformer 的优化实现。

FlashAttention 学习路径：从 cann-learning-hub 到 recipes

把上面的内容串起来，一个完整的 FlashAttention 学习路径是这样的：

第一站：cann-learning-hub 教程文章。 读《FlashAttention 在昇腾 NPU 上的优化原理》，搞清楚核心概念。时间：20 分钟。

第二站：cann-learning-hub Notebook 示例。 跑 notebooks/flash_attention_benchmark.ipynb，对比性能，直观感受优化效果。时间：30 分钟。

第三站：ops-transformer 仓。 读 FlashAttention 的算子实现代码（op_info.yaml 和 kernel 实现），理解 GE 是怎么拆解这个算子的、tile 策略是怎么实现的。时间：1-2 小时。

第四站：catlass 模板。 用 catlass 的 FlashAttentionTemplate 生成自己的 FlashAttention 算子，对比和 ops-transformer 标准实现的性能差距。时间：1 小时。

第五站：ATB 模型集成。 把 FlashAttention 放进一个完整的 Transformer Layer，用 ATB 的 TransformerLayer 管理检查点、KV Cache、算子融合。时间：1 小时。

第六站：cann-recipes-infer。 找一个完整的推理 recipe（比如 llama2-7b），看 FlashAttention 在端到端模型里是怎么被调用的，GE 的融合策略是怎么配的，性能瓶颈在哪里。时间：2-3 小时。

六站走完，你对 FlashAttention 在昇腾 NPU 上的理解从"知道有这个算子"变成了"能在生产环境里用好这个算子"。

结尾

cann-learning-hub 不是一份 API 文档，它是 CANN 开源社区的导航中心——55 个仓库、四个层级的学习资源，它帮你找到该从哪里开始、该往哪个方向深入。加速库（catlass、ATB、asnumpy）不是"更快的算子"，它们是不同层级的抽象：catlass 让你不写 Ascend C 也能得到高性能算子，ATB 让你不拼算子也能得到最优的 Transformer 模型，asnumpy 让你不学新 API 也能在 NPU 上跑数值计算。

理解这些定位差异，学习资源才能用对，加速库才能选对。