Skip to content

Add routed-expert MXFP4 QAT for Hy3 - #2

Open
ISEEKYAN wants to merge 13 commits into
mainfrom
feature/hy3-routed-expert-mxfp4-qat
Open

Add routed-expert MXFP4 QAT for Hy3#2
ISEEKYAN wants to merge 13 commits into
mainfrom
feature/hy3-routed-expert-mxfp4-qat

Conversation

@ISEEKYAN

@ISEEKYAN ISEEKYAN commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Summary

  • expose Megatron Lite's standard MXFP4 QAT primitive through ImplConfig.qat
  • keep the model integration declarative and apply QAT before optimizer construction
  • map Hy3's split Transformer Engine expert parameters onto BF16 QAT masters
  • support canonical checkpoint load, BF16 round trip, and routed-only MXFP4 HF export
  • provide reproducible scheduler entry points with pinned source revisions and import-path assertions

Quantization scope

The policy matches K3: quantize every routed-path linear and no other component. The concrete structures differ:

  • Hy3 fc1.weightK is the fused gate-plus-up projection for local expert K; fc2.weightK is its down projection.
  • These correspond to K3 experts.K.gate_up.weight and experts.K.down.weight.
  • K3's latent-MoE additionally quantizes shared routed-path routed_expert_down_proj and routed_expert_up_proj linears and has a routed-expert norm. Hy3 has no equivalent latent bottleneck or norm.
  • Hy3's K is the local-expert index because Megatron Lite passes num_experts / ep_size to each Transformer Engine GroupedLinear.

Attention, dense MLP, shared experts, embedding, router/correction bias, and lm_head remain BF16. Hy3 also has no K3-style standalone attention residual-projection modules: its attention output projection is excluded under attn, while residual additions have no parameters.

The Hy3 declaration therefore matches exactly moe.experts.fc1/fc2 modules and parameters named weight followed only by digits. This covers every local expert tensor without matching similarly named non-weight state.

Validation

  • real Tencent Hy3 routed-expert weights: 100,663,296 elements across 16 tensors; fake quantization and serialized dequantization are bitwise equal to ModelOpt 0.43
  • expected full-model routed-expert name set derived from the Hy3 checkpoint map: 46,080 tensors
  • runtime parameter contract: the QAT BF16 master set must equal the pre-QAT routed fc1/fc2.weightK set; the two-expert tiny model has exactly 4 masters
  • canonical checkpoint load and BF16 export: 33 tensors, bitwise round trip
  • routed-only MXFP4 export: 6 packed HF weights with scales; excluded weights remain BF16
  • forward/backward: finite loss and gradients present on every routed-expert master
  • CPU suite: 21 passed; 8 scheduler/CUDA-only tests skipped locally and covered by the non-skipped scheduler acceptance above
  • Ruff check, changed-file Ruff format check, shell syntax, and whitespace checks: passed

The repository currently has no .pre-commit-config.yaml or pinned Ruff version. The equivalent Ruff check and changed-file format checks were run directly without reformatting unrelated pre-existing files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant