feat(minimax-h3): single-file truncated int8-convrot Qwen3-VL text encoder (PR 7)

[lstein]

Summary

PR 7 of the MiniMax H3 stack (on top of #145): load Comfy-Org's layer-truncated int8-convrot Qwen3-VL-32B text encoder (qwen3vl_32b_minimax_h3_int8_convrot.safetensors, 25.3 GiB) as a single-file override for the H3 folder's 62 GiB encoder. Tokenizer and processor still come from the folder.

Why: the bf16 encoder is ~64 GB of RAM/VRAM working set — two-thirds of a 96 GB machine by itself, and the reason concurrent H3 sessions thrash. The quantized file is fully resident on one GPU, drops session RAM by ~40 GB, and encodes ~22% faster (50 layers computed instead of 64).

The subtle part: truncation semantics

The file ships 50 of 64 layers, no model.norm, no lm_head, and declares its contract in safetensors metadata: "output": "unnormalized_hidden_after_layer_50". H3 conditioning reads hidden_states[50] unnormalized — but on a truncated stack, transformers tie-replaces the last hidden-states entry with the post-final-norm tensor. The loader therefore installs nn.Identity() as the final norm, making hidden_states[50] bit-identical to the raw last-layer output. Verified two ways:

• a cross-depth numerical test (full model vs truncated+Identity with copied weights → bit-identical hidden_states[k]), with a negative control showing a surviving real norm corrupts the tensor;
• the depth guard accepts exactly-50-layers only when the final norm is Identity (and still accepts the full folder encoder).

The absent lm_head is tied to the embeddings (never used — H3 is hidden-states-only conditioning).

Wiring

• Qwen3VLEncoder_Checkpoint_MiniMaxH3_Config: metadata-primary fingerprint + structural key checks on both paths; cross-probed against Krea-2's 4B encoder configs and PR 6's transformer config in both directions; identification fixture from the real file header. nvfp4 files rejected before the 25 GiB read.
• Checkpoint loader (int8 machinery shared with PR 6): serves only SubModelType.TextEncoder; bundled Apache-2.0 config (field-identical to the folder's, verified) with layer-count override; strict load asserting the missing set is exactly {lm_head.weight}.
• minimax_h3_model_loader v1.2.0: optional text_encoder_model field; default-workflow pins bumped; schema regen.
• Linear UI: second "Text Encoder" override picker in the Advanced group; params persist v6→v7 with migration fixtures; metadata + recall.
• Krea-2 isolation: all three consumers of the encoder list (picker hook, modelsLoaded, modelSelected auto-select) now use a Krea-2-scoped guard, with an unmocked regression test proving the H3 encoder is never auto-selected for Krea-2.

Known limitations

• Same all-or-nothing int8 residency as PR 6 (~25.3 GiB free VRAM needed while encoding; it idle-offloads afterward).
• Under partial load the tied lm_head/embeddings split into two tensors (~1.56 GB waste) — documented, not fixed here.
• ⚠ Version ledger: this stack now claims params _version 5 (PR feat(minimax-h3): linear UI — generate-tab t2v/i2v and image output mode (PR 4/5) #143), 6 (PR feat(minimax-h3): single-file pruned/int8-convrot transformer support (PR 6) #145), 7 (this PR); flux2 also claims 5 — second-to-land renumbers.

Testing

Backend 151 passed (H3 suite 46, identification 90 incl. new fixture, workflow-registry 15); ruff 0.11.2 clean. Frontend tsc/eslint/prettier/knip clean, 1722 tests, vite build OK. Real-header dry-run: all 1602 tensors map key-for-key; 350 int8 swaps. Adversarial fresh-context review completed; the one confirmed defect (unscoped Krea-2 auto-select) fixed with regression coverage.

Manual gate: download the encoder file, install by direct path (probes as qwen3_vl_encoder / checkpoint / minimax-h3), select under Advanced → Text Encoder, generate t2v; expect prompt adherence indistinguishable from the folder encoder and session RAM down ~40 GB.

🤖 Generated with Claude Code