Part 7 — CLI 入口打通

写 config_registry.py，把 scripts/train_lm.py 切到 ConfigManager，端到端跑 --module qwen3_5_v2 --config qwen3_5_v2_4b 命令。旧 yaml 路径仍是默认。

1. 目标

把"命令行 → HyperTrainer.Config → config.build() → trainer.train()"完整链路打通，达成 torchtitan 风格的"用户敲命令 → 并行模型 + 完整训练栈"4 步链路。

2. 任务边界

3. config_registry.py 示例

# hyper_parallel/models/qwen3_5_v2/config_registry.py
from hyper_parallel.config import (
    TrainingConfig, ParallelismConfig, ActivationCheckpointConfig,
)
from hyper_parallel.components.optimizer import OptimizersContainer
from hyper_parallel.components.dataloader import HuggingFaceTextDataLoader
from hyper_parallel.trainer.trainer_config import HyperTrainer

from .__init__ import qwen3_5_v2_spec_factory


def qwen3_5_v2_debugmodel() -> HyperTrainer.Config:
    return HyperTrainer.Config(
        model_spec=qwen3_5_v2_spec_factory("debugmodel"),
        optimizer=OptimizersContainer.Config(lr=8e-4),
        training=TrainingConfig(
            local_batch_size=8, seq_len=2048, steps=10,
        ),
        dataloader=HuggingFaceTextDataLoader.Config(dataset="dummy"),
        activation_checkpoint=ActivationCheckpointConfig(mode="selective"),
    )


def qwen3_5_v2_4b() -> HyperTrainer.Config:
    cfg = qwen3_5_v2_debugmodel()
    cfg.model_spec = qwen3_5_v2_spec_factory("4B")
    cfg.parallelism = ParallelismConfig(
        tensor_parallel_degree=2,
        data_parallel_shard_degree=-1,
    )
    return cfg


def qwen3_5_v2_4b_tp2_fsdp4() -> HyperTrainer.Config:
    cfg = qwen3_5_v2_4b()
    cfg.parallelism.tensor_parallel_degree = 2
    cfg.parallelism.data_parallel_shard_degree = 4
    return cfg

4. scripts/train_lm.py 改造（≈ 5 行）

改造前（现状，scripts/train_lm.py:39-47）：

if __name__ == "__main__":
    args = parse_args(HyperTrainerConfig)
    discover_model_spec(args.model.name)
    trainer = LLMTrainer(args)
    trainer.train()

改造后：

from hyper_parallel.config import ConfigManager

if __name__ == "__main__":
    mgr = ConfigManager()
    config = mgr.parse_args()           # 自动识别 --module / yaml
    trainer = config.build()            # HyperTrainer(config) 或 LLMTrainer(legacy)
    trainer.train()

关键点：

• ConfigManager.parse_args() 内部如果走旧 yaml 路径，返回的是经过 _legacy_to_trainer_config 后的 HyperTrainer.Config（M2）。
• config.build() 即 HyperTrainer(config) —— 不论新旧 CLI 入口，都收口到 M5 的 HyperTrainer.__init__。
• 旧 LLMTrainer 路径仍可手动调用：trainer = LLMTrainer(parse_args(HyperTrainerConfig))，方便回归对比。

5. 入口判定规则

ConfigManager.parse_args 的判定（M2 manager.py）：

argv[0] 起始为 "--module"   →  新 tyro 路径
                                  └─ importlib.import_module(
                                       "hyper_parallel.models.<NAME>.config_registry")
                                  └─ tyro.cli(HyperTrainer.Config, default=loaded_recipe,
                                              args=剩余 CLI)

否则（argv[0] 是 yaml 路径） →  旧路径
                                  └─ parse_args(HyperTrainerConfig)    # 复用 :547
                                  └─ _legacy_to_trainer_config(legacy)

6. 与 torchtitan 接口差异说明

7. 开发步骤

8. 验证标准

新建 tests/torch/st/qwen3_5_v2_cli/：

通过门槛：

• 4 个 ST 全绿。
• 旧 yaml 入口行为 0 改动（与 main 分支 bit-exact）。

9. 工期 & 依赖