RFC-需求串讲模板

背景

特性在进入代码开发前，需要把问题背景、目标边界、对外接口、方案设计、组件依赖、兼容性约束和验证方式讲清楚。

建议落地方式

填写原则：

• checklist 代表需要覆盖的信息维度，不限制必须用列表呈现。
• 接口、方案、依赖、约束和验证标准须能支撑代码评审和验收。
• 流程图、架构图、时序图按特性复杂度选择使用；

---

特性 RFC 模板

目的：在代码开发前，把要解决的问题、接口、方案、依赖、约束和验证讲清楚。

填写原则：只写本特性相关内容。列表为 checklist，代表需要涵盖的信息，但是不局限使用列表来呈现，维度涵盖即可，格式不限。

1. 基本信息

项目	内容
作者
相关模块	model / distributed / checkpoint / optimizer / trainer
相关 issue / PR
适用后端	PT / MS / PT + MS

2. 背景

说明为什么要做。本节只保留和本特性直接相关的信息。

类型	需要说明的内容
功能补全	当前缺什么能力；影响什么场景
性能优化	哪个场景慢；当前指标；目标指标
能力增强	已有类似能力，但本 RFC 要增强什么
用户需求	用户怎么使用；当前阻塞点；完成后怎么验收

本 RFC 要解决的问题：xxx。
完成后的成功标准：xxx。

3. 目标和非目标

3.1 目标

1. 支持 xxx。
2. 在 xxx 场景下达到 xxx 性能 / 显存目标。
3. 支持 PT / MS 的 xxx 范围。

3.2 非目标

1. 本期不支持 xxx，原因是 xxx。
2. 本期不优化 xxx，原因是 xxx。

4. 相关实现参考

来源	做法	限制	对本 RFC 的影响
相关框架 / 原生实现 / 模型写法

5. 对外接口

5.1 接口定义

# 按实际特性替换
model = enable_xxx(
    model,
    enabled=True,
    mode="xxx",
    option_a=...,  # 含义、默认值、合法范围
)

入参 / 配置项	类型	默认值	是否必填	含义	合法范围	错误处理
enabled	bool	False	否	是否打开特性	True / False
mode	str

5.2 使用示例

config.xxx.enabled = True

trainer = Trainer(config)
trainer.fit(model, dataloader)

5.3 接口说明

为什么这样设计：xxx。
和已有接口是否一致：一致 / 不一致。
如果不一致，原因是：xxx。

6. 方案设计

6.1 总体流程

flowchart TD
    A["读取用户配置"] --> B["校验参数合法性"]
    B --> C{"是否开启本特性"}
    C -- "否" --> D["保持现有训练流程"]
    C -- "是" --> E["准备分布式上下文"]
    E --> F["改写 / 包装模型"]
    F --> G["构建 optimizer / scheduler"]
    G --> H["执行训练 step"]
    H --> I["checkpoint save / load"]
    I --> J["指标与日志上报"]

6.2 架构参考

建议用架构图说明本特性和框架内核心模块的依赖关系，各种并行、swap、重计算等的边界。

flowchart LR
    subgraph User["用户侧"]
        Config["Config"]
        Model["Model Definition"]
        Data["Dataloader"]
    end

    subgraph Framework["Hyper Parallel Framework"]
        Trainer["Trainer"]
        Feature["Feature Runtime"]
        Dist["Distributed Context"]
        Wrapper["Model Wrapper"]
        Optim["Optimizer Adapter"]
        Ckpt["Checkpoint Adapter"]
    end

    subgraph Backend["后端"]
        PT["PyTorch Backend"]
        MS["MindSpore Backend"]
        Comm["Communication Backend"]
    end

    Config --> Trainer
    Model --> Wrapper
    Data --> Trainer
    Trainer --> Feature
    Feature --> Dist
    Feature --> Wrapper
    Trainer --> Optim
    Trainer --> Ckpt
    Dist --> Comm
    Wrapper --> PT
    Wrapper --> MS

6.3 时序参考

sequenceDiagram
    participant U as User
    participant T as Trainer
    participant R as Feature Runtime
    participant D as Distributed
    participant M as Wrapped Model
    participant O as Optimizer
    participant C as Checkpoint

    U->>T: fit(model, dataloader)
    T->>R: prepare(config, model)
    R->>D: init process group / mesh
    R->>M: wrap or transform model
    T->>M: forward(batch)
    M->>D: collective communication
    M-->>T: loss
    T->>M: backward(loss)
    M->>D: gradient sync / reduce-scatter
    T->>O: step()
    T->>O: zero_grad()
    T->>C: save / load when needed

6.4 关键逻辑

def enable_xxx(model, config):
    validate_config(config)
    model = prepare_model(model, config)
    runtime = prepare_runtime(config)
    return WrappedModel(model, runtime)

6.5 代码改动点

模块	改动内容	是否影响已有行为
model		是 / 否
distributed		是 / 否
checkpoint		是 / 否 / 不涉及
optimizer		是 / 否 / 不涉及
trainer		是 / 否 / 不涉及

6.6 方案取舍

如果有多个方案，填写：

方案	优点	缺点	是否选择	原因
A			是 / 否
B			是 / 否

如果只有一个方案，填写：

只保留该方案的原因：xxx。
该方案的主要代价：xxx。

7. 组件依赖

依赖组件	强依赖 / 弱依赖	当前状态	未 ready 时本期能力
FSDP	强 / 弱 / 不涉及
TP / PP	强 / 弱 / 不涉及
checkpoint	强 / 弱 / 不涉及
optimizer	强 / 弱 / 不涉及
PT / MS 后端	强 / 弱 / 不涉及

完整能力需要：xxx。
本期最小可交付能力：xxx。

8. 约束与兼容性

类型	内容
不支持项
性能收益	场景、指标、目标
显存收益	场景、指标、目标
性能劣化	场景、原因、是否可接受
PT / MS 差异	支持范围、行为差异
和已有行为不一致	差异、原因、迁移方式

9. 验证设计

9.1 用例分层

用例级别	数量	覆盖内容	通过标准
UT		接口、参数校验、核心函数
Level0		最小训练闭环
Level1		分布式、多组件组合、性能 / 显存

9.2 交互验证（举例）

组合	是否验证	通过标准
本特性 + FSDP / TP / PP /CP / EP / 重计算等	是 / 否	和单卡 loss 对齐，误差 <= xxx
本特性 + checkpoint	是 / 否	save / load 后可继续训练
PT / MS 对齐	是 / 否	行为一致或差异符合文档

9.3 性能 / 显存验证

场景	基线	开启本特性	指标	通过标准
			step time / throughput / peak memory

10. 实现计划

PR	内容	依赖	验证
PR1	接口和参数校验	无	UT
PR2	核心方案实现	PR1	UT + Level0
PR3	组件交互和验证	PR2	Level1

schema_version: 1
source: gitcode
gitcode_repo: mindspore/hyper-parallel
gitcode_issue: 284
source_url: https://gitcode.com/mindspore/hyper-parallel/issues/284

Start by reviewing the repository's existing documentation and issue-template conventions; this issue does not name a target file or test. Add the proposed feature RFC template with its sections, checklists, diagrams, interface examples, dependency guidance, compatibility constraints, validation design, and implementation plan, while preserving the stated scope and formatting.