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.run
• Ascend-cann-toolkit_${cann_version}_linux-x86_64.run

1. 安装社区版 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 目录。

2. 配置环境变量

   安装完成后，请先执行：

   source ${install_path}/ascend-toolkit/set_env.sh
   

   请将 ${install_path} 替换为 toolkit 的实际安装目录，例如 /usr/local/Ascend 或 ${HOME}/Ascend。

3. 前置依赖

   编译用到的依赖如下，请确保已安装并且满足版本要求：

   • cmake >= 3.16.0
   • python >= 3.8.0
   • zip
   • git
   • python三方库依赖：通过pip3 install -r requirements.txt安装

4. ops-tensor子模块与Toolkit约束

   • 仓库与路径：子模块路径为third_party/ops-tensor，对应上游仓库ops-tensor（默认跟踪master，见仓库根目录.gitmodules）。
   • 获取源码：克隆本仓库时建议执行 git clone --recurse-submodules <仓库 URL>；若已克隆未带子模块，在仓库根目录执行：

     git submodule update --init --recursive third_party/ops-tensor
     

     若未提前初始化子模块，CMake在构建依赖cann_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

该脚本仅做检查和提示，不修改任何环境配置，也不会替代正式的构建流程。检查通过后再进入下一步的构建与运行。

---

⚡️快速入门

1. 配置项目

   NPU_ARCH 为必填参数，用于指定目标 NPU 架构。当前支持的取值如下：

   NPU 平台	NPU_ARCH
   Ascend950	dav-3510
   Ascend910B/C	dav-2201

   以 Ascend950 为例，使用以下命令初始化构建配置，CMake 会自动创建 build 目录：

   cmake -S . -B build -DNPU_ARCH=dav-3510
   

   在 Ascend910B/C 平台构建时，请使用 -DNPU_ARCH=dav-2201。不支持当前架构的样例会在配置阶段跳过，因此 target help 和后续构建只包含当前架构生效的样例。

2. 查看可用 Target（可选）

   编译前可先查看当前项目中支持单独构建的目标列表：

   cmake --build build --target help
   

3. 编译与安装

   • 选项 A：编译指定 Target（部分构建）

     将 <target_name> 替换为上一步查到的目标名称：

     cmake --build build --target <target_name>
     

   • 选项 B：编译所有 Target（推荐，全量构建）

     支持多线程加速构建：

     cmake --build build --parallel
     

     安装编译产物，将生成的二进制文件整理到 build_out 目录：

     cmake --install build --prefix ./build_out
     

4. 运行验证

   • 选项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                                # 项目说明文档

💬相关信息

• 许可证
• 所属SIG

🤝联系我们

本项目的功能与文档会持续更新。

• 问题反馈：通过 GitCode Issues 提交问题
• 社区互动：通过 GitCode Discussions 参与交流

---

_{Made with ❤️ by the CANN Team · More CANN Projects}