feat(minimax-h3): single-file pruned/int8-convrot transformer support (PR 6)

[lstein]

Note

Port of lstein#145 to the InvokeAI-7 tree. Mechanical replay of the original commits onto v7 main (4a48a37967); openapi.json/schema.ts regenerated and verified drift-free at every level, and the dependencies.py auto-merge verified by hand. All changes target the backend and the existing frontend/web app - webv2 is untouched (H3 support in the new UI is future work). Review history and test notes live on the original PR.

Summary

PR 6 of the MiniMax H3 stack (on top of lstein#144): load Comfy-Org single-file H3 transformers — including the pruned int8-convrot fl2va (19.5 GiB) — as a checkpoint-format main model that overrides the transformer while the diffusers folder keeps providing the text encoder, tokenizer/processor, and both VAEs.

Why: the bf16 folder transformer is 62 GiB — on a 48 GB card only ~53% stays resident and every denoise step streams ~30 GiB from RAM. The pruned int8 file is fully resident with room to spare, and has ~40% fewer FLOPs (the AdaLN branches are replaced by a precomputed rank-8 time-embedding curve).

Format support (semantics verified against Comfy-Org/comfy-quants, comfy-kitchen, and ComfyUI's model code — reimplemented, not copied)

• int8_tensorwise: per-output-channel symmetric int8 + fp32 scales, declared by <layer>.comfy_quant JSON markers. Weights stay int8 in VRAM (Int8ConvrotLinear buffers); dequant happens per forward in the compute dtype (~620 MB transient at the largest layer).
• convrot: grouped-256 regular-Hadamard rotation folded into the stored weights. The Hadamard is symmetric orthonormal, so derotation is the same grouped matmul — no runtime activation rotation. Roundtrip pinned by tests against a reference quantizer.
• Pruned "AdaLN curves": adaln_t_table [1025, 8] lerped at t∈[0,1] replaces the time embedder; rank-8 AdaLN projections, no silu, fp32 modulation. Implemented as a subclass of the vendored transformer (vendored file untouched). Timestep-domain equivalence with ComfyUI verified in review (t = 1−σ, keyframe pin 0.999, unique-t dedup).
• The full bf16 and pruned bf16 single files load through the same path (time-embedder renames verified against the real HF file header via range request; the no-marker path skips the int8 swap).
• fp8-scaled files are rejected early (header-only marker check) with a clear unsupported-quantization error. GGUF: out of scope. ref2va files are rejected by filename (keys are indistinguishable from fl2va).

Wiring

• Main_Checkpoint_MiniMaxH3_Config (fingerprint: audio_patch_proj.weight + video_patch_proj.weight + blocks.0.attn.qkv_proj.weight — checked for collisions against every other family's single-file fingerprint, both directions); identification fixture included.
• The checkpoint loader serves ONLY SubModelType.Transformer (Wan-GGUF precedent) and errors helpfully for anything else; shape-inferred config (verified key-for-key/shape-for-shape against the real 19.5 GiB header).
• minimax_h3_model_loader v1.1.0: optional transformer_model field (checkpoint-format H3 mains); default workflows' pinned versions bumped.
• Linear UI: "Transformer (single file)" combobox in Generation Settings → Advanced (gated on H3); checkpoint mains hidden from the main model picker; metadata recall for the override (skips silently if the model was uninstalled); params persist v5→v6 with migration fixtures.

Known limitations (review-documented)

• Int8 layers are not autocast-wrapped: residency is all-or-nothing, so the single file needs ~20 GiB free VRAM. Graceful partial-load degradation remains the folder model's job.
• ⚠ Version-collision ledger: upstream main is still params _version 4; this stack claims v5 (PR 4) and v6 (this PR), and the flux2 branch also claims v5 — whichever lands second renumbers.
• A pre-existing global gap (all estimators): user-set max_cache_vram_gb bypasses working-memory reservations.

Testing

• Backend: H3 suite 40 tests + identification (incl. new fixture) + workflow-registry — 144 passed; ruff (CI-pinned 0.11.2) clean.
• Frontend: tsc / eslint / prettier / knip clean; 1720 tests passed; vite build OK. Schema regen committed (node field).
• Adversarial fresh-context review completed; all findings fixed (full-file claim-then-crash, early fp8 rejection, dequant transient, modulation dtype, recall handler) or documented (all-or-nothing residency).
• Manual gate: install the single file by direct path (probes as minimax-h3 / checkpoint / fl2va, pruned), select it under Advanced → Transformer (single file), run t2v; expect ~31 GiB VRAM steady state and no per-step streaming.

🤖 Generated with Claude Code