CANN高性能实战演进样例与体系化调优知识库
| Files | Last commit | Last update |
|---|---|---|
| 27 days ago | ||
| 9 days ago | ||
| 2 days ago | ||
| 9 days ago | ||
| 1 month ago | ||
| 12 days ago | ||
| 9 days ago | ||
| 9 days ago | ||
| 1 month ago | ||
| 26 days ago | ||
| 12 days ago | ||
| 2 months ago | ||
| 12 days ago | ||
| 25 days ago | ||
| 6 months ago | ||
| 9 months ago | ||
| 26 days ago | ||
| 26 days ago | ||
| 9 months ago | ||
| 9 months ago | ||
| 9 months ago | ||
| 9 days ago |
CANN-SAMPLES
昇腾 CANN 样例仓库
提供高性能实现示例与体系化调优知识库,从入门概念到极致性能,覆盖 MatMul、MoE、Attention 等核心算子的完整优化链路
使用 npusim 进行仿真需要 CANN 9.2.0 及以上版本。
📖 概述 · 🔥 最新动态 · 🛠️ 环境部署 · ✅ 环境自检 · 🚀 快速入门 · 📦 目录结构 · 💬 社区讨论
🚀概述
cann-samples 是 CANN(Compute Architecture for Neural Networks)实战样例仓库,提供高性能实现示例与体系化调优知识库。
本仓已集成代码仓库智能体,点击 徽章,进入其专属页面,开启在线智能代码学习与知识问答体验!
本仓为 Agent 提供了 samples skill,可用于查找样例、了解特性用法、获取算子优化建议等,一键安装命令如下:
npx skills add https://gitcode.com/cann/cann-samples.git --skill samples
🗺️ 用户导航
| 你是... | 推荐入口 | 预计耗时 |
|---|---|---|
| 👋 NPU 算子初学者 | 入门样例 → add / matmul 建立基本概念 |
30 min |
| 🏗️ 自有环境部署 | 环境部署 → 环境自检 → 快速入门 编译运行第一个样例 | 20 min |
| 🧠 NPU 新特性掌握 | 特性列表 → 探索芯片功能特性与优化方法 | 按需 |
| 🚀 追求极致性能 | 样例列表 → 按算子类型查找调优实践 | 按需 |
| 🔧 调试与性能分析 | 工具集 → 使用辅助工具分析算子性能瓶颈 | 按需 |
| ✨ 贡献代码 | 所属 SIG | 15 min |
为什么使用 cann-samples
| 维度 | 说明 |
|---|---|
| ⚡ 体系化调优知识库 | 从入门概念到极致性能,覆盖 MatMul、MoE、Attention 等核心算子的完整优化链路 |
| 🔬 端到端可复现 | 每个 story 提供 baseline→优化分步教程与可运行 recipe,配合 npusim trace 量化性能差异 |
| 🧠 硬件特性深挖 | 直击 ScalarBound、流水线排布、寄存器 Spill、SIMT / SIMD VF 编程等底层优化点 |
| 🧩 多数据类型覆盖 | 支持 BF16 / FP16 / HiFloat8 / MXFP4 / MXFP8 等多种精度与量化方案 |
| 🎯 多代际硬件适配 | 覆盖 Ascend 950(dav-3510)与 Ascend 910B/C(dav-2201)平台 |
🔥最新动态
- [2026/08] 新增 Kimi Delta Attention Lite、Softmax RegBase 递进优化和 Vector Function Add 样例,并上线环境自检脚本,进一步完善入门与性能调优体验。
- [2026/07] 新增 Flash Attention Lite、GELU + Element-wise RegBase、SIMT Histogram和 SIMT Scatter 调优实践,同时补充 NPU 访存带宽测试与 CV 数据通路优化样例。
- [2026/06] 建设 SIMD VF 常见范式,覆盖 Broadcast、Elementwise 与 Reduce;新增 Reg 数据搬运场景选型指南及 10 个可运行示例,并补充 KvRmsNormRopeCache RegBase优化实践。
- [2026/05] 矩阵乘与分组矩阵乘样例持续增强:新增 matmul_a16w16 StreamK、weight_quant_grouped_matmul_mxfp8fp4 MXA8W4 量化等高性能样例,并为 MXFP4/MXFP8 量化场景补充 Weight NZ 支持。
📝环境部署
请依次完成 CANN Toolkit 安装、环境变量配置和基础依赖安装。涉及 Tensor API 的样例还需配置 asc-devkit 子模块,具体要求见第 4 节。
1. 安装社区版 CANN Toolkit
根据使用场景选择 Weekly 版本或稳定版本,并在昇腾官网按产品系列、CPU 架构和操作系统下载对应的 CANN Toolkit 安装包,最后按页面提供的命令完成安装。
-
场景1:基于 CANN Weekly 版本体验最新 master 能力或开发
前往CANN 快速安装页面,选择“Weekly版本”。也可以从下方历史验证表中选择安装包。
-
场景2:基于 CANN 稳定版本体验分支能力或开发
前往CANN 快速安装页面,选择“稳定版本”。仅支持 CANN 9.0.0 正式版及更新版本。
历史验证通过的 Weekly 版本
下表记录了本仓库历史验证通过的社区版 CANN Toolkit Weekly 版本,按时间戳从新到旧排列,供安装时备选。请根据实际 CPU 架构选择下载链接;涉及 Tensor API 的样例请使用表中已验证通过的版本。
| CANN 版本 | 时间戳 | 验证结果 | 下载链接 |
|---|---|---|---|
9.1.0 |
20260720000024864 |
✅ PASS | aarch64 / x86_64 |
9.1.0 |
20260513000324948 |
✅ PASS | aarch64 / x86_64 |
9.1.0 |
20260508171052185 |
✅ PASS | aarch64 / x86_64 |
9.0.0 |
20260422000325096 |
✅ PASS | aarch64 / x86_64 |
2. 配置环境变量
安装完成后,执行以下命令使 CANN Toolkit 环境变量生效:
source ${install_path}/ascend-toolkit/set_env.sh
请将 ${install_path} 替换为 Toolkit 的实际安装目录,例如 /usr/local/Ascend 或 ${HOME}/Ascend。
3. 安装基础依赖
编译样例前,请确保已安装以下依赖并满足版本要求:
- CMake >= 3.16.0
- Python >= 3.10.0
- zip
- git
在仓库根目录执行以下命令,安装 Python 三方库依赖:
pip3 install -r requirements.txt
4. 配置 asc-devkit 子模块
矩阵乘等涉及 Tensor API 的样例依赖 asc-devkit 子模块。该子模块位于 third_party/asc-devkit,对应上游仓库 asc-devkit,当前固定在 feature/tensor_api_from_9.0.0 分支的 commit 04e3587dceb4792be9351e1057bf41772b5ffcd6。Tensor API 的头文件和实现分别位于其 include/tensor_api 与 impl/tensor_api 目录。
获取子模块
克隆本仓库时,建议一并获取子模块:
git clone --recurse-submodules <仓库 URL>
若已克隆仓库但未获取子模块,请在仓库根目录执行:
git submodule update --init third_party/asc-devkit
Toolkit 与硬件要求
- Toolkit:Tensor API 相关样例同时依赖 asc-devkit 的 Tensor API 头文件和 Toolkit 中的 Ascend C 头文件。请安装完整的 CANN Toolkit,使用上方历史验证表中已验证通过的版本,并按第 2 节配置环境变量。Toolkit 版本过旧、仅安装 Run 包或环境变量未生效时,可能出现头文件缺失、符号未定义或编译选项报错。
- NPU 架构:
matmul_story、grouped_matmul_story额外要求NPU_ARCH=dav-3510(Ascend 950)。使用dav-2201全量配置工程时,这两项样例会被跳过。
构建时的子模块处理
若未提前初始化子模块,CMake 在构建依赖 cann_samples::tensor_api 的目标时,也会尝试执行上述子模块更新命令。
Tensor API 与 SHMEM 的自动子模块更新通过 Git common directory 中的共同锁串行执行,避免并行构建竞争写入 Git 配置;后续 SHMEM 编译仍可并行。锁等待最多 600 秒,Git 失败会中止对应依赖目标。不依赖 CANN/NPU 的 Host 集成验证命令与范围见 cmake/tests/README.md。
✅环境自检
在实际编译或运行样例之前,建议先完成环境自检,确保开发环境已正确配置。在仓库根目录执行以下命令,脚本会自动逐项检查并给出提示:
python3 scripts/check_env.py
该脚本仅做检查和提示,不修改任何环境配置,也不会替代正式的构建流程。检查通过后再进入下一步的构建与运行。
⚡️快速入门
-
配置项目
NPU_ARCH为必填参数,用于指定目标 NPU 架构。当前支持的取值如下:NPU 平台 NPU_ARCH Ascend950 dav-3510Ascend910B/C dav-2201以 Ascend950 为例,使用以下命令初始化构建配置,CMake 会自动创建
build目录:cmake -S . -B build -DNPU_ARCH=dav-3510在 Ascend910B/C 平台构建时,请使用
-DNPU_ARCH=dav-2201。不支持当前架构的样例会在配置阶段跳过,因此target help和后续构建只包含当前架构生效的样例。 -
查看可用 Target(可选)
编译前可先查看当前项目中支持单独构建的目标列表:
cmake --build build --target help -
编译与安装
-
选项 A:编译指定 Target(部分构建)
将
<target_name>替换为上一步查到的目标名称:cmake --build build --target <target_name> -
选项 B:编译所有 Target(推荐,全量构建)
支持多线程加速构建:
cmake --build build --parallel安装编译产物,将生成的二进制文件整理到
build_out目录:cmake --install build --prefix ./build_out
-
-
运行验证
-
选项A: 运行指定的Target(以vector_add为例)
上一步将
<target_name>替换为vector_add编译成功后,编译输出二进制文件在./build/Samples/0_Introduction/vector_add/目录下,即编译产物在第一步构建的build文件夹下与样例目录对应的位置,执行如下命令运行:./build/Samples/0_Introduction/vector_add/vector_add可以得到结果如下:
Vector add completed successfully! -
选项B: 运行全量编译并安装后的matmul用例
完成第三步的安装后,所有编译生成文件都在
build_out文件夹下,matmul用例的可运行文件在./build_out/0_Introduction/matmul目录下,执行如下命令运行:cd ./build_out/0_Introduction/matmul/ ./matmul 100 50 200运行成功后,终端将打印如下类似信息:
Data generated successfully! [verify] shape(100, 200), elements=20000 - summary (large matrix, full tensors omitted) abs_err: max=0.000000e+00, mean=0.000000e-00, rmse=0.000000e+00 rel_err: max=0.000000e+00 count(|abs_err| > 0.001): 0 / 20000 cpu golden (top-left 4x4): tensor([[1144., 1088., 1012., 1040.], [1104., 1072., 1004., 972.], [1056., 968., 888., 984.], [1012., 932., 876., 912.]], dtype=torch.bfloat16) npu out (top-left 4x4): tensor([[1144., 1088., 1012., 1040.], [1104., 1072., 1004., 972.], [1056., 968., 888., 984.], [1012., 932., 876., 912.]], dtype=torch.bfloat16) max abs diff: 0.0 point error count(>0.1): 0/20000 ratio error count(>0.001): 0/20000, error ratio: 0.000000 [PASS] NPU results are consistent with CPU.开发者可自行尝试运行
build_out下的其它用例。
-
📂目录结构
├── Samples # 样例目录
│ ├── 0_Introduction # 入门样例
│ │ ├── 01_simd_cpp_api # SIMD C++ API 入门样例
│ │ ├── 02_simd_c_api # SIMD C API 入门样例
│ │ ├── 03_simt_api # SIMT API 入门样例
│ │ ├── 04_aicpu # AI CPU 算子入门样例
│ │ ├── 05_simd_simt_hybrid # SIMD/SIMT 混合编程入门样例
│ │ ├── 99_system # CANN组件样例
│ │ ├── matmul # Tensor API 矩阵乘入门样例
│ │ ├── npu_execution # NPU 算子执行链路概念文档
│ │ ├── vector_add # TQue / TPipe 向量加法入门样例
│ │ ├── vector_add_c_api # C API 向量加法入门样例
│ │ ├── vector_function_add # RegBase VF 向量加法入门样例
│ │ └── vector_function_getting_started # RegBase VF 编程模型入门文档
│ ├── 1_Features # 功能特性样例
│ │ ├── memory_optimization # 访存优化方法
│ │ ├── instruction_optimization # 指令优化方法
│ │ ├── system_optimization # 系统优化方法
│ │ └── hardware_features # 芯片特性样例
│ ├── 2_Performance # 性能调优样例
│ │ ├── matmul_story # 矩阵乘性能优化实践
│ │ ├── grouped_matmul_story # 分组矩阵乘性能优化实践
│ │ └── ... # 其它性能调优样例
│ ├── 3_Utilities # 开发工具集
│ │ └── simulation-based-vf-profiling # 基于 npusim 的 VF 性能分析
│ └── CMakeLists.txt
├── third_party # 外部依赖(Git 子模块)
│ ├── asc-devkit # asc-devkit:Ascend C Tensor API 头文件
│ ├── shmem # 共享内存相关组件
│ └── ... # 其它第三方依赖
├── cmake # 工程编译配置
├── scripts # 环境检查等辅助脚本
│ └── check_env.py # 构建前环境自检脚本
├── tests # 测试目录
├── .clang-format # 代码格式配置
├── CMakeLists.txt # 根 CMake 配置
├── CONTRIBUTING.md # 贡献指南
├── LICENSE # 许可证
├── requirements.txt # Python 依赖
├── SECURITY.md # 安全声明
└── README.md # 项目说明文档
💬相关信息
🤝联系我们
本项目的功能与文档会持续更新。
- 问题反馈:通过 GitCode Issues 提交问题
- 社区互动:通过 GitCode Discussions 参与交流
Made with ❤️ by the CANN Team · More CANN Projects