CANN / hccl 仓库 RFC 编号登记机制与设计文档协作流程指南【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl本文围绕 HCCLHuawei Collective Communication Library开源仓库中 docs/en/rfcs/INDEX.md 所定义的RFC 编号登记机制展开系统讲解该仓库如何通过独立取号 文档评审两步式流程管理技术方案设计文档RFC包括编号分配规则、状态机、RFC 生命周期与模板要求并结合仓库内已合入的 0001/0002/0003 号 RFC 实例与对应源码落地路径帮助贡献者快速掌握从提需求到 RFC 合入再到代码实现的完整协作方法。一、RFC 文档目录与命名规范HCCL 仓库将所有技术方案设计文档统一存放在 docs/en/rfcs/英文与 docs/zh/rfcs/中文目录下。这些文档用于在编码实现之前对齐方案、沉淀设计决策属于 Request for CommentsRFC性质的治理资产。目录由三类文件组成0000-template.mdRFC 编写模板规定一篇 RFC 必须包含的章节骨架INDEX.mdRFC 编号登记表列出所有已分配的 RFC 编号及其状态NNNN-xxx-xxx.mdRFC 文档本体文件名由 4 位编号加简短描述组成。命名规则见 docs/en/rfcs/README.md{4位编号}-{简短描述}.md例如0001-add-new-feature.md。其中编号为 4 位零填充0001–9999描述部分要求英文小写、连字符分隔、简洁明确。当前仓库中三个已合入 RFC 的命名如下文件编号主题0001-add-batch-invariant-reducescatter.md0001BIRSBatchsize Invariant ReduceScatter算法0002-HCCL-ALGO-Plugin.md0002HCCL 自定义算法扩展框架0003-executor-template-refactor.md0003集合通信 Executor 统一算法结构重构二、编号登记机制独立取号与 RFC 文档创建解耦INDEX.md 的核心设计是取号与文档撰写两步解耦先通过一个轻量的 PR 锁定编号再在后续独立的 PR 中提交 RFC 文档。这一机制保证了编号分配的确定性避免两个贡献者同时撰写同名/同号 RFC 造成冲突。完整的取号流程如下查看已分配编号表找出最小未使用的编号 N通常为最后一行编号 1在表中追加一行登记编号 N状态填reserved标题、作者可以先填占位提交取号 PR——该 PR 仅包含 INDEX.md 中的一行更新取号 PR 合入后编号 N 被正式占用状态保持reserved此时方可开始撰写 RFC 文档RFC 文档NNNN-xxx-xxx.md通过后续独立 PR提交RFC 文档 PR 合入后状态更新为accepted整个 RFC 正式生效。该机制在 docs/zh/rfcs/INDEX.md 中有完全一致的中文定义供中文贡献者对照使用。取号 PR 与 RFC 文档 PR 的重量差异轻量/重量正是为了鼓励贡献者尽早占号、充分讨论同时将评审火力集中在真正的方案内容上。三、编号状态机reserved → accepted → supersededINDEX.md 定义了三种编号状态构成 RFC 从占位到生效再到被替代的完整生命周期状态含义reserved编号已占位取号 PR 已合入RFC 文档待提交或评审中acceptedRFC 文档 PR 已合入整个 RFC 正式生效superseded被后续 RFC 替代需查看原文档末尾的Superseded by标注其中reserved与accepted的转换发生在RFC 文档 PR 合入这一事件上accepted与superseded的转换则发生在后续 RFC 替代本方案时详见第六节。四、编号分配规则INDEX.md 对编号的分配施加了五条硬性约束确保登记表长期稳定可追溯格式4 位零填充0001–9999永不重用已合入的编号即使 RFC 被后续 RFC 替代也不回收顺序分配原则上不跳号下一个编号 最大已用编号 1替代关系原 RFC 文档末尾标注 Superseded by 00NNINDEX.md 状态列同步改为superseded冲突解决若两人同时领取同一编号后者需 rebase 后改为新的最小编号。前两条规则共同保证了编号 永久身份标识任何一篇 RFC 无论最终是否生效其编号都不会被复用避免历史文档引用关系被破坏。五、已分配编号登记表当前状态截至当前仓库内容INDEX.md 的已分配编号表登记情况如下编号标题作者状态PR0001BIRS (Batchsize Invariant ReduceScatter) for A3Davydov_DanilacceptedMR 1440后续新增 RFC 时贡献者须在此表追加新行字段包括编号、标题、作者、状态与关联 PR。仓库中 0002、0003 两篇 RFC 文档已经落地对应文档已合入贡献者在取号时应以 INDEX.md 表中实际登记的最大编号为准。六、RFC 生命周期从需求到实现合约RFC 的完整生命周期定义于 docs/en/rfcs/README.md与编号状态机相互衔接共分七个阶段需求阶段在 Issue 中按 Requirement 类型提交需求等待 SIG 组接纳取号 PR在 INDEX.md 中追加一行占位登记状态reserved提交取号 PR取号 PR 合入编号被占用开始撰写 RFC编写阶段按 0000-template.md 撰写系统方案评审阶段通过 RFC 文档 PR 提交评审过程中根据评审意见修改方案决策阶段合入Maintainer 评审通过添加/lgtm与/approve后合入并将 INDEX.md 中该行状态改为accepted关闭评审未通过则关闭 PR编号仍保留reserved且不回收作者可以重新启动评审流程实施阶段合入的 RFC 作为实现合约后续代码 PR 必须遵循 RFC 方案。需要特别强调的是第 7 阶段——RFC 合入后并非终点而是实现工作的起点。RFC 中定义的架构、接口与算法约束对后续代码提交具有约束力这正是文档驱动开发在该仓库中的落地形态。七、RFC 模板一篇合格 RFC 的章节骨架0000-template.md 规定了 RFC 文档必须包含的元信息与章节结构。文档开头需填写三行元信息Start Date开始日期YYYY-MM-DD 格式RFC PR Number关联的 RFC PR 编号Related Issue关联的需求 Issue 编号。正文章节骨架如下章节要求Summary做什么 为什么这样做评审者应在 30 秒内掌握核心决策及其理由Background and Motivation展开问题与场景为何需要、解决什么问题、预期用例Terminology对齐关键术语跨模块/跨仓 RFC 必填单模块可省略Architecture and Interface Contract总体架构图、模块职责、运行时序、外部接口与依赖接口Impact Analysis性能影响、现有功能影响范围、构建/依赖/发布影响Compatibility Considerations向后兼容性、是否需要特性开关、分阶段发布策略Detailed Design模块内部实现按模块组织含核心数据结构、关键逻辑、内部接口Algorithm Design涉及核心算法时填写原理、复杂度分析、正确性论证Test PlanUT/ST/上板测试方案验证功能正确性与兼容性Risk Assessment潜在风险点与缓解措施Alternative Solutions考虑过的其他方案及其优劣Open Issues设计阶段未决或需进一步讨论的问题从已合入的 RFC 看模板执行情况良好例如 0001-add-batch-invariant-reducescatter.md 完整覆盖了背景动机、详细设计、兼容性、测试计划、风险评估与开放问题0002-HCCL-ALGO-Plugin.md 在此基础上补充了接口契约的完整代码定义0003-executor-template-refactor.md 则额外增加了 Glossary术语表与替代方案Alternatives的对比论证。八、从编号到实现三份已合入 RFC 的落地案例为了更直观地展示取号 → 文档 → 实现的完整闭环以下结合仓库源码梳理三份 RFC 各自对应的落地位置。这些实现路径同时也是贡献者理解 RFC 编号登记机制价值的窗口——每个编号背后都对应着真实的代码变更与设计约束。8.1 RFC 0001BIRS 批量不变 ReduceScatter 算法0001 号 RFC 提出 BIRSBatchsize Invariant ReduceScatter算法面向 A3 服务器 SIO HCCS 混合互联拓扑在保证确定性归约顺序逐位可复现的同时提升大消息场景带宽利用率。该 RFC 明确了两个特性开关编译期开关ENABLE_EXPERIMENTALCMake option默认 OFF开启后编译experimental/ops/子目录运行期环境变量HCCL_BIRS_ENABLETRUE将HcclReduceScatter调用路由到 BIRS 实现。其落地代码路径与 RFC 中描述的目录结构一致可在仓库中直接验证实验入口experimental/ops/reduce_scatter/reduce_scatter_op_experimental.ccBIRS 算法实现目录experimental/ops/reduce_scatter/birs/既有 ReduceScatter 实现被 BIRS 通过HCCL_BIRS_ENABLE分支旁路src/ops/reduce_scatter/实验公共基础设施experimental/ops/op_common/。8.2 RFC 0002HCCL-ALGO-Plugin 自定义算法扩展框架0002 号 RFC 设计了一套以动态库方式扩展 HCCL 算子算法的框架核心价值是让用户无需修改 HCCL 核心代码即可为 AllReduce、AllGather 等算子注入自定义算法解决旧机制下的代码侵入、构建耦合、发布依赖与选择逻辑封闭四大问题。框架由三部分构成Plugin ManagerHcclAlgoPluginMgr内嵌于 HCCL 仓库通过dlopen加载 PluginBroker 动态库并保存函数表指针PluginBroker 动态库libhccl_algo_PluginBroker.so独立于 HCCL 主库的桥接模块自动扫描算子目录并构建全局算法注册表自定义算法实现动态库由用户独立编译安装通过REGISTER_HCCL_ALGO宏注册算法条目。其源码落地路径可在仓库中确认src/algo_plugin/hccl_algo_plugin_mgr.ccManager 实现、src/algo_plugin/inc/hccl_algo_plugin_broker_api.hBroker 接口定义以及实验性配套生态 experimental/eco_system/algo_plugin/含 SDK、plugin_broker 与示例。该框架受 CMake 选项ENABLE_HCCL_ALGO_PLUGIN默认 OFF控制未配置HCCL_ALGO_PLUGIN_PATH时 HCCL 行为完全不变。8.3 RFC 0003Executor/Template 统一算法结构重构0003 号 RFC 提出以HcclAlgorithm静态算法描述OpsExecutor通用解释器Template单层执行单元CommPlanner通信计划生成器四层结构重构 HCCL 的算法组织方式将 53 个专用 Executor 合并为 1 个通用执行器使3 级拓扑扩展到 4 级拓扑从每算子新增 2–3 个 Executor 类约 1000 行简化为算法表追加 1 个叶子节点约 10 行。该重构以零侵入插件方式落地于 experimental/ops/op_common/recursive_executor/算法描述结构inc/algo_desc.hHcclAlgorithm/AlgoExecDesc/TemplateExecDesc桥接层executor/adaptor_executor.h继承 src 的InsCollAlgBase通过REGISTER_ALG注册通用执行器executor/ops_executor.cc算法注册表selector/alg_selector.h模板与通信计划template/aicpu/ 与 template/comm_planners/4 级拓扑匹配器topo/topo_match_four_level.h。该 RFC 还定义了运行期开关HCCL_EXPERIMENTAL_RECURSIVE_EXECUTORtrue配合编译期常量默认关闭并规划了test/ut/recursive_executor/下的四组 UTomnipipe_utils、data_ops、comm_planner、algo_desc其中algo_desc组已有对应实现test/ut/recursive_executor/algo_desc_test.cc其余三组按 RFC 说明待补齐。九、替代Superseded流程当一个 RFC 的实现被后续 RFC 替代时需要同步执行三个动作以保持登记表与文档的一致性在被替代的 RFC 文档末尾追加标注 Superseded by 00NN将 INDEX.md 中该行状态从accepted改为superseded不修改原编号。这样既保留了被替代文档的可追溯性读者可通过标注跳转到新方案又遵循了编号永不重用的原则。截至当前仓库状态三篇 RFC 均处于accepted状态尚无 superseded 记录但该机制已完整定义并随时可用。十、贡献者实操路径总结综合以上机制一名贡献者从产生想法到方案落地的完整路径为阅读 CONTRIBUTING_en.md或中文版 CONTRIBUTING.md了解总体贡献规范查看 INDEX.md 确认当前最大已用编号领取最小未使用编号提交仅含一行 INDEX.md 更新的取号 PR合入后编号即被锁定状态reserved依据 0000-template.md 撰写 RFC 文档提交文档 PR进入评审评审通过Maintainer 添加/lgtm与/approve并合入后将 INDEX.md 状态更新为accepted后续代码 PR 严格遵循 RFC 方案实现RFC 即成为实现合约。从仓库现状看该机制已在三篇 RFC 上完成闭环验证0001BIRS对应 experimental/ops/reduce_scatter/birs/ 实现0002ALGO-Plugin对应 src/algo_plugin/ 实现0003Executor 重构对应 experimental/ops/op_common/recursive_executor/ 实现。新的贡献者完全可以参照这三个案例在保持编号登记表、文档与代码三方一致的前提下安全地加入自己的技术方案。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考