背景

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

建议落地方式

填写原则：

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

---

特性 RFC 模板

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

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

1. 基本信息

项目	内容
作者
相关模块	model / distributed / checkpoint / optimizer / trainer
相关 issue / PR

2. 背景

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

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

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

3. 目标和非目标

3.1 目标

1. 支持 xxx。
2. 在 xxx 场景下达到 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	强 / 弱 / 不涉及

完整能力需要：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