MiniMax H3 NF4 Model Loader / NF4 模型加载

MiniMax H3 - the 33B open-weight model that generates video and synchronized stereo audio in one pass - is a big download either way. The full-precision weights sit around 42.5 GB. If you want a smaller footprint, the pre-quantized BitsAndBytes NF4 weights from DiffSynth-Studio are the alternative, and this is the loader that makes them usable in ComfyUI.

The catch this node exists to solve: DiffSynth's NF4 files don't look like anything ComfyUI can load natively. They store Linear weights as flattened BitsAndBytes tensors with the original matrix shapes hidden away in .quant_state.bitsandbytes__nf4 sidecar metadata. Native ComfyUI can't infer the H3 architecture from those, and it can't restore the quantization state either. The loader parses that metadata, rebuilds the logical shapes, reconstructs the model, and restores the NF4 quant state and DiffSynth's head-interleaved DiT QKV layout - then hands you a normal MODEL output that plugs straight into your H3 sampler graph.

What you need

Drop this file into ComfyUI/models/diffusion_models/:

| File | Size | |---|---| | minimax-h3-fl2va-nf4.safetensors | 17.16 GB |

It replaces the stock UNETLoader - select the file in the model_name combo, connect the MODEL output where the standard loader was connected, and keep the rest of the H3 workflow unchanged. It pairs with the pack's other three loaders for the Qwen3-VL text encoder and the video + audio VAEs.

BitsAndBytes is required, and it's CUDA-only. The loader fails explicitly with a helpful message if it's missing:

python -m pip install "bitsandbytes>=0.50.0"

This is the one node in the pack with a real dependency; the other core tools need nothing extra.

The honest speed tax

NF4 stores Linear weights in 4 bits, so yes, smaller. On the pack's one measured machine (RTX 3090, 864×480, 124 frames, 20 steps): 34.4 GB of files vs 53.9 GB, but 15:34 vs 11:47 - about 36% less disk and about 32% slower. That's not a bug. The weights dequantize back for computation, and a smaller file doesn't mean a faster render.

So the real question is whether the disk savings are worth the runtime. If 17 GB of VRAM-resident model is the difference between fitting on your card or not, NF4 is the path. If you have the room for the Comfy-Org int8_convrot stack, that's the faster route on the tested rig. Treat these as one machine's numbers, not a universal benchmark.

Failure modes that are actually useful

The loader validates aggressively, and the errors are the good kind. It refuses FP4 files, missing quantization sidecars, non-H3 models, missing CUDA, and incomplete downloads - and it's worth calling out the .incomplete and .aria2log artifacts explicitly: those aren't model files, and a half-downloaded checkpoint will fail on purpose rather than silently corrupt. LoRA patches on NF4 Linear layers are not supported. And a reminder that H3 weights carry the MiniMax H3 Community License, which excludes the US, EU, UK and Korea from running the local weights - this loader doesn't change the licensing of what you download.

Install

Part of the MiniMax-H3 Tools pack, which needs ComfyUI 0.30.0+. Search "MiniMax H3 Tools" in ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Rinne414/ComfyUI-MiniMaxH3-Tools.git

Restart ComfyUI and it's under MiniMax H3. It's an independent compatibility layer - not official MiniMax, DiffSynth-Studio, or ComfyUI support - but the NF4 FL2VA stack has been through a full end-to-end run (video plus synchronized audio out the other side), so the happy path is genuinely tested.