算子领域高性能实战演进样例与体系化调优知识库
CANN-SAMPLES
昇腾 CANN 算子领域的实战样例仓库
提供高性能实现示例与体系化调优知识库，从入门概念到极致性能，覆盖 MatMul、MoE、Attention 等核心算子的完整优化链路
📖 概述 · 🔥 最新动态 · 🛠️ 环境部署 · ✅ 环境自检 · 🚀 快速入门 · 📦 样例列表 · 💬 社区讨论
🚀概述
cann-samples 是 CANN（Compute Architecture for Neural Networks）算子领域的实战样例仓库，提供高性能实现示例与体系化调优知识库。
本仓已集成代码仓库智能体，点击 徽章，进入其专属页面，开启在线智能代码学习与知识问答体验！
🗺️ 用户导航
| 你是... | 推荐入口 | 预计耗时 |
|---|---|---|
| 👋 NPU 算子初学者 | 入门样例 → add / matmul 建立基本概念 |
30 min |
| 🏗️ 自有环境部署 | 环境部署 → 环境自检 → 快速入门 编译运行第一个样例 | 20 min |
| 🧠 NPU 新特性掌握 | 特性列表 → 探索芯片功能特性与优化方法 | 按需 |
| 🚀 追求极致性能 | 样例列表 → 按算子类型查找调优实践 | 按需 |
| 🔧 调试与性能分析 | 工具集 → 使用辅助工具分析算子性能瓶颈 | 按需 |
| ✨ 贡献代码 | 所属 SIG | 15 min |
为什么使用 cann-samples
| 维度 | 说明 |
|---|---|
| ⚡ 体系化调优知识库 | 从入门概念到极致性能，覆盖 MatMul、MoE、Attention 等核心算子的完整优化链路 |
| 🔬 端到端可复现 | 每个 story 提供 baseline→优化分步教程与可运行 recipe，配合 cannsim trace 量化性能差异 |
| 🧠 硬件特性深挖 | 直击 ScalarBound、流水线排布、寄存器 Spill、SIMT / SIMD VF 编程等底层优化点 |
| 🧩 多数据类型覆盖 | 支持 BF16 / FP16 / HiFloat8 / MXFP4 / MXFP8 等多种精度与量化方案 |
| 🎯 多代际硬件适配 | 覆盖 Ascend 950（dav-3510）与 Ascend 910B/C（dav-2201）平台 |
🔥最新动态
- [2026/05] cann-samples在matmul_story新增matmul_a16w16 streamK等高性能example，并在既有quant_matmul_mxfp4、quant_matmul_mxfp8 MX量化矩阵乘中支持Weight NZ。
- [2026/05] cann-samples在grouped_matmul_story新增weight_quant_grouped_matmul_mxfp8fp4 MXA8W4量化example，并在既有quant_grouped_matmul_mxfp4、quant_grouped_matmul_mxfp8分组矩阵乘中支持Weight NZ。
📝环境部署
当前仓库已验证通过的社区版 CANN Toolkit 如下：
| CANN 版本 | 时间戳 | 验证结果 | 下载链接 |
|---|---|---|---|
9.1.0 |
20260513000324948 |
✅ PASS | aarch64 / x86_64 |
9.1.0 |
20260508171052185 |
✅ PASS | aarch64 / x86_64 |
9.0.0 |
20260422000325096 |
✅ PASS | aarch64 / x86_64 |
请根据实际 CPU 架构，从上述链接目录中自行选择对应的 .run 安装包。
兼容性声明
cann-samples中矩阵乘类example更新，引入ops-tensor子模块。涉及Tensor API的样例需使用上表中已验证通过的 Toolkit 版本构建，并按下文ops-tensor子模块与Toolkit约束初始化子模块、配置环境变量。
toolkit 安装包文件名格式如下：
Ascend-cann-toolkit_${cann_version}_linux-aarch64.runAscend-cann-toolkit_${cann_version}_linux-x86_64.run
-
安装社区版 CANN Toolkit
# 确保安装包具有可执行权限 chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run # 安装命令 ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --force --install-path=${install_path}${cann_version}：表示 toolkit 安装包版本号，需满足上文的最低版本要求。${arch}：表示 CPU 架构，如aarch64、x86_64。${install_path}：表示指定安装路径，默认安装在/usr/local/Ascend目录。
-
配置环境变量
安装完成后，请先执行：
source ${install_path}/ascend-toolkit/set_env.sh请将
${install_path}替换为 toolkit 的实际安装目录，例如/usr/local/Ascend或${HOME}/Ascend。 -
前置依赖
编译用到的依赖如下，请确保已安装并且满足版本要求：
- cmake >= 3.16.0
- python >= 3.8.0
- zip
- git
- python三方库依赖：通过
pip3 install -r requirements.txt安装
-
ops-tensor子模块与Toolkit约束
- 仓库与路径：子模块路径为
third_party/ops-tensor，对应上游仓库ops-tensor（默认跟踪master，见仓库根目录.gitmodules）。 - 获取源码：克隆本仓库时建议执行
git clone --recurse-submodules <仓库 URL>；若已克隆未带子模块，在仓库根目录执行：
若未提前初始化子模块，CMake在构建依赖git submodule update --init --recursive third_party/ops-tensorcann_samples::tensor_api的目标时也会尝试执行上述子模块更新命令。 - Toolkit要求：Tensor API相关样例会使用
third_party/ops-tensor/include/tensor_api以及Toolkit中的Ascend C头文件，因此必须安装完整的CANN Toolkit并先执行source ${install_path}/ascend-toolkit/set_env.sh。当前请使用上表中已验证通过的版本构建；Toolkit版本过旧、仅安装Run包或环境变量未生效时，可能出现头文件缺失、符号未定义或编译选项报错。 - NPU架构：
matmul_story、grouped_matmul_story额外要求NPU_ARCH=dav-3510（Ascend 950）；使用dav-2201全量配置工程时，这两项样例会被跳过，属预期行为。
- 仓库与路径：子模块路径为
✅环境自检
在实际编译或运行样例之前，建议先完成环境自检，确保开发环境已正确配置。在仓库根目录执行以下命令，脚本会自动逐项检查并给出提示：
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 # 入门样例
│ ├── 1_Features # 功能特性样例
│ │ ├── memory_optimization # 访存优化方法
│ │ ├── instruction_optimization # 指令优化方法
│ │ ├── system_optimization # 系统优化方法
│ │ └── hardware_features # 芯片特性样例
│ ├── 2_Performance # 性能调优样例
│ │ ├── matmul_story # 矩阵乘性能优化实践
│ │ ├── grouped_matmul_story # 分组矩阵乘性能优化实践
│ │ └── ... # 其它性能调优样例
│ ├── 3_Utilities # 开发工具集
│ │ └── simulation-based-vf-profiling # 基于 cannsim 的 VF 性能分析
│ └── CMakeLists.txt
├── third_party # 外部依赖（Git 子模块）
│ ├── ops-tensor # ops-tensor：Ascend C Tensor API 头文件
│ ├── shmem # 共享内存相关组件
│ └── ... # 其它第三方依赖
├── cmake # 工程编译配置
├── scripts # 环境检查等辅助脚本
│ └── check_env.py # 构建前环境自检脚本
├── .clang-format # 代码格式配置
├── CMakeLists.txt # 根 CMake 配置
├── LICENSE # 许可证
├── SECURITY.md # 安全声明
└── README.md # 项目说明文档
💬相关信息
🤝联系我们
本项目的功能与文档会持续更新。
- 问题反馈：通过 GitCode Issues 提交问题
- 社区互动：通过 GitCode Discussions 参与交流
Made with ❤️ by the CANN Team · More CANN Projects