joeygambino/MiniMax-H3-encoder-GGUF

MiniMax-H3 Text Encoder — GGUF

GGUF quantizations of the Qwen3-VL-32B vision-language text encoder used by MiniMax-H3 in ComfyUI.

The H3 DiT quants are here: joeygambino/MiniMax-H3-GGUF. You need one file from each repo to run H3 — the DiT alone will not generate anything.

---

Troubleshooting: state_dict / vision mismatch with the -mmproj file

Load these encoders with H3 Clip Loader (Any) from ComfyUI-H3-Multishot, not the stock CLIPLoaderGGUF node.

The H3 text encoder is a truncated Qwen3-VL-32B - 50 layers, no final norm, no lm_head - and its vision tower ships separately as the -mmproj-F16.gguf sidecar. Stock ComfyUI-GGUF only merges an mmproj when the encoder's architecture is qwen2vl; Qwen3-VL reports qwen3vl, so the sidecar is never merged at all, and the resulting missing vision tensors surface as a state_dict mismatch. Its mmproj key map is also qwen2vl-era: wrong merger keys, and no rules for H3's deepstack mergers or split QKV, so even forcing the merge would not line up.

The pack's loader does all three things stock cannot - truncates the text tower to H3's shape, merges the sidecar explicitly, and renames the vision tensors to H3's layout (including remapping deepstack mergers, which llama.cpp indexes by vision layer 8/16/24 and H3 indexes by position 0/1/2).

Keep the -mmproj-F16.gguf in the same folder as the encoder and do not rename either file: they are paired by filename stem.

Why does a .safetensors encoder work without any of this? Because a full safetensors encoder (fp8, int8, NVFP4-AWQ, ...) is a complete, pre-shaped model with its vision tower already inside. It needs no sidecar and no remapping. That is a property of the container, not of the quantization - NVFP4 is not doing anything special here.

Files

File	Size	Use
MiniMax-H3-encoder-Q4_K_M.gguf	19.8 GB	Recommended. ~16.5 GB resident.
MiniMax-H3-encoder-Q5_K_M.gguf	23.2 GB	Higher precision, more VRAM.
MiniMax-H3-encoder-mmproj-F16.gguf	1.2 GB	Multimodal projector — REQUIRED for image input.

The mmproj is not optional if you use reference images

H3's reference-to-video (ref2va) and image-to-video paths feed images into the text encoder. Without mmproj, the encoder is text-only: reference images are ignored and reference/I2V workflows will not behave correctly.

CLIPLoaderGGUF (from ComfyUI-GGUF) auto-pairs the mmproj sidecar by filename, so keep the names exactly as downloaded and put the mmproj in the same folder as the encoder.

---

Install

Place all files in:

ComfyUI/models/text_encoders/
├── MiniMax-H3-encoder-Q4_K_M.gguf
└── MiniMax-H3-encoder-mmproj-F16.gguf

Load with CLIPLoaderGGUF (ComfyUI-GGUF) — or H3ClipLoaderAny from ComfyUI-H3-Multishot, which accepts either .safetensors or .gguf and handles the mmproj pairing.

Set the CLIP type to minimax.

---

VRAM: read this before you file a "it's so slow" issue

The encoder and the DiT do not co-fit on a 32 GB card:

Component	Resident
Encoder (Q4_K_M)	~16.5 GB
H3 DiT	~25 GB

If both are held at once, the DiT loads partially and streams the remainder from system RAM every sampling step. Measured on an RTX 5090: ~60 minutes for a clip that takes ~15 minutes when the DiT is fully resident. The tell in your log is:

loaded partially; 6423 MB usable, 5847 MB loaded, 19363 MB offloaded

Fix: evict the encoder after conditioning and before sampling. Conditioning is already computed at that point, so the encoder weights are safe to drop:

import comfy.model_management as mm
clip.patcher.model.to(mm.text_encoder_offload_device())
mm.free_memory(mm.get_total_memory(mm.get_torch_device()) * 0.9, mm.get_torch_device())
mm.soft_empty_cache()

The multishot sampler in ComfyUI-H3-Multishot does this automatically between shots.

Note that a chained multi-shot workflow re-encodes per shot (each shot conditions on the previous shot's last frame), so the encoder reloads each time — a few seconds per shot, which is far cheaper than streaming ~19 GB every step.

---

Notes on quantization

The encoder is Qwen3-VL-32B, whose tensor dimensions permit K-quants — hence Q4_K_M / Q5_K_M here. The H3 DiT cannot use K-quants (its 2688-wide tensors are not divisible by 256), which is why that repo ships Q4_0 / Q5_1 instead. If you are mixing and matching, that difference is expected, not a packaging error.

---

Also on Civitai

Same files, if you prefer downloading there: MiniMax-H3 Text Encoder GGUF (Qwen3-VL)

Support

Everything here is free and stays free — the format spec, the nodes, the workflows, the cartridges, the LoRAs. If it saved you a night of debugging (it contains several hundred of mine), tips keep the 5090 warm:

• ☕ Buy me a coffee on Ko-fi
• 💛 Sponsor on GitHub
• 🔁 Liberapay (recurring)

---

Credits

• MiniMax-H3 — MiniMaxAI
• Qwen3-VL — Alibaba / Qwen team
• GGUF loader for ComfyUI — city96/ComfyUI-GGUF

Quantized and packaged by joeygambino.