已开启

【RFC】hyper-parallel 支持torchtitan 风格 Module/Config —— Part 8 模型扩展+切换为默认spec #146

changzherui创建于 5月15日

changzherui成员

5月15日创建

Part 8 — 其他模型迁移 + 切换默认 spec

按 M6 模式把剩余生产模型（qwen3_5_moe / qwen3_vl_moe）迁移为 Module 协议版；待全部 v2 稳定 ≥ 1 周后切换默认 spec，清理 legacy 代码。滚动推进，不阻塞主线。

1. 目标

把 qwen3_5_moe / qwen3_vl_moe 迁移为 v2，覆盖 MoE / VL 两类核心场景。
当所有 v2 稳定后，切换默认 spec 为 v2，旧实现下沉到 _legacy/。
暴露公共 API、补文档。

2. 任务边界

M8.1 — `qwen3_5_moe_v2/` 迁移（按 M6 模式）

新文件	旧对应	内容
`models/qwen3_5_moe_v2/model.py`	`models/qwen3_5_moe/model.py`	`Qwen3_5MoeModel(Decoder) + Qwen3_5MoeTransformerBlock`；用 M4 `models/common/moe.py` 的 `MoE / Router / Experts / SharedExpertMoE`
`models/qwen3_5_moe_v2/sharding.py`	—	`set_qwen3_5_moe_sharding_config(config, *, loss_parallel, enable_sp, ep_degree)`：声明 EP 切分
`models/qwen3_5_moe_v2/parallelize.py`	`models/qwen3_5_moe/parallelize.py`	CP → TP → EP → AC → FSDP 的串联；复用旧 `_apply_ep`、`_apply_ac` 算法
`models/qwen3_5_moe_v2/state_dict.py`	`models/qwen3_5_moe/state_dict.py:Qwen3_5MoeStateDictAdapter`	继承 `BaseStateDictAdapter`，复用旧"专家融合 / 拆分"键名映射
`models/qwen3_5_moe_v2/config_registry.py`	—	`qwen3_5_moe_v2_debug / qwen3_5_moe_v2_a3b / qwen3_5_moe_v2_a3b_ep8` 等 recipe
`models/qwen3_5_moe_v2/__init__.py`	`models/qwen3_5_moe/__init__.py`	`register_spec("qwen3_5_moe_v2", ModelSpec(...))`

工期：4 天。

M8.2 — `qwen3_vl_moe_v2/` 迁移（按 M6 模式 + VL 头）

新文件	旧对应	内容
`models/qwen3_vl_moe_v2/model.py`	`models/qwen3_vl_moe/model.py`	`Qwen3VlMoeModel(BaseModel)`：vision encoder + projector + text decoder（复用 `Qwen3_5MoeModel`）
`models/qwen3_vl_moe_v2/vision.py`	—	`VisionTower(Module)`：vision transformer 块（按 Module 协议）
`models/qwen3_vl_moe_v2/sharding.py`	—	`set_qwen3_vl_moe_sharding_config`：vision 路径只走 FSDP，不走 TP（与旧版一致）
`models/qwen3_vl_moe_v2/parallelize.py`	`models/qwen3_vl_moe/parallelize.py`	沿用旧版 vision / projector / text 分别 FSDP 包装策略
`models/qwen3_vl_moe_v2/state_dict.py`	`models/qwen3_vl_moe/state_dict.py`	VL HF↔hyper 键名映射
`models/qwen3_vl_moe_v2/config_registry.py`	—	`qwen3_vl_moe_v2_a3b` 等 recipe
`models/qwen3_vl_moe_v2/__init__.py`	`models/qwen3_vl_moe/__init__.py`	`register_spec("qwen3_vl_moe_v2", ...)`
`scripts/train_vl.py`（改 ≈ 5 行）	现 `scripts/train_vl.py`	同 M7：切换到 `ConfigManager.parse_args()`

工期：5 天。

M8.3 — 切换默认 spec + 清理 legacy + 公共 API + 文档

任务	内容
切换默认 spec	`register_spec("qwen3_5", spec_v2)` —— v2 实现替换 v1；`models/qwen3_5/` 移到 `models/qwen3_5_legacy/`，加 `@deprecated` 装饰器；同理处理 `qwen3_5_moe / qwen3_vl_moe`
暴露公共 API	`hyper_parallel/__init__.py` 新增导出：`Module / BaseModel / ModelSpec / ShardingConfig / NamedPlacement / MeshAxisName / set_*_sharding_config / ConfigManager / Configurable / Function`（按 §3 列表）
写 `docs/zh/module_protocol.md`	"如何按 Module 协议新增一个模型" 教程，包含：`Config` 设计 / `update_from_config` 实现 / `set_<name>_sharding_config` 编写 / `parallelize_<name>` 串联 / `state_dict_adapter` 实现
写 `docs/zh/config_system.md`	新 CLI 用法、`config_registry.py` 模板、字段对照表（参考 M2 文档）
写 `docs/migrations/v2_migration.md`	旧 yaml → 新 CLI 的迁移指南

工期：2 天。

3. M8.3 公共 API 暴露清单

在 hyper_parallel/__init__.py 新增：

# Module 协议
from hyper_parallel.protocols import (
    Configurable, Module, ModuleList, ModuleDict, Sequential,
    BaseModel, ModelSpec,
    ShardingConfig, NamedPlacement, LocalMapConfig, MeshAxisName,
    BaseStateDictAdapter,
)

# 配置系统
from hyper_parallel.config import (
    ConfigManager, Function, TORCH_DTYPE_MAP,
    TrainingConfig, ParallelismConfig, ActivationCheckpointConfig,
    CompileConfig, CommConfig, DebugConfig,
)

# 训练组件
from hyper_parallel.components import (
    OptimizersContainer, LRSchedulersContainer,
    BaseLoss, CrossEntropyLoss,
    BaseTokenizer, HuggingFaceTokenizer,
    BaseDataLoader, HuggingFaceTextDataLoader, DummyDataLoader,
    CheckpointManager, Profiler, MetricsProcessor,
)

# 通用模型组件
from hyper_parallel.models.common import (
    Linear, Embedding, RMSNorm, Qwen3_5RMSNorm,
    RoPE, GQAttention, FeedForward, MoE,
    TransformerBlock, Decoder,
    set_decoder_sharding_config, set_gqa_attention_sharding,
    set_dense_ffn_sharding, set_qkv_linear_sharding,
    colwise_config, rowwise_config, norm_config,
)

4. 与 torchtitan 接口差异说明

#	差异点	原因
1	spec 名称命名约定：`<base>_v2` 用于过渡期；M8.3 切换后改回 `<base>`	与现存 spec 并存避免冲突；切换后清理
2	`models/qwen3_5_legacy/` 保留至少 1 个版本周期才删除	给现网用户充足迁移时间
3	VL 路径的 `vision` / `projector` / `text` 分别 FSDP 包装是 hyper 现有约定	`models/qwen3_vl_moe/parallelize.py` 已成熟，不改逻辑

5. 开发步骤

M8.1 步骤（4 d）

Day 1：model.py，重写 Qwen3_5MoeModel。
Day 2：sharding.py + parallelize.py（EP 切分声明 + AC + FSDP 串联）。
Day 3：state_dict.py + config_registry.py + __init__.py。
Day 4：8-card 训练数值对齐验证、修 bug。

M8.2 步骤（5 d）

Day 1：model.py + vision.py。
Day 2：sharding.py + parallelize.py。
Day 3：state_dict.py。
Day 4：config_registry.py + __init__.py + scripts/train_vl.py。
Day 5：8-card / 16-card 验证。

M8.3 步骤（2 d）

执行前置条件：M8.1 + M8.2 + M7 全部稳定 ≥ 1 周（每日 CI 数值对齐通过）。

Day 1：切换 register_spec；把旧实现移到 _legacy/；加 @deprecated；更新 hyper_parallel/__init__.py。
Day 2：写 3 篇文档；跑全量回归。

6. 验证标准

M8.1 / M8.2

测试	断言要点
`tests/torch/st/qwen3_5_moe_v2/test_st_loss.py`	8-card / 16-card 训练 10 步，loss / grad_norm 与旧 `qwen3_5_moe` 同种子误差 ≤ 1e-4
`tests/torch/st/qwen3_vl_moe_v2/test_st_loss.py`	同上，针对 VL 路径
`tests/torch/st/*/test_state_dict_roundtrip.py`	HF 权重加载到新 / 旧路径 state_dict 张量逐元素一致

M8.3

测试	断言要点
`tests/torch/st/default_spec_switch/test_qwen3_5_default_v2.py`	`register_spec("qwen3_5", ...)` 切到 v2 后，默认 `--module qwen3_5 --config qwen3_5_4b` 命令跑通，loss 与切换前 v2 路径一致
`tests/torch/st/legacy_yaml/test_legacy_yaml_still_works.py`	旧 yaml 路径仍能跑（`models/qwen3_5_legacy/` 仍然被 `discover_model_spec` 找到）
`docs/zh/module_protocol.md` 完整覆盖 5 个步骤	人工 review

通过门槛：

8.1 / 8.2 各 3 个 ST 全绿。
8.3 公共 API 暴露后，所有 import hyper_parallel.X 不报错。
旧 yaml 路径仍可用至少 1 个版本周期。

7. 工期 & 依赖

子模块	工期	依赖	并行性
M8.1 qwen3_5_moe_v2	4 d	M1–M7	可与 M8.2 并行
M8.2 qwen3_vl_moe_v2	5 d	M1–M7	可与 M8.1 并行
M8.3 切换 + 清理	2 d	M8.1 + M8.2 稳定 ≥ 1 周	串行最后

总工期：~11 天（最短 ~7 天 + 稳定期）。

changzherui成员

5月15日修改标题为 “hyper-parallel 支持torchtitan 风格 Module/Config —— M8 模型扩展+切换为默认spec”，原标题为“hyper-parallel 支持torchtitan 风格 Module/Config —— M8”

changzherui成员

5月15日修改标题为 “【RFC】hyper-parallel 支持torchtitan 风格 Module/Config —— M8 模型扩展+切换为默认spec”，原标题为“hyper-parallel 支持torchtitan 风格 Module/Config —— M8 模型扩展+切换为默认spec”

changzherui成员

5月25日修改了issue 的描述

changzherui成员

5月25日修改标题为 “【RFC】hyper-parallel 支持torchtitan 风格 Module/Config —— Part 8 模型扩展+切换为默认spec”，原标题为“【RFC】hyper-parallel 支持torchtitan 风格 Module/Config —— M8 模型扩展+切换为默认spec”

Part 8 — 其他模型迁移 + 切换默认 spec

1. 目标

2. 任务边界

M8.1 — qwen3_5_moe_v2/ 迁移（按 M6 模式）

M8.2 — qwen3_vl_moe_v2/ 迁移（按 M6 模式 + VL 头）

M8.3 — 切换默认 spec + 清理 legacy + 公共 API + 文档

3. M8.3 公共 API 暴露清单

4. 与 torchtitan 接口差异说明

5. 开发步骤

M8.1 步骤（4 d）

M8.2 步骤（5 d）

M8.3 步骤（2 d）

6. 验证标准

M8.1 / M8.2

M8.3

7. 工期 & 依赖

M8.1 — `qwen3_5_moe_v2/` 迁移（按 M6 模式）

M8.2 — `qwen3_vl_moe_v2/` 迁移（按 M6 模式 + VL 头）