cann-samples:基于 CANN 的算子高性能实战样例与调优知识库项目

CANN高性能实战演进样例与体系化调优知识库

Branch3Tags0
FilesLast commitLast 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 及以上版本。

License Perf Stories CANN Zread

📖 概述 · 🔥 最新动态 · 🛠️ 环境部署 · ✅ 环境自检 · 🚀 快速入门 · 📦 目录结构 · 💬 社区讨论


🚀概述

cann-samples 是 CANN(Compute Architecture for Neural Networks)实战样例仓库,提供高性能实现示例与体系化调优知识库。

本仓已集成代码仓库智能体,点击 Zread 徽章,进入其专属页面,开启在线智能代码学习与知识问答体验!

本仓为 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)平台

🔥最新动态


📝环境部署

请依次完成 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

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


⚡️快速入门

  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                       # 入门样例
│   │   ├── 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

Introduction

CANN高性能实战演进样例与体系化调优知识库

https://gitcode.com/cann/cann-samplesCustomize your domain