MiniMax H3 BlockSwap Args

H3's DiT has 50 transformer blocks, and a plain bf16 checkpoint is around 42 GB. If you're on a 24 GB card, or an 8 GB one, you cannot hold all of that in VRAM at once - full stop. BlockSwap is the answer, and it's the same trick the llama.cpp crowd uses for huge LLMs: keep some blocks on the GPU, some in system RAM, and stream the rest from disk on demand, swapping them through as the sampler walks the model. This node is the configuration for that swap, and it's the difference between "won't run" and "runs, slowly but actually works."

How it works

The model loader streams blocks lazily; this node tells the sampler how to stage them. block_to_swap is the headline number: with 50 total blocks, setting it to 47 (the default) means only 3 blocks stay resident on GPU and 47 live in the CPU home pool - then prefetch reads the next block window from disk into RAM in the background while the GPU chews on the current one. hot_blocks pins leading blocks permanently on GPU so they never pay the H2D/D2H transfer tax every pass. It's a ring buffer, sized against your VRAM, with auto_vram (default on) estimating your activation/ComfyUI overhead and reserving before allocating the pool.

The trade-off is honesty: you trade VRAM for bandwidth. Swapping 47 blocks every pass is disk- and RAM-bound work - it's why the README recommends an SSD and why the KSampler's stats output shows swap hits and loads so you can watch the thrash.

The inputs that matter

• block_to_swap - default 47, range 0–50. How many of the 50 blocks live off-GPU. 0 keeps everything resident (only for beefy cards). This is the knob you tune to your VRAM.
• auto_vram - default True. Automatically reserves estimated activation/ComfyUI VRAM and runtime LoRA space before allocating the pool. Disable only if you want the raw values used exactly as typed.
• prefetch (default True) and prefetch_count (default 2) - background disk→RAM prefetch of the next window; slots reserved in the home pool.
• hot_blocks - leading blocks pinned on GPU, avoiding repeated transfers. Capped at resident-window − 1.
• pin_memory (default True) - pinned memory for staging/prefetch transfers.
• disk_workers - background disk read threads, default 2.
• dtype - bfloat16 (recommended), float16 (older GPUs), float32 (debugging).

One output: block_swap_args, a MINIMAX_H3_SWAP, wired into the KSampler's optional socket.

Installing it

Pack-wide routine - ComfyUI Manager search "MiniMax H3", or:

cd ComfyUI/custom_nodes
git clone https://github.com/xiaolibai-sys/ComfyUI-MiniMaxH3
pip install -r requirements.txt

then restart. No models needed by the node itself - it configures how the already-loaded model is staged.

Common issues

• Swapping but still OOM. Crank block_to_swap up toward the max and make sure auto_vram is on; if it's already at 47, the problem is your activations, not the weights - drop resolution.
• Painfully slow. BlockSwap is I/O-bound by design. An SSD matters enormously; a spinning disk makes prefetch pointless. stats in the KSampler shows swap_hits/swap_loads/peak_vram so you can see what's bottlenecking.
• float16 on an old card. If you're on pre-BF16-era hardware, float16 is the call - the tooltip says so.
• Believing it's a free lunch. It isn't - it's the low-VRAM path. The README and every "will my card run it?" thread agree: this makes it possible, not fast.