支持 YAML 生成统一的 typed TrainerConfig

1. 基本信息

项目	内容
作者	Tonghan Zhang
相关模块	config、trainer、训练组件
相关 Issue / PR	Issue #288；当前实现 PR
适用后端	本特性的配置解析层与后端无关

2. 背景

当前 Hyper-Parallel 的训练输入路径为：

YAML / CLI
→ parse_args(HyperTrainerConfig)
→ HyperTrainerConfig(model, data, train)
→ discover_model_spec(model.name)
→ LLMTrainer / VLTrainer
→ BaseTrainer._build_*

HyperTrainerConfig 是固定的三层参数树。当前 YAML 中没有 _target_；parse_args() 只按 model / data / train 的 dataclass 字段读取参数。具体模型通过 model.name 和 registry/discovery 选择，dataloader、optimizer、checkpoint 等运行对象由 Trainer 和 BaseTrainer._build_* 选择并创建。

本 Issue 新增一级组件 _target_，让 YAML 可以选择具体 Config 类或 factory。引入该接口后，resolver 需要在进入 Trainer 前完成以下检查：

• target 路径存在且目标可调用；
• target 参数名合法且必填参数齐全；
• 参数值符合 target 签名；
• target 返回值符合对应的 TrainerConfig 字段类型。

解析成功后，TrainerConfig 的一级字段直接挂载组件 Config、参数 Config 或模型输入配置。

本 Issue 要解决的问题：YAML 在进入 Trainer 前生成完整、可校验的 typed TrainerConfig。组件的类型和参数在解析阶段确定，运行对象的构造顺序仍由后续 Trainer 迁移负责。
完成后的成功标准：完整配置可以解析为 TrainerConfig；`_target_`、字段、必填参数和类型错误在 Trainer 构建前报告。

3. 目标和非目标

3.1 目标

1. 提供 TrainerConfig 作为新的 typed 解析结果；现有 Trainer 在运行迁移前继续使用 HyperTrainerConfig。
2. YAML 中实际提供的一级组件分组分别通过 _target_ 选择 Config 类或 factory。
3. resolver 根据 TrainerConfig 字段、target 参数签名和返回类型完成校验。
4. 支持在最终 TrainerConfig 上应用 typed CLI dotted override。
5. 为本期纳入 TrainerConfig 的一级字段提供明确的 Config 接口。
6. model 使用通用 ModelConfig 保存模型名称、权重路径和架构覆盖参数。

3.2 非目标

1. 本阶段不创建 Trainer、model、optimizer、dataloader 等训练运行对象。
2. 本阶段不迁移 BaseTrainer._build_* 的运行构造职责，也不执行 train step 或 checkpoint load。
3. resolver 只解析 YAML 的一级组件分组，不递归解析嵌套 _target_。
4. Dataset、Collator 和 DataLoader 的运行时依赖与构造顺序由后续数据组件迁移定义。
5. Hugging Face 模型 target、resolved-config 记录和任意 callback 列表分别评审，不纳入本阶段接口。
6. 旧 HyperTrainerConfig、model registry 和 discovery 路径不在本阶段修改。

4. 相关实现参考

来源	做法	限制	对本 Issue 的影响
TorchTitan	Trainer.Config 直接挂载 model spec、dataloader、optimizer、scheduler、loss、checkpoint 等 typed 组件；Trainer 按运行依赖调用各组件 build()	用户入口主要是 Python 配置函数，不是 Hyper 现有的 YAML	Hyper 采用统一根 TrainerConfig 和组件 Config 边界，同时保留 YAML 入口
AutoModel	YAML _target_ 可以导入并调用对象；数据路径正在转向 typed Dataset、Dataloader 和 Collator 的受控构造	通用 ConfigNode 允许嵌套 target，组件依赖和构造顺序需要由 recipe 额外管理	Hyper 只解析一级组件 target；组件内部组合由所属 Config/build 管理

5. 对外接口

5.1 根配置

PR1 提供 parse_training_args() 作为 YAML 配置解析入口。该函数读取命令行中的 YAML 路径和 dotted override，返回 TrainerConfig：

from hyper_parallel.config.manager import parse_training_args

config = parse_training_args()

parse_training_args() 负责拆分配置文件路径与剩余 CLI 参数；YAML 加载、resolve_root(raw) 和 override 应用共同完成配置解析。PR1 输出最终 TrainerConfig；PR2 将 train_lm.py、train_vl.py 和 Trainer 切换到该配置。

TrainerConfig 的一级字段参考 TorchTitan 的组件边界，并按 Hyper 的对象所有权定义：

