MiniMax H3 Adaptive Cache

If you've run MiniMax H3 in ComfyUI you know the feeling: a 33B omni-modal model that writes picture and stereo audio together is a genuine marvel and a genuine time sink. The launch threads filled up with people asking how long a render would take on a normal card. This node is aimed squarely at that problem. It's a content-aware cache for ComfyUI's native MiniMax H3 support - no API, no key, no third-party Python dependencies. You clone it, drop it on your model, and it starts skipping work.

What it actually does

H3's DiT runs dozens of blocks per sampling step, and adjacent steps are usually doing nearly the same thing. The trick is an old one - think DeepCache / block-skip from the image-model days, but gated on content. Every call still recomputes the front blocks (the "warm" prefix - about 12 of 50 on Balanced). When a full call finishes it stores tail_residual = final_target − warm_target for the audio/video rows, and on later steps that look similar enough it applies that residual to skip the remaining ~38 tail blocks entirely.

The plugin doesn't modify ComfyUI's model.py and runs no core patch script. It registers one wrapper per block on H3's existing ("double_block", index) extension point, plus a prefetch guard so skipped tail blocks aren't even streamed into VRAM. Skipped blocks don't just save compute - they save memory traffic, which matters when the weights run to tens of gigabytes.

How it decides to skip

It doesn't compare full frames. It samples a handful of tokens and channels from the target audio and video, computes a symmetric relative change since the last step, and only caches a hit when the delta stays under both a moving-EMA threshold and a hard ceiling, with video weighted about 80/20 over audio. That's why it's "adaptive" rather than a blind skip-every-other-step hack. It only caches the target audio/video regions the final output layer reads; text, first/last-frame conditions and reference images aren't cached at all.

Worth stating plainly: this is a lossy approximation. Same seed won't give you pixel-identical output to a full run, and it's clearly meant for drafts and iteration, not your final money shot.

The inputs that matter

You get exactly three knobs plus the model. preset is the one you'll touch: safe, balanced, fast, or sigma_only. Balanced is the default and the right starting point. Safe skips less (about 60% max) and enforces the strictest content checks - use it when a face or character identity must stay stable, or with fast motion, explosions, hard cuts, dialogue lip-sync, or complicated multi-reference Ref2VA. Fast skips more (~84%) with looser checks. sigma_only is basically the guard turned off - it decides purely on noise level, which is fast but the least safe.

cache_device is the other one: auto keeps the cached residual on GPU only when enough VRAM is free and falls back to pinned CPU memory otherwise. On a 16GB card, leave it on auto - residuals at higher resolutions can eat hundreds of MB.

Where it goes in your workflow

UNETLoader
   ↓
MiniMax H3 Adaptive Cache   →  MODEL out
   ├─→ BasicScheduler
   └─→ BasicGuider / CFGGuider

The output is a single patched MODEL. The catch: both the scheduler and the guider must consume it. Wire only one branch and you get a workflow that's structurally complete but logically wrong - the README calls this out as the #1 way people mis-connect it.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/FFFFFFpy/ComfyUI-MiniMaxH3-AdaptiveCache

Restart ComfyUI. That's the whole install - no pip dependencies, and it's also in ComfyUI Manager under "ComfyUI-MiniMaxH3-AdaptiveCache". The real prerequisite is ComfyUI's native MiniMax H3 support itself, and the model: H3's weights are big (~42GB class), so this is a "you already run H3 on a big GPU" optimization, not a way to squeeze it onto a 3060.

Console stats & troubleshooting

After each run the node prints honest stats: full vs. cached calls, blocks executed vs. skipped, content-guard rejects, and where the residual landed. A typical Balanced run reads full=10, cache=10, executed=620/1000 blocks, block reduction=38%. Read that number carefully: block reduction is not end-to-end speedup (VAE, text encoding and video muxing still cost real time), and your first run at a new resolution is slower while Triton/autotune caches warm up. In the author's RTX 5090 benchmark, Balanced alone hit ~1.6× at 20 steps, and combined with Sol-Attn (Morton off) ~2.44× - real, but not 38% off your wall clock.

It refuses loudly if you feed it anything that isn't ComfyUI's native MiniMax H3, or if your ComfyUI build lacks the OUTER_SAMPLE wrapper API it needs. And don't stack another block-skip or cache node that patches H3's double_block points onto the same model - that's one shared extension point, and only one of you gets to win.