[GLM-5.2] Preserve HF config compatibility for vLLM

[jayhenry]

Summary

• preserve the original GLM-5.2 compatibility fields when XTuner reconstructs the Hugging Face config
• restore topk_method="noaux_tc" so vLLM and SGLang construct the router layout expected by the checkpoint
• serialize only meaningful RoPE values and keep the current Transformers head_dim normalization unchanged
• add a model-agnostic check_hf_config_save testing helper plus a check-hf-config-save skill for future model ports
• replace the narrow GLM field assertions with a public from_hf -> save_hf contract test

Root cause

flowchart LR
    A["Original HF config"] --> B["XTuner from_hf"]
    B --> C["XTuner internal config"]
    C --> D["Reconstructed HF config"]
    D --> E["Inference-engine model construction"]
    E --> F["Checkpoint weight loading"]

Loading

The previous reverse mapping from Glm52MoEConfig to HFGlmMoeDsaConfig omitted legacy compatibility fields. In particular, the exported checkpoint still contained tensors such as:

model.layers.10.mlp.gate.e_score_correction_bias

but its config.json omitted topk_method.

Transformers 5.14.1 no longer exposes topk_method as a GLM-5.2 architecture argument. Its GLM implementation constructs and uses the correction bias independently of that legacy field, so adding the field back does not change current Hugging Face model structure or inference semantics.

vLLM 0.26.0 still treats the field as a model-construction switch: it registers gate.e_score_correction_bias only for topk_method == "noaux_tc" (exact source). When the field is absent, vLLM builds no matching parameter and fails on the existing checkpoint tensor with:

KeyError: 'layers.10.mlp.gate.e_score_correction_bias'

SGLang 0.5.16 has the same value-sensitive correction-bias construction (exact source) and also directly reads moe_layer_freq when selecting sparse layers (exact source).

Therefore these configs are equivalent for current Hugging Face inference, but they are not equivalent inputs to the vLLM/SGLang model constructors. Restoring the fields fixes a real engine load-time compatibility failure.

Generic export check

xtuner._testing.check_hf_config_save compares:

1. the raw source config.json;
2. the source loaded and saved directly by the active Transformers version;
3. the XTuner public from_hf -> save_hf result.

The direct Transformers round-trip is the serialized reference. This prevents forced changes such as head_dim, layer_types, and mlp_bias in Transformers 5.14.1 from being misdiagnosed as XTuner bugs. Versioned HFConfigFieldDependency entries independently protect engine-critical fields that Transformers may not consume.

The new check-hf-config-save skill standardizes this workflow for future models: resolve exact versions, inspect exact engine tags, add the public-path regression test, and report runtime checks separately from source-only audits.

GLM-5.2 result

Environment/component	Exact version	Validation	Result
pt29_glm1 Transformers	5.2.0	executable helper + GLM config tests	5 passed
pt29_glm2 Transformers	5.14.1	executable helper + GLM config tests	5 passed
vLLM	0.26.0	production failure log + exact-tag source audit	dependency confirmed
SGLang	0.5.16	latest stable exact-tag source audit	dependencies confirmed

Transformers normalization observed by the helper:

Transformers	Source -> direct HF round-trip	Direct HF round-trip -> XTuner
5.2.0	bos_token_id, transformers_version	no differences
5.14.1	bos_token_id, head_dim, layer_types, mlp_bias, transformers_version	no differences

The old hf-800/config.json is a negative reproduction: the helper rejects it for missing ep_size, index_topk_pattern, moe_layer_freq, pretraining_tp, rope_interleave, and topk_method, and for the unrelated RoPE defaults/nulls. The repaired export passes in both Transformers versions.

head_dim remains intentionally unchanged in XTuner code. Transformers 5.14.1 continues to normalize it to qk_rope_head_dim in GlmMoeDsaConfig.__post_init__.

Additional checks: targeted Ruff checks, Python compile checks, and skill validation all pass.