| name | op-samples-reference |
| description | CANN 算子高性能样例参考库。在架构设计、代码开发和性能优化阶段，从 cann-samples 仓库中检索相关样例代码与调优实践作为参考。触发：需要参考已有算子实现、查找优化方法示例、或学习特定编程模型时。 |
CANN 算子样例参考库
概述
本技能管理 cann-samples 仓库的本地副本，为算子开发各阶段提供高性能实战样例和调优知识库的参考。该仓库持续更新，包含算子领域的最佳实践、优化方法和完整代码示例。
仓库管理
初始化
首次使用时，将仓库克隆到 .agent/cann-samples：
git clone https://gitcode.com/cann/cann-samples.git .agent/cann-samples
更新
若本地副本已存在，拉取最新内容：
git -C .agent/cann-samples pull --rebase
每次使用前应检查是否需要更新，确保参考的是最新样例。
仓库结构
cann-samples/
├── Samples/
│ ├── 0_Introduction/ # 入门样例：NPU 执行链路、Vector/Cube 基本编程模型
│ ├── 1_Features/ # 特性样例：解耦底层优化能力
│ │ ├── memory_optimization/ # 访存优化（带宽利用、缓存策略、bank 冲突等）
│ │ ├── instruction_optimization/ # 指令优化（流水并行、多缓冲、权重格式等）
│ │ ├── system_optimization/ # 系统优化（负载均衡、多核调度等）
│ │ └── hardware_features/ # 芯片特性（SIMT、Vector Function、量化类型等）
│ ├── 2_Performance/ # 性能实战：从 Baseline 到极致性能的端到端调优
│ └── 3_Utilities/ # 工具类：仿真、Profiling 等辅助工具样例
├── third_party/ # 外部依赖（Git 子模块）
├── cmake/ # 编译配置
└── CMakeLists.txt # 根 CMake 配置
注意：以上为仓库的大致分类结构，具体包含哪些样例和子目录会随仓库更新而变化。使用时应直接进入对应目录查看当前可用的内容。
各阶段参考指引
阶段一：架构设计
在设计 Tiling 策略、Kernel 结构和 Host 流程时，参考样例中的架构模式：
- 入门编程模型 — 查看
Samples/0_Introduction/ 下的样例，了解 Vector Core 和 Cube Core 的基本 Tiling 策略、数据搬运模式和流水并行结构
- 同类算子实现 — 在
Samples/2_Performance/ 中查找与目标算子类型相近的样例（如矩阵乘类、归约类、通信类），参考其整体架构设计思路
- 优化策略选型 — 浏览
Samples/1_Features/ 各子目录的 README，了解可用的优化手段，在设计方案中提前规划可采用的优化策略
- SIMT 算子设计 — 若目标算子采用 SIMT 编程模型，必须参考
Samples/1_Features/hardware_features/simt/ 中的样例，了解 SIMT 架构下的 Tiling 策略、线程映射和 Kernel 结构设计
操作方式：进入 .agent/cann-samples/Samples/ 对应子目录，阅读 README.md 了解样例概述，再进入具体样例目录查看设计文档和源码。
阶段二：代码开发
在编写 Host/Kernel/Tiling 代码时，参考样例中的具体实现：
- API 用法 — 参考入门样例中的 Ascend C API 调用方式（数据搬运、计算指令、同步 barrier 等）
- Kernel 结构 — 参考性能样例中的 Kernel 实现，学习多缓冲（N-Buffer）、流水并行、分块策略等编程模式
- 芯片特性利用 — 查看
Samples/1_Features/hardware_features/ 中的样例，了解 Vector Function 等特定编程模型的代码写法
- SIMT 算子开发 — 若目标算子采用 SIMT 编程模型，必须参考
Samples/1_Features/hardware_features/simt/ 中的样例代码，学习 SIMT Kernel 的具体实现方式、线程索引计算、共享内存使用等
- 构建配置 — 参考样例中的 CMakeLists.txt 了解编译配置和依赖管理方式
操作方式：直接阅读 .agent/cann-samples/Samples/ 下目标样例的源码文件（.cpp/.h），关注 kernel 实现、tiling 数据结构和 host 侧调用逻辑。
阶段三：性能优化
在进行性能调优和瓶颈分析时，参考样例中的调优实践：
- 端到端调优路径 —
Samples/2_Performance/ 下的 story 类样例通常包含从 baseline 到极限性能的完整调优过程，包括性能分析文档、分步教程和可运行的 recipe 示例
- 访存瓶颈 — 参考
Samples/1_Features/memory_optimization/ 中的样例，学习带宽利用率优化、L1 缓存策略、bank 冲突消除等方法
- 指令效率 — 参考
Samples/1_Features/instruction_optimization/ 中的样例，学习流水并行度提升、指令预取、权重格式转换等方法
- 系统级优化 — 参考
Samples/1_Features/system_optimization/ 中的样例，学习多核负载均衡、尾轮优化等策略
- 性能分析工具 — 参考
Samples/3_Utilities/ 中的工具样例，学习 Profiling 和仿真分析方法
操作方式：优先阅读 Samples/2_Performance/ 下相关 story 目录中的 docs/ 文档和 README.md，理解调优思路，再对照代码实现学习具体优化手法。
检索策略
当需要查找参考时，按以下顺序检索：
- 先读目录索引 — 从
Samples/ 根目录开始，逐级阅读 README.md 定位相关样例
- 再读样例文档 — 进入目标样例目录，阅读其 README.md 和 docs/ 下的文档
- 最后读源码 — 根据文档指引查看具体的
.cpp/.h 源码文件
仓库内容持续更新，若在某个分类下未找到相关参考，应检查仓库是否有新增目录或样例。也可查看仓库根目录 README.md 的 Latest News 了解最近新增的内容。
注意事项
- 仓库中的样例可能依赖特定版本的 CANN Toolkit 和 NPU 架构，参考时注意查看样例 README 中的环境要求
- 部分样例使用
third_party/tensor_api 子模块提供的 Tensor API，参考时需确认子模块已初始化
- 样例代码的风格和规范可能与 ops-blas 项目不完全一致，参考时应以 ops-blas 自身的编码规范（
blas-ascendc-coding-rules）为准
