CANN训练样例贡献指南

贡献指南

【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train

本项目欢迎广大开发者体验并参与贡献。在参与社区贡献之前，请参见cann-community了解行为准则、签署CLA协议，并熟悉源码仓的贡献流程。

开发者在准备本地代码与提交PR时，请重点关注以下几点：

1. PR描述：提交PR时，请按照模板仔细填写业务背景、目的、方案等信息。
2. 重大修改讨论：若涉及到新增特性、新增接口、新增配置参数或者修改代码流程等，请务必先通过Issue进行方案讨论，以避免您的代码被拒绝合入。若您不确定本次修改是否可被归为“简单的bug修复”，亦可通过提交Issue进行方案讨论。

开发者贡献场景主要包括：反馈BUG、建议特性、改进文档、修复问题、新增样例。

新增样例流程

感谢您参与样例建设！为了确保贡献顺畅，建议您遵循“RFC讨论 -> 代码开发 -> 提交PR”的流程：

1. 提交 RFC，达成方案共识

在正式开发前，建议先提交 Issue 进行 RFC（请求评议），包含：

• 背景与动机：解决什么场景需求，提供什么参考价值。
• 核心设计：技术思路、关键模块（模型选型、流程架构等）。
• 预期目标：核心功能、精度指标或性能表现。
• 排期：预计完成时间。

2. 开发规范（重点）

在开始编码前，请务必遵循以下目录结构与代码风格要求。

2.1 样例目录结构规范

样例代码以模型为单位组织（如qwen3）。

修改原则：

• 大修改（完整替换/Monkey Patch）：针对文件修改量大或逻辑复杂的情况，请在patches/<框架名>下复刻原仓目录结构，放置修改后的完整 Python 文件。
• 小修改（Git Patch）：针对少量代码修改（Bugfix/参数调整），请基于特性（Feature）粒度将多个文件修改合并为一个.patch文件，置于patches/<框架名>根目录下。
  • Patch 命名规范：编号-框架名-类型-特性名.patch（类型：feature或bugfix；特性名：全小写，下划线连接）
  • 示例：0001-verl-feature-enable_alltoall_overlap.patch

目录结构示例：

qwen3 # 样例名 ├── patches # 修改补丁总目录 │ ├── verl # 框架A (如 verl) │ │ ├── trainer # [大修改] 目录，对应原仓路径 │ │ │ └── verl_trainer_adaptor.py # 完整替换或Monkey Patch文件 │ │ ├── utils # [大修改] 目录，对应原仓路径 │ │ │ └── ... │ │ └── 0001-verl-feature-enable_alltoall_overlap.patch # [小修改] 特性粒度 patch │ └── vllm_ascend # 框架B(如vllm_ascend) │ └── ... ├── internal # 框架无关的内部文件 ├── Dockerfile # 环境部署文件 ├── prelude_patch.py # Monkey Patch 加载的入口文件（如有） ├── requirements.txt # 依赖库（需锁定版本） └── README.md # 说明文档

2.2 代码风格

请使用pre-commit工具确保代码满足基本规范，安装后会在 git commit 时自动检查：

pip install pre-commit pre-commit install

2.3 patch校验

请在项目根目录下（cann-recipes-train/）执行./ci/validate_all_projects.sh以验证patch文件命名规范，并确保项目能够基本构建。 基本构建包含以下步骤：

1. 下载样例所需的框架代码，如verl, vllm, vllm_ascend等。
2. 将框架代码复制到样例文件夹下，复刻原仓目录结构。
3. 依次用git apply应用所有patch，确保改动能够正确应用，没有冲突。

3. 提交 PR，完善交付内容

方案达成共识且代码开发完成后，请提交 PR 并关联 RFC Issue。PR 内容需包含：

• 样例代码：符合上述目录规范，并通过流水线 code check。
• 优化文档：说明功能适配、性能优化的重点（原因、方法、收益）。
• README文档：
  • 简述：核心内容（模型、设备、精度/性能数据）。
  • 操作步骤：详细的复现流程（从环境准备到执行）。

贡献注意事项

为了避免合入时的波折，请检查以下细节：

• 无二进制文件：除必要的文档配图外，代码库中不应包含二进制文件。
• 数据集：涉及第三方数据集时，仅在文档说明下载和使用方式，勿直接提交数据集。
• 公共代码验证：若修改涉及公共代码，需确保通过 CI 验证。
• 算子依赖：涉及算子新增或修改，请先合入算子仓，再推进样例合入。
• License 合规：检查使用的 License 是否合规（推荐 Apache 2.0 或 MIT），并正确标注版权。

如有任何疑问，欢迎在社区交流。再次感谢您的支持！

【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train