VAE Loader (GGUF)

Here's the thing you need to know before you get excited: VAE Loader (GGUF) does not load "GGUF VAEs" in general. It loads exactly one thing - a MiniMax H3 video VAE converted with this pack's Q8_CR format. Point it at anything else and it raises a ValueError explaining exactly that. It's a specialist tool, not a general-purpose drop-in for your models/vae folder.

So why does it exist at all? MiniMax H3 video generation is heavy, and the video VAE is a genuine VRAM line item. Shrinking the decoder's Linear weights to INT8 lets the whole stack sit tighter on a consumer card, and on a workflow that's already pushing its luck, a few GB less in the VAE can be the difference between rendering and OOM. If you're not doing MiniMax H3 video, you can skip this node entirely and keep using the normal VAE loader.

How it works

The loader reads a .gguf file from models/vae and checks its architecture string. It must be minimax_h3_vae, and the quant mode must be int8_convrot (i.e. Q8_CR) - the loader enforces both. The GGML-format tensors are dequantized back to float, then the VAE is built through ComfyUI's MiniMax H3 path with the INT8 ConvRot ops injected, so the decoder's 2-D Linear layers keep their native INT8 execution. Convolutions, norms, and buffers stay floating point.

You don't convert this yourself from scratch if you'd rather not. The pack ships tools/convert.py, and the README gives the one-liner for a MiniMax H3 video VAE checkpoint:

python tools/convert.py --src /path/to/minimax_h3_video_vae_fp16.safetensors \
  --dst /path/to/minimax_h3_video_vae-Q8_CR.gguf --quant-type Q8_CR

Drop the result in ComfyUI/models/vae.

The input that matters

Just one: vae_name, a dropdown of the .gguf files it sees in models/vae. Select your file and the output is a standard VAE that plugs into VAE Decode exactly like any other. That's the entire interface - refreshingly small for what it's doing under the hood.

Installing

Search ComfyUI-GGUF in the ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/molbal/ComfyUI-GGUF

Restart ComfyUI and run pip install --upgrade gguf (the pack's one hard dependency). ComfyUI v0.27.0+ is required for the native INT8 path.

Where people get burned

• Wrong file, hard error. If you drop a non-MiniMax VAE GGUF in and select it, you get an exception, not a fallback. That's by design - read the error message and use the right node for the right VAE.
• Old or mismatched ComfyUI. Current builds use ComfyUI's injected MiniMax H3 VAE ops directly; older compatible builds fall back to the loader injecting them at construction time. If your build is neither, the loader refuses.
• Q8_CR version drift. If you converted your VAE before ConvRot weights were marked as pre-rotated, older files load via the non-rotated INT8 path instead. It still works, it's just not the fast path.
• And the general pack gotcha: this fork doesn't support _K quants on anything but text encoders, so don't try to feed a Q4_K_M anything into this loader.