算子领域高性能实战演进样例与体系化调优知识库

文件	最后提交记录	最后更新时间
.ci	支持通过 NPU_ARCH 配置样例编译架构	1 个月前
.gitcode	docs: 添加 GitCode Issue 和 PR 模板配置	3 个月前
Samples	refactor: 简化 Reg 数据搬运选型指南行文，统一 VL 计算，移除 ScaleB NZ 示例	1 天前
cmake	Add MXFP8FP4 weight quant matmul sample	9 天前
tests	test: add minimal functional CI runner and manifest	2 个月前
third_party	hifloat8 recipe	24 天前
.clang-format	init commit	4 个月前
.gitignore	add performance mxfp4 tiling	2 个月前
.gitmodules	submodule引入tensorapi源码并适配所有sample	1 个月前
CMakeLists.txt	支持通过 NPU_ARCH 配置样例编译架构	1 个月前
CONTRIBUTING.md	支持通过 NPU_ARCH 配置样例编译架构	1 个月前
LICENSE	init commit	4 个月前
OAT.xml	规范化OAT.xml中许可证声明形式	2 个月前
README.md	docs: update verified CANN Toolkit versions with 9.1.0 support	24 天前
SECURITY.md	init commit	4 个月前
Third_Party_Open_Source_Software_List.yaml	init commit	4 个月前
Third_Party_Open_Source_Software_Notice	init commit	4 个月前
requirements.txt	Clean up MXFP4 timing and verification flows	2 个月前

cann-samples

🔥Latest News

[2026/05] ops-samples在matmul_story新增matmul_a16w16 streamK等高性能example，并在既有quant_matmul_mxfp4、quant_matmul_mxfp8 MX量化矩阵乘中支持Weight NZ。
[2026/05] ops-samples在grouped_matmul_story新增weight_quant_grouped_matmul_mxfp8fp4 MXA8W4量化example，并在既有quant_grouped_matmul_mxfp4、quant_grouped_matmul_mxfp8分组矩阵乘中支持Weight NZ。
[2026/04] ops-samples新增matmul_story、grouped_matmul_story：matmul_story提供MX矩阵乘分步教程（matmul_tutorials）与matmul_recipes高性能算子样例（MXFP4/MXFP8/A16W16等）；grouped_matmul_story提供分组矩阵乘grouped_matmul_recipes样例（MXFP4/MXFP8）及配套性能文档。
[2026/04] ops-samples中矩阵乘类example更新，引入ops-tensor子模块，涉及兼容性，详见兼容性声明。
[2026/03] ops-samples更名为cann-samples。
[2026/02] ops-samples项目上线，提供算子领域高性能实战演进样例与体系化调优知识库。

🚀概述

cann-samples 是 CANN（Compute Architecture for Neural Networks）算子领域的实战样例仓库，提供高性能实现示例与体系化调优知识库。

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

📝环境部署

当前仓库已验证通过的社区版 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 安装包。

兼容性声明

ops-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

安装社区版 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
ops-tensor子模块与Toolkit约束
- 仓库与路径：子模块路径为third_party/tensor_api，对应上游仓库ops-tensor（默认跟踪master，见仓库根目录.gitmodules）。
- 获取源码：克隆本仓库时建议执行 git clone --recurse-submodules <仓库 URL>；若已克隆未带子模块，在仓库根目录执行：
```
git submodule update --init --recursive third_party/tensor_api
```
  若未提前初始化子模块，CMake在构建依赖cann_samples::tensor_api的目标时也会尝试执行上述子模块更新命令。
- Toolkit要求：Tensor API相关样例会使用third_party/tensor_api/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全量配置工程时，这两项样例会被跳过，属预期行为。

⚡️快速入门

配置项目

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 和后续构建只包含当前架构生效的样例。
查看可用 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目录下，执行如下命令运行：
```
./build_out/0_Introduction/matmul/matmul 100 50 200
```
  可以得到结果如下：
```
matmul run successfully!
```
  开发者可自行尝试运行build_out下的其它用例。

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

📂目录结构

├── Samples                                  # 样例目录
│   ├── 0_Introduction                       # 入门样例
│   ├── 1_Features                           # 功能特性样例
│   │   ├── memory_optimization              # 访存优化方法
│   │   ├── instruction_optimization         # 指令优化方法
│   │   ├── system_optimization              # 系统优化方法
│   │   └── hardware_features                # 芯片特性样例
│   ├── 2_Performance                        # 性能调优样例
│   │   ├── matmul_story                     # 矩阵乘性能优化实践
│   │   ├── grouped_matmul_story             # 分组矩阵乘性能优化实践
│   │   └── ...                              # 其它性能调优样例
│   └── CMakeLists.txt
├── third_party                              # 外部依赖（Git 子模块）
│   ├── tensor_api                           # ops-tensor：Ascend C Tensor API 头文件
│   ├── shmem                                # 共享内存相关组件
│   └── ...                                  # 其它第三方依赖
├── cmake                                    # 工程编译配置
├── .clang-format                            # 代码格式配置
├── CMakeLists.txt                           # 根 CMake 配置
├── LICENSE                                  # 许可证
├── SECURITY.md                              # 安全声明
└── README.md                                # 项目说明文档