ComfyUI-MiniMaxH3-AdaptiveCache Introduction
ComfyUI-MiniMaxH3-AdaptiveCache is a speed-up extension for ComfyUI’s native MiniMax H3 model. It helps reduce the time spent generating audio and video by reusing part of the model’s work when one sampling step is sufficiently similar to a previous step.
The extension offers two nodes:
- MiniMax H3 Adaptive Cache provides presets for everyday use.
- MiniMax H3 Adaptive Cache (Advanced) lets you adjust the caching and quality controls individually.
The extension does not add a new image or video model, and it does not change ComfyUI’s MiniMax H3 model file. It changes how some H3 processing steps are performed. Caching is an approximation: even with the same seed, a cached result will not be pixel-for-pixel identical to a run that calculates every step in full.
For a first quality-and-speed comparison, the author recommends the Balanced preset with cache_device = auto. If a face, character identity, lip movement, sound cue, or fast action must remain especially consistent, start with Safe instead.
How ComfyUI-MiniMaxH3-AdaptiveCache Works
Think of each sampling step as a sequence of editing passes. MiniMax H3 processes audio and video through a stack of blocks. On a full pass, every block runs. On a suitable later pass, Adaptive Cache runs the early blocks again, checks whether the audio and video have changed too much, and reuses a saved result for the remaining blocks.
For example, with a 50-block H3 model and the Balanced preset, a full pass runs all 50 blocks. A cache hit still runs roughly the first 12, but can skip blocks 13–50. The extension also prevents the skipped blocks’ weights from being fetched into GPU memory during that hit.
A cache hit is not automatic. The extension checks where it is in the sampling process, how much the sampling value called sigma has changed, and whether sampled portions of the audio and video states remain similar. It also limits how many cache hits can occur in a row. When a check fails, the model performs a full pass and refreshes the saved result.
Only the target audio and video portions needed for the final output are saved. Conditioning information such as text, reference images, reference video, and reference audio is not saved as part of that cached result. This keeps the cache smaller, particularly in workflows with many references.
Skipping about 76% of blocks on one cache hit does not mean the whole workflow finishes 76% faster. Full passes still occur, and tasks such as text encoding, video decoding or encoding, memory transfers, and file output still take time.
ComfyUI-MiniMaxH3-AdaptiveCache Features
Presets
| Preset | Maximum tail blocks cached | Sampling window | Consecutive cache-hit limit | Content checks | When to try it |
|---|---|---|---|---|---|
| Safe | About 60% | 15%–85% | 1 | Strict audio and video checks | Quality-sensitive shots, identity, rapid motion, lip sync, or complex references |
| Balanced | About 75% | 10%–90% | 2 | Adaptive audio and video checks | A starting point for most workflows |
| Fast | About 84% | 8%–92% | 3 | More permissive audio and video checks | Testing whether greater speed is worth a possible quality change |
| Sigma Only | About 75% | 10%–90% | 2 | Off; checks sigma only | Experiments where you will inspect the output carefully |
A sampling window specifies which portion of sampling is eligible for cache hits. For example, Balanced permits caching between approximately 10% and 90% of the sampling process, provided its other checks pass.
Advanced controls
The Advanced node exposes the settings behind the caching behavior:
| Setting | What it controls | Practical effect |
|---|---|---|
cache_depth | How much of the block stack a hit skips | A larger value can save more work but relies more heavily on the cached result. |
sigma_threshold | The maximum permitted change between adjacent sigma values | A stricter threshold favors full passes when sampling changes more sharply. |
window_start / window_end | Where caching is allowed during sampling | A narrower window leaves more steps fully calculated. |
max_consecutive | How many cache hits can occur in succession | A lower limit forces full refreshes more often. |
quality_guard | Audio-and-video checking, video-only checking, or no content checking | Include audio checks when timing or sound details matter. |
content_multiplier | How permissive the adaptive content check is | Lower values are more conservative. |
content_ceiling | A hard limit on detected content change | Helps reject a sudden change even before the adaptive check has much history. |
cache_device | Whether the saved result stays on gpu, cpu, or is chosen by auto | GPU can be quicker to read; CPU can reduce GPU-memory pressure. |
gpu_safety_mb | GPU memory reserved when using auto | More reserved memory makes auto less likely to keep the cache on the GPU. |
The content check samples small portions of both audio and video rather than scanning the entire sequence. By default, it gives video 80% of the combined weight and audio 20%.
Cache location
gpukeeps the saved result in video memory for quick access, but it can consume hundreds of megabytes at higher resolutions.cpukeeps it in pinned system memory and, on CUDA systems, attempts to move it back while the early blocks run.autochooses GPU only when the saved result and a safety margin fit in currently available video memory; otherwise, it chooses CPU.
For a 16 GB graphics card, the author recommends trying auto first.
Workflow connections
Place the Adaptive Cache node after H3’s UNETLoader, then send its MODEL output to both the scheduler and the guider:
UNETLoader
↓
MiniMax H3 Adaptive Cache
├─→ BasicScheduler
└─→ BasicGuider / CFGGuider
Both branches must use the cached node’s MODEL output. Connecting only one branch can leave a workflow that looks complete but behaves incorrectly. The included examples/video_minimax_h3_i2v_adaptive_cache.json is an image-to-video workflow example.
Working with Sol-Attn
Adaptive Cache can be combined with the separate Kijai Sol-Attn extension. Sol-Attn reduces the cost of attention inside blocks that run; Adaptive Cache skips eligible later blocks. The recommended order is:
UNETLoader
↓
Patch Sol-Attn
↓
MiniMax H3 Adaptive Cache
├─→ BasicScheduler
└─→ BasicGuider / CFGGuider
Set Sol-Attn’s morton option to false. Morton rearranges video data and expects it to be restored after the last block. A cache hit may skip that restoration point. Starting with version 0.1.1, Adaptive Cache detects Morton mode and safely steps aside: Sol-Attn continues to work, but all H3 blocks run and Adaptive Cache neither saves nor reuses a cached result.
For a quality-first combination, the author suggests starting with Sol-Attn’s morton = false, use_tma = false, int8_qk = false, and sink_conditioning = exact_kv_and_rows, alongside Adaptive Cache’s Balanced preset and cache_device = auto. Check quality before experimenting with INT8 or several approximation settings at once. Other extensions that replace H3’s same block-level processing point are not recommended alongside Adaptive Cache.
Performance and quality expectations
In the author’s repeated RTX 5090 test, a 20-step, 1376 × 768, 124-frame workflow averaged 297.32 seconds without these accelerations, 186.24 seconds with Balanced Adaptive Cache, and 121.89 seconds with Sol-Attn plus Adaptive Cache. Each configuration was run twice. In that test, a typical Balanced run had 10 full passes and 10 cache hits, reducing total block executions by 38%.
Earlier single-run RTX 4090 observations varied substantially and should not be treated as reliable speed predictions. GPU, resolution, frame count, model format, compilation, run order, and other workflow costs all affect the result. To compare settings on your own machine, keep the seed, prompt, inputs, model, resolution, frame count, and sampler settings fixed; warm up each configuration; then compare several runs and inspect the resulting video and audio.
The extension can run alongside Turbo LoRA or a Turbo sampler, but speed compatibility is not a quality guarantee. Some Turbo-4 samples in the author’s W4A8 mixed-quantization test showed visible quality problems, especially with additional approximations. The available tests do not establish whether Adaptive Cache caused those problems. Check your quantized model’s Turbo output on its own before adding caching, and compare identical inputs and seeds when evaluating quality.
After sampling, the extension prints statistics to the console, including full passes, cache hits, executed and skipped blocks, content-check rejections, cache location, and Morton-related bypasses. “Block reduction” measures block work avoided, not total workflow speed gained.
What’s New with ComfyUI-MiniMaxH3-AdaptiveCache
The documented current version is 0.1.1. The provided information identifies one specific change beginning with this version:
- Sol-Attn Morton safety handling: When Morton mode is enabled, Adaptive Cache automatically bypasses caching, runs every H3 block, and avoids saving or reusing a cached result. A console warning and call statistics make the bypass visible. This prevents the extension from relying on video data being restored by a block it might otherwise skip.
No earlier version-by-version change list is provided.
Troubleshooting ComfyUI-MiniMaxH3-AdaptiveCache
The workflow runs, but the result seems wrong
- Check that both
BasicSchedulerandBasicGuiderorCFGGuiderreceive the Adaptive Cache node’s MODEL output. - Compare the result against a run without Adaptive Cache using the same inputs and seed.
- Try Safe if the difference involves faces, character identity, rapid movement, hard cuts, lip sync, sound timing, or complex Ref2VA references.
Sol-Attn works, but Adaptive Cache does not seem to skip blocks
- Check whether Sol-Attn’s
mortonoption is enabled. - Set
morton = falsewhen combining the two extensions. - Run the workflow again and inspect Adaptive Cache’s console statistics. With Morton enabled, its safety bypass deliberately runs all blocks.
The GPU runs low on memory
- Set
cache_device = auto, especially if you are using a 16 GB graphics card. - If memory pressure continues, try
cache_device = cpu. - Expect a possible speed tradeoff: CPU storage reduces GPU-memory use but requires transfers.
The speed-up is smaller than expected
- Check the console’s full-pass and cache-hit counts. A block can be skipped only when a cache check succeeds.
- Compare total workflow time separately from block-reduction statistics.
- Warm up each configuration, then make several comparable runs. New resolutions or processing shapes can incur substantial one-time compilation or tuning costs.
- Keep other settings fixed while testing. The author’s measurements show that a single run can give a misleading impression of performance.
ComfyUI reports a compatibility error
The extension relies on internal interfaces in ComfyUI’s native MiniMax H3 implementation. If those interfaces change, the extension is designed to report an error. Confirm that the workflow uses native H3 and check whether a ComfyUI update changed its H3 support. Also review other block-patching or skip-block nodes in the workflow, since they may compete for the same extension point.
Frequently asked questions
Will this produce exactly the same output as a full H3 run?
No. Adaptive caching is a lossy approximation, so matching seeds do not guarantee pixel-identical results.
Does Fast always finish sooner than Balanced?
Not necessarily. Presets affect which passes may use the cache; actual hits, memory transfers, and other workflow stages determine total time.
Should I use Sigma Only for finished work?
It turns off the audio and video content checks. Use it only when you are prepared to inspect the result carefully and compare it with a more conservative setting.
Can I combine it with Turbo?
The execution paths can work together, and the author observed additional speed gains. Quality needs separate evaluation, particularly with the W4A8 model format used in the documented Turbo tests.
Does this extension include Sol-Attn?
No. Sol-Attn is a separate extension.
Learn More about ComfyUI-MiniMaxH3-AdaptiveCache
- Included image-to-video example:
examples/video_minimax_h3_i2v_adaptive_cache.jsonshows how the cached MODEL output connects to both the scheduler and guider. - Kijai Sol-Attn: Read its documentation if you plan to combine attention acceleration with Adaptive Cache. Keep its Morton option off for caching.
- Console statistics: Use the extension’s per-sampling report to understand when caching happened and whether content checks or Morton safety handling changed the expected behavior.
