MiniMax H3 Ref2VA Accelerator

MiniMax H3 is a 33B omni-modal video model, and it runs like one. On the author's test rig - a 32 GB RTX 5090 with pruned BF16 weights - a single 10-second Ref2VA generation at 20 steps took 14 minutes 43 seconds natively. This node, the MiniMax H3 Ref2VA Accelerator, got the same clip down to about 11 minutes by reusing chunks of the transformer between steps. That's a ~25% cut, of the honest kind: the README leads with the disclaimer that this is an approximate accelerator, not bit-identical inference. Need the exact native trajectory? Bypass it or use Observe Only (no caching).

One scope note before you expect magic. "Ref2VA" is H3's reference-conditioned editing layout - reference video and audio in, regenerated target out. The node only engages when that payload reaches the sampler; on plain text-to-video or image-to-video it deliberately stays idle, and the console summary says so explicitly.

How it works: block caching with guard rails

H3's diffusion transformer runs 50 blocks per step. This node guarantees block 0 always runs and makes the rest conditional. After a full pass it stores the residual contributed by blocks 1-49. On the next step, it runs block 0, compares the fresh residual against the stored one across six fp32 metrics - global change, target-video, target-audio, visual-reference, reference-audio, and a worst-frame temporal check - and if all sit under their thresholds, it reuses the cached tail instead of recomputing blocks 1-49. Any guard failing means a full native step.

Two design decisions stand out. Every preset sets max_consecutive_hits to 1, so back-to-back cached steps are impossible - a real full pass always sits between hits. And it refuses to install at all if it detects another DiT block replacement already patched into the branch (TeaCache, CacheDiT, T8, Spectrum-style nodes), raising instead of silently stacking. More polite than most. SageAttention-style attention patches are fine - different layer.

The inputs that matter

• model - your native MiniMaxH3Model; anything else gets a clear rejection error.
• mode - Ref2VA Balanced is the recommended default. Conservative and Ultra Safe (quality-first) trade speed for less drift on keeper shots; Aggressive is the faster-but-experimental one; Observe Only collects metrics without caching (handy for calibration).
• cache_storage - CPU (VRAM-safe) for pruned/offloaded BF16 checkpoints, which is the production recommendation. GPU only earns its VRAM if a small/quantized checkpoint leaves comfortable headroom.
• debug - off, unless you're digging into why a step cached or didn't.

The trap for beginners: those threshold floats (global_threshold, video_threshold, the reference thresholds, start_percent/end_percent, max_consecutive_hits) only do anything in Custom mode. Presets use their own internal values; the visible numbers are cosmetic until you flip the dropdown. Same for the experimental Advanced controls - tail_rescale (leave off; testing found no quality win) and cpu_tail_compute (Safe CPU is the default and the author's pick; "Auto GPU Fast Path" saved about 2 seconds on an 11-minute run).

The output is one patched MODEL that must feed the whole downstream guider/scheduler path - any branch that bypasses it simply isn't accelerated.

Installing

Via ComfyUI Manager, search H3 Ref2VA Accelerator, install, restart. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/BMB12d3/ComfyUI-H3-Ref2VA-Accelerator.git
# restart ComfyUI

No extra Python packages - it depends only on ComfyUI and PyTorch. One upgrade gotcha: if you previously installed a legacy ZIP whose folder is named ComfyUI-H3-RefBlockCache, delete or rename it first. Both register the same node class ID, and two copies in custom_nodes means duplicate registration.

Where it slots in, per the README:

H3 diffusion model
  -> Memory Efficient Sage Attention (optional)
  -> ModelSamplingMiniMaxH3 / sigma shift
  -> MiniMax H3 Ref2VA Accelerator
  -> Basic Guider + Basic Scheduler
  -> RES Multistep

Common issues

• "Only supports native ComfyUI MiniMaxH3Model" - the loader isn't handing you a native H3 model, or a wrapper swapped the class.
• "Found an existing DiT block replacement" - a competing block-cache node is in the branch. Remove one of them; they don't stack.
• Summary says it ran "without a Ref2VA payload" - nothing cached, by design. Your workflow is plain T2V/I2V, or the references aren't reaching the sampler.
• "Required guard metric(s) unavailable" - usually a native H3 layout change after a ComfyUI update. Caching disables itself for safety; run Observe Only with debug on.
• Output differs from native - expected, since cache hits approximate. Conservative or Ultra Safe shrink the drift; bypassing is the only way to zero it.
• Little or no speedup - content with big step-to-step changes can legitimately keep failing the guards. Read the console summary for the cache-hit count before blaming the node.

Remember this only helps you if you can legally run the H3 weights - MiniMax's community license excludes the US, EU, UK, and Korea from local use. And the repo itself ships with no license file, so treat the code as all-rights-reserved.