精简总结：现在 Hyper 缺少什么

一句话：并行底座（fully_shard / CE / Muon 库）够用；缺的是把 GlmImageMoe 这条任务 在原生 Hyper 里跑通的产品能力。

硬缺（没有就训不了同一张网）

1. 模型：无 GlmImageMoe ModelSpec（VQ + MoE + vq_to_llm_proj）
2. 数据：无 DirectToken / WDS / packing（visual_indices、cu_seqlens 等）
3. 接线：无该模型的 parallelize_fn + Trainer 专用 batch 路径（现 VL 是 Qwen 像素路径）
4. MoE 运行时：要么迁 fused MoE + parallel_state 桩，要么换 HP MoE 并对齐

生产缺口（能训但不好用 / 对不齐配方）

• dyn_bsz、freeze_vq + FSDP ignore
• Trainer 未接 get_hyper_optimizer（Muon）
• 无 EMA、DCP 业务 extra_state 约定弱
• EP 在 Trainer 对 MoE 仍禁用

不缺

fully_shard、mesh、CE / loss_parallel、DCP 骨架、Muon 库、通用 LLM/VL Trainer 壳。

下文为分类清单与 P0–P3 / Acceptance 明细。

背景

目标：完全不用 VeOmni，仅用原生 HyperParallel 训练与当前 Omni 冒烟相同的网络（GlmImageMoe：文本 MoE + VQ codebook / DirectToken 路径）。

现有 examples/torch/glm_image_moe_smoke/ 已验证 HP fully_shard 可与 Torch FSDP2 在同 init/batch 下对齐 step1 loss，但实现仍 import veomni（模型 + DirectToken 数据）。本 issue 列出要将这条路径产品化为 零 VeOmni 依赖 时，Hyper 需要补齐的能力（按类目）。

对照结论一句话：

• 不必新造：fully_shard API、ParallelDims/mesh、CE / loss_parallel 算子、DCP 骨架、Muon 库实现、通用 Trainer 壳。
• 必须新造：GlmImage ModelSpec、DirectToken 数据+collate、该模型 parallelize_fn、Trainer 专用 batch 路径。

一、框架基础（Trainer / 注册 / 生命周期）

源码锚点（HP）：hyper_parallel/models/spec/registry.py、trainer/base.py、trainer/vl_trainer.py（现仅 Qwen pixel_values 路径）、scripts/train_lm.py / train_vl.py。

现状：仅有 qwen3_5 / qwen3_5_moe / qwen3_vl_moe 三条 Spec；无 GlmImage / Omni / VQ 注册。

二、网络与算子（模型本体）

不可砍的协议细节：

• 图像位用 placeholder（非 raw VQ id 进 input_ids）
• labels = VQ code + lang_vocab_size 偏移；CE ignore_index=-100
• _no_split_modules = ["Glm4MoeLiteDecoderLayer"]
• 冻结 VQ 时 root prepare_fsdp_root_ignored_params；vq_to_llm_proj 保持可训

三、并行化

现状：Trainer 路径对 qwen3_*_moe 在 ep>1/tp>1 直接 NotImplementedError；一等公民是 FSDP/HSDP。库内 EP demo 在 examples/torch/moe/，未挂 ModelSpec。

四、数据与 Batch

现状：LLM = dummy/HF/json/preset_pt；VL = vl_dummy/preset_pt + Qwen 像素键。无 webdataset、无 DirectToken、无 packing/cu_seqlens collate、无 dyn_bsz。

Batch 契约（与 VLTrainer 不兼容）：

input_ids, labels, position_ids, cu_seqlens, max_seqlens,
visual_indices, placeholder_token_id(_index), …

五、优化与训练语义

现状：Trainer _build_optimizer 固定 torch.optim.AdamW；get_hyper_optimizer 库有未接线；无 EMA。

六、存盘 / 续训 / 可观测

可复用：DCP 骨架、CheckpointCallback。

七、优先级与落地顺序

建议最小闭环：

M1 模型进 Spec
 → M2+D1+D2 数据与 forward 契约
 → M3+T1 fully_shard 训通（可用 preset_pt 先绕过 WDS）
 → M4 MoE kernel 定案（parallel_state 桩 或 换 HP MoE）
 → D3 dyn_bsz / O1 Muon / C1–C2 生产化
 → E* 按业务配方补
 → U* 官方零 VeOmni 路径

可砍（仍算「同一网络」对照）：EMA、aux/bias、multisource 细日志、online-VQ、EP。
不可砍：ModelSpec、DirectToken（或严格等价）数据/collate、parallelize_*、冻结 VQ + ignore、decoder FSDP 边界、vocab/placeholder 语义。

八、已有验证（参考）

• 冒烟/对齐目录：examples/torch/glm_image_moe_smoke/（当前仍依赖 VeOmni）
• 24L / 100 step：HP vs FSDP2，step1 diff ~1e-6；长跑有 bf16 累积漂移（max ~3e-2）
• 说明：并行数值路径可用；缺的是产品化与去 VeOmni 依赖

Acceptance（建议）

• model.name: glm_image_moe 经 HP Trainer 可启动，无 import veomni
• DirectToken（或 preset 等价 batch）喂入后 8 卡 fully_shard 跑通 ≥10 step，loss 有限
• 与同 init/batch 的 FSDP2 对照：step1 |Δloss| ≤ 1e-5（或文档约定阈值）
• （P1）dyn_bsz packing 与 freeze_vq + ignored_params 生效
• （P1）YAML 可选 Muon / AdamW 经 get_hyper_optimizer