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

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

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

---

1. 目标

1. 把 qwen3_5_moe / qwen3_vl_moe 迁移为 v2，覆盖 MoE / VL 两类核心场景。
2. 当所有 v2 稳定后，切换默认 spec 为 v2，旧实现下沉到 _legacy/。
3. 暴露公共 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）

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

M8.2 步骤（5 d）

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

M8.3 步骤（2 d）

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

1. Day 1：切换 register_spec；把旧实现移到 _legacy/；加 @deprecated；更新 hyper_parallel/__init__.py。
2. 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 天 + 稳定期）。

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

Start by comparing the listed qwen3_5_moe and qwen3_vl_moe implementations with the M6 patterns and the common MoE components in models/common/moe.py. Work through the M8.1 and M8.2 files and run the specified loss, state-dict roundtrip, and multi-card tests. Done means both v2 paths pass numerical and roundtrip checks, the default spec and legacy paths work, public APIs are exported, and the three documentation files are complete.