YAML 字段	TrainerConfig 字段类型	接口职责
model	ModelConfig	保存模型名称、权重路径和架构覆盖参数
optimizer	Optimizer.Config 或 None	保存具体 optimizer 实现的 Config，例如 AdamW.Config
lr_scheduler	LRScheduler.Config 或 None	保存具体 scheduler 实现的 Config，例如 CosineWithWarmup.Config
loss	Loss.Config 或 None	保存具体 loss 实现的 Config，例如 CausalLMLoss.Config
training	TrainingConfig	保存训练循环参数，不创建运行对象
accelerator	AcceleratorConfig	保存并行拓扑和策略参数，不创建运行对象
mixed_precision	MixedPrecisionConfig	保存参数、通信和输出 dtype
gradient_checkpointing	GradientCheckpointingConfig	保存激活重计算策略参数
debug	DebugConfig	保存确定性、数值检查等调试参数
comm	CommConfig	保存通信初始化和超时参数

model 的解析结果是一次训练使用的 ModelConfig。后续运行路径根据 model.name 通过现有 registry/discovery 取得 ModelSpec；resolver 不生成 ModelSpec。

具有默认值的字段可以在普通训练 YAML 中省略。YAML 中一旦显式提供某个一级字段，该分组就必须包含 _target_。

5.2 YAML 示例

model:
  _target_: hyper_parallel.trainer.config.ModelConfig
  name: qwen3_5
  weights_path: /path/to/Qwen3.5-0.8B-Base

training:
  _target_: hyper_parallel.trainer.config.TrainingConfig
  max_steps: 100
  global_batch_size: 8

accelerator:
  _target_: hyper_parallel.trainer.config.AcceleratorConfig
  tp: 2

optimizer:
  _target_: hyper_parallel.components.optim.AdamW.Config
  lr: 0.0002
  weight_decay: 0.1

loss:
  _target_: hyper_parallel.components.loss.CausalLMLoss.Config
  ignore_index: -100

这是最小接口示例。完整解析测试覆盖本期 TrainerConfig 已声明的全部一级字段。

5.3 CLI dotted override

训练入口迁移完成后，用户命令格式为：

torchrun --nproc_per_node=8 scripts/train_lm.py \
  configs/qwen3_5.yaml \
  --training.max_steps=200 \
  --accelerator.tp=4 \
  --optimizer.lr=0.0001

parse_training_args() 读取第一个位置参数作为 YAML 路径，将剩余的 --field=value token 作为 dotted override。resolver 先生成 typed TrainerConfig，再应用 override。字段必须存在于最终配置类型中，值必须符合字段类型。本期交付终点是返回 TrainerConfig；当前 train_lm.py 和 train_vl.py 仍使用旧 parse_args(HyperTrainerConfig)，入口切换由后续 PR 完成。

5.4 模型配置

模型分组直接生成通用 ModelConfig：

ModelConfig(
    name="qwen3_5",
    weights_path="/path/to/Qwen3.5-0.8B-Base",
)

resolver 只得到模型输入配置，不导入模型 package、不创建模型，也不加载权重。现有训练入口随后根据 model.name 发现并取得对应 ModelSpec。

6. 方案设计

6.1 关键逻辑

函数	职责
parse_training_args()	对外入口；从命令行取得 YAML 路径和 dotted override，返回最终 TrainerConfig
resolve_root()	根据 TrainerConfig 检查 YAML 根字段和必填字段，逐个解析一级分组，最后创建 TrainerConfig
resolve_component()	读取一个分组的 _target_，检查 target 的返回类型、参数签名和参数类型，再调用 target 创建配置对象
import_target()	将 dotted path 导入为 Python 类或 factory，支持 AdamW.Config 这类嵌套属性路径
coerce_value()	根据类型注解校验并转换 YAML 参数，同时供 CLI override 使用

调用顺序为 parse_training_args() -> resolve_root() -> resolve_component() -> import_target() / coerce_value()，随后在生成的 TrainerConfig 上应用 CLI override。一级字段集合由 TrainerConfig 声明；target 内部参数直接传给当前 target，不继续扫描嵌套 _target_。

6.2 代码改动点

模块	改动内容	是否影响已有行为
hyper_parallel.trainer.config	定义 TrainerConfig、TrainingConfig 和 CommConfig，并将现有 AcceleratorConfig、MixedPrecisionConfig、GradientCheckpointingConfig、DebugConfig 接入根配置	新增 typed 配置接口；运行入口切换前不改变训练行为
hyper_parallel.config.resolver	导入一级 target，校验参数和返回类型，构造 TrainerConfig	新增解析路径
hyper_parallel.config.manager	解析命令行中的 YAML 路径和 override，调用 resolver 并返回 TrainerConfig	新增统一配置入口
optimizer、scheduler、loss 组件模块	提供本期可解析的具体 Config 类型	本阶段只定义接口，不迁移运行构造
模型配置	复用通用 ModelConfig	不修改内置模型 package 或现有 ModelSpec 注册方式
train_lm.py / train_vl.py	后续运行迁移时接收 TrainerConfig 并选择对应 Trainer	本阶段保留现有运行路径
配置解析测试	覆盖完整字段、错误路径和 CLI override	不启动 Trainer

6.3 方案取舍

方案	优点	缺点	是否选择	原因
YAML → 通用动态节点 → typed Config	能表达任意嵌套 target	同时维护动态节点和 typed Config；运行依赖边界不清晰	否	Hyper 不需要第二套中间配置树
YAML 一级 target → TrainerConfig	入口保持 YAML；最终结果只有一棵 typed 配置树	新组件必须先定义 Config 接口并确定所有权	是	配置字段、组件接口和错误检查边界明确

新增训练参数或组件时，先由使用该字段的训练流程负责人和所属组件负责人确定：

1. 字段属于已有 TrainingConfig、AcceleratorConfig 等参数类，还是新的一级组件；
2. 运行对象由哪个组件 build()；
3. 是否需要修改 Trainer 的构造顺序；
4. Config 字段、YAML 示例和验证用例如何同步更新。

新增 optimizer、loss 等实现时，应在所属组件模块增加对应 Config/build，而不是向 YAML 开放未声明字段。

7. 组件依赖

依赖组件	强依赖 / 弱依赖	当前状态	未 ready 时本阶段能力
TrainerConfig 字段定义	强依赖	本 Issue 定义	无法校验 YAML 一级字段和组件返回类型
各组件 Config 接口	强依赖	本阶段补齐接口	对应字段不能进入完整解析测试
通用 ModelConfig	强依赖	复用现有模型输入参数类型	model 字段无法解析
BaseTrainer._build_*	弱依赖	现有运行路径可用	不影响配置解析；运行迁移后续完成
PT / MS 后端	不涉及	解析层共用 Python 类型	本阶段不创建后端运行对象

完整能力需要 TrainerConfig 字段、组件 Config 接口、resolver 和 CLI override 同时可用。本阶段最小可交付能力是完整 YAML 到 typed TrainerConfig 的解析与错误检查。

8. 约束与兼容性

类型	内容
配置边界	parse_training_args() 返回最终 TrainerConfig；每个一级组件分组通过 _target_ 选择 Config 类或 factory
target 范围	target 只创建 Config、参数类或 ModelConfig，不创建训练运行对象
嵌套结构	resolver 不递归实例化 target 参数；组件内部组合由所属 Config/build 管理
已有训练行为	运行入口迁移前继续使用旧 HyperTrainerConfig、registry/discovery 和 BaseTrainer._build_*
迁移方式	PR2 使用现有 Qwen3.5 完成组件运行迁移，再决定旧配置入口的删除范围
性能与显存	解析只发生在启动阶段，不改变训练计算、通信、吞吐或显存路径
PT / MS 差异	解析行为一致；后端差异由具体组件 Config/build 所有者处理

9. 验证设计

9.1 用例分层

用例级别	数量	覆盖内容	通过标准
UT	参数化覆盖	target 导入、字段名、必填参数、参数类型、返回类型、CLI override	所有成功与失败路径符合字段路径和类型约束

9.2 解析验收

用例	通过标准
完整 YAML	显式覆盖 5.1 节全部一级字段并生成 TrainerConfig；各字段对象类型正确
默认字段	省略具有默认值的一级字段时，由 TrainerConfig 提供正确默认对象
未知一级字段	在调用任何 target 前失败，错误包含根字段路径
缺少 _target_	显式提供的一级组件分组立即失败，错误包含字段路径
target 导入	路径不存在或目标不可调用时失败，错误包含字段路径
参数名称	optimizer.lrr 等未知参数在调用 target 前失败
必填参数	缺少 target 必需参数时指出参数名和字段路径
参数类型	参数值不符合 target 参数注解时失败
factory 返回类型	target 返回值不符合 TrainerConfig 字段类型时失败
typed CLI	可覆盖具体组件字段；未知字段和值类型错误立即失败
解析副作用	解析过程不创建 Trainer、model、optimizer、dataloader 或 checkpoint manager

9.3 性能 / 显存验证

本阶段不改变训练运行路径，不设置训练性能或显存目标。验证解析耗时不进入 train step 即可。

10. 实现计划

PR	内容	依赖	验证
PR1	TrainerConfig、一级 target resolver、config manager、typed CLI override，以及本期 optimizer、scheduler、loss Config	无	配置解析 UT
PR2	使用现有 Qwen3.5 迁移组件构建和训练入口，并评审旧 HyperTrainerConfig 的删除范围	PR1	UT + Level0
后续 PR	按模型或训练流程补充新组件，并由流程负责人和组件负责人共同确定字段所有权与构造顺序	PR2	对应组件 UT + 训练验证

PR1 的完成标准：一份显式覆盖 TrainerConfig 全部一级字段的 YAML 能生成完整 typed 配置；具有默认值的字段可以省略；CLI override 可用；所有 target、参数和类型错误均在进入 Trainer 前报告。