如何向CANN ops-math开源社区贡献你的第一个自定义算子：experimental目录到PR全流程

如何向CANN ops-math开源社区贡献你的第一个自定义算子：experimental目录到PR全流程

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math

CANN ops-math 是昇腾 NPU 数学类基础计算算子库，涵盖张量形态变换（conversion）、数学运算（math）、随机数生成（random）等类别，让网络在 NPU 上加速计算。本文面向新手，手把手带你走完自定义算子开源贡献全流程：从创建 Issue、在experimental目录开发验证算子，到提交 PR、通过 CI 门禁直至合入。全程约 5 个关键步骤，读完即可动手。

为什么选择 ops-math 的 experimental 目录起步？

对于第一次贡献算子的开发者，官方推荐的起点是experimental（用户自定义算子）目录，原因有三：

experimental 目录当前包含三个分类子目录，详见 docs/zh/install/dir_structure.md：

experimental ├── conversion # 用户开发的 conversion 类算子 ├── math # 用户开发的 math 类算子 └── random # 用户开发的 random 类算子

一图看懂：算子贡献全流程

完整的贡献过程共 6 个环节（详见 CONTRIBUTING.md）：

1. 创建 Issue 需求→ 提出算子想法与设计方案
2. 需求评审→ 申报 Ops-basic SIG 议题，评审通过后获得贡献目录
3. 本地开发→ 在 experimental 对应分类目录实现并验证算子
4. PR 提交→ 按交付件要求向目标分支提交 PR
5. CI 门禁→ 触发 compile 指令，通过编译、静态检查、UT、冒烟测试
6. 检视合入→ Committer 检视（/lgtm）→ Maintainer 最终审核（/approve）合入

第一步：创建 Issue 提出算子需求

⚠️关键提醒：若你的修改属于新增特性、新增接口等非简单 bug 修复，务必先通过 Issue 讨论方案，否则代码可能被拒绝合入。

新建一个Requirement|需求建议类 Issue，内容建议包含：

• 背景信息：算子要解决什么问题，来自哪个框架或模型场景
• 价值/作用：为什么社区需要这个算子
• 设计方案：输入输出定义、数据流、Kernel 实现思路

创建后需申报 SIG 议题并参加 Ops-basic SIG 评审；需求紧急时可联系 Maintainer 申请临时评审。评审通过后，SIG 成员会为你分配具体的贡献目录（例如experimental/math）。

第二步：本地开发你的第一个自定义算子

1. 准备环境与源码

先完成 NPU 驱动、CANN 包安装等环境部署，然后下载与 CANN 版本配套的分支源码（注意：master 分支可能存在版本不匹配风险）：

# ${tag_version} 替换为分支标签名，例如 9.0.0 git clone -b ${tag_version} https://gitcode.com/cann/ops-math.git && cd ops-math

2. 按最简交付件搭建算子目录

生态算子的交付件结构非常轻量，在experimental/${op_class}下按如下规则放置文件：

${op_class} # 算子分类，如 math ├── ${op_name} # 算子名目录 │ ├── ${op_name}.cpp # 算子 Kernel 实现文件 │ ├── tests │ │ └── test_${op_name}.py # 算子测试文件 │ ├── CMakeLists.txt # 算子编译配置文件 │ └── README.md # 算子 README 文档（必选）

3. 编译验证：先跑通示例算子再上手

建议先按快速入门指南编译运行add_example示例算子，验证环境闭环（编译 → 安装 → 运行样例）：

bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16

确认环境正常后，替换为你的算子名即可按同样流程编译、安装、验证。如果你偏好 PyTorch Extension 方式开发（单文件完成算子 + 框架适配、用<<<>>>语法启动核函数），可参考轻量级高性能工程模板 examples/fast_kernel_launch_example/README.md。

第三步：提交 PR 并通关 CI 门禁

提交前合规自检清单

• 代码符合《C++ 编程规范》
• 本地编译通过
• 算子满足精度标准（生态算子开源精度标准）
• README 文档语法规范
• 已签署 CLA 协议
• PR 标题清晰、描述指明更改内容和原因，并关联对应 Issue

CI 门禁：一条命令触发

PR 提交后，通过评论compile指令触发开源仓门禁，检查项包括：

1. 代码编译
2. 静态检查（codecheck 误报请提交给 SIG 成员屏蔽）
3. UT 测试
4. 冒烟测试

门禁全部通过后，在关联的 Issue 中 @ Committer 进入人工环节。

第四步：检视与合入

• Committer 检视：反馈检视意见，按意见修改后再次 @ Committer
• Maintainer 合入：Committer 通过后标注/lgtm，Maintainer 最终审核无问题后标注/approve合入 PR 🎉

至此，你的第一个自定义算子正式进入 CANN ops-math 开源仓库。

新手常见坑位速查

延伸阅读

• 快速入门：编译、开发、调试、验证全闭环
• 贡献指南：五大贡献场景详解
• 项目目录结构：standard 算子完整交付件参考
• Fast Kernel Launch：单文件高性能算子开发模板

完成第一个算子只是开始——项目同样欢迎 Bug 修复、算子优化和文档纠错类贡献，欢迎在 Issue 与讨论区参与交流，一起把 NPU 算子生态做得更好！

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math