Thanks for sending an requirement! Please fill in the following template to help quickly solve your problem.

Backgroud（背景信息）

1. 概述

本需求文档描述 HCCL（Huawei Collective Communication Library）自定义算法扩展框架的功能需求和非功能需求。

核心目标：在不修改 HCCL 核心代码的前提下，支持用户以动态库形式添加自定义算法，使自定义算法能够无缝接入现有的算法选择和执行流程。

---

2. 背景与动机

2.1 业务场景

HCCL 算子仓包含多种算子（AllReduce、AllGather、Broadcast、Reduce 等），每个算子可包含多种算法实现。当前算法通过以下方式选择：

1. 拓扑感知选择：根据集群拓扑结构（1D Mesh、2D Mesh、CLOS 等）自动选择最适合的算法
2. 数据大小阈值：根据传输数据大小选择不同算法（如小数据用 OneShot，大数据用 TwoShot/NHR）
3. 硬件形态适配：950不同硬件形态需要不同算法实现

2.2 需求来源

当前存在以下场景需要扩展自定义算法：

场景	描述
新算法实现	用户希望添加自己设计的全新算法（如优化的 Ring、Tree 算法变体）
新硬件支持	支持新硬件形态或新拓扑结构，需要添加对应的算法实现
定制化优化	针对特定业务场景（如特定网络环境、特定数据模式）进行算法定制
实验性算法	在生产环境外验证新算法性能

2.3 当前限制

当前添加新算法存在以下限制：

1. 代码侵入：需要修改 HCCL 源码，添加注册代码
2. 构建耦合：新算法需要与 HCCL 源码一起编译
3. 发布依赖：算法更新需要重新编译和发布整个 HCCL
4. 选择逻辑封闭：新算法难以接入现有的算法选择流程

---

3. 功能需求

3.1 插件化算法加载

需求编号	需求描述	优先级
FR-001	系统支持通过配置文件指定动态库路径，加载用户自定义算法	必须
FR-002	系统启动时自动加载配置的动态库，调用库中的注册函数	必须
FR-003	支持同时加载多个动态库，多个自定义算法并存	必须
FR-004	动态库加载失败时（如文件不存在、符号解析失败），不影响主流程，返回明确错误日志	必须
FR-005	支持运行时卸载/重载动态库（可选）	期望

3.2 算法注册机制

需求编号	需求描述	优先级
FR-010	自定义算法需要提供元信息：算法名称、支持的算子类型、支持的拓扑类型	必须
FR-011	自定义算法需要实现评分函数，输入为精简上下文，输出为优先级分数	必须
FR-012	系统提供统一的注册中心，支持算法的注册和查询	必须
FR-013	支持同名算法的覆盖或拒绝（待定）	待讨论

3.3 算法选择流程

需求编号	需求描述	优先级
FR-020	自定义算法需要在现有算法选择流程中被评估	必须
FR-021	当多个自定义算法同时匹配时，选择优先级分数最高的算法	必须
FR-022	自定义算法分数相同时，按注册顺序选择	必须
FR-023	当没有自定义算法匹配时，回退到现有算法选择流程	必须
FR-024	支持通过环境变量或配置强制使用/禁用自定义算法	期望

3.4 算法执行流程

需求编号	需求描述	优先级
FR-030	自定义算法的执行器（Executor）实例由系统统一管理生命周期	必须
FR-031	自定义算法执行器需要继承现有基类或实现统一接口	必须
FR-032	自定义算法执行过程中的错误处理与现有算法保持一致	必须

---

4. 非功能需求

4.1 可用性需求

需求编号	需求描述
NFR-010	自定义算法加载失败时，提供清晰的错误日志
NFR-011	评分函数返回 -1 时，明确表示不适用当前场景
NFR-012	文档完整，包含接口说明、使用示例、配置说明

4.2 兼容性需求

需求编号	需求描述
NFR-020	不修改现有 HCCL 代码逻辑
NFR-021	不影响现有算法的选择和执行流程
NFR-022	无自定义算法时，HCCL 行为保持不变
NFR-023	接口设计考虑向前兼容，支持未来扩展

4.3 安全需求

需求编号	需求描述
NFR-030	动态库加载路径可配置，防止加载恶意库
NFR-031	动态库中的算法实现出现问题时，不导致 HCCL 进程崩溃

---

5. 用户使用场景

场景 1：添加新算法

1. 用户开发新的 AllReduce 算法实现（MyAllReduceAlgo）
2. 用户创建动态库 libmy_algo.so
3. 用户配置 HCCL_ALGO_PLUGINS=/path/to/libmy_algo.so
4. HCCL 启动时加载动态库，并自动注册算法和算法选择策略（评估策略）
5. 用户调用 HcclAllReduce() 时，系统评估自定义算法并可能选中

场景 2：支持新硬件

1. 硬件团队开发适配新硬件的算法
2. 打包为动态库
3. 配置加载
4. 拓扑检测到新硬件时，评分函数返回高分数
5. 自定义算法被选中执行

场景 3：禁用自定义算法

1. 用户设置 HCCL_ALGO_PLUGINS 为空或不设置
2. 系统不加载任何自定义动态库
3. HCCL 行为与原有完全一致

---

6. 约束条件

约束	描述
C-001	动态库接口需要使用 C ABI（extern "C"）
C-002	动态库中的 Executor 需要继承现有 InsCollAlgBase 基类
C-003	评分函数需要是确定性的（相同输入产生相同输出）
C-004	动态库需要与 HCCL 主库使用相同的编译工具链构建

Origin（信息来源）

自规划

Benefit / Necessity （价值/作用）

Design（设计方案）