MiniMax H3 Qwen Reference Prefix Cache / 参考前缀缓存 (Advanced)

MiniMax H3's text encoder is a Qwen3-VL vision-language model, and running reference images and videos through a VLM vision tower is not free - it's some of the most expensive tensor work in your graph outside sampling itself. This node is an opt-in, bounded cache for the visual-reference prefix of that encoder: same reference frames in, cached tokens out, prompt text still freshly computed every time. If you batch or iterate on the same reference, that's the exact part worth caching.

The design is careful in a way that matters if you've been burned by custom nodes before. It wraps only this CLIP object's output and never patches ComfyUI core files, never mutates the input CLIP. It's a wrapper you can take out of the graph and your workflow is bit-identical. And it's opt-in: the default mode is report_only, which computes and reports but doesn't actually cache. You have to switch to memory_lru_exp to turn the cache on.

Inputs that matter

• clip - the H3 CLIP (Qwen3-VL) object. Required.
• mode - report_only (default, safe) or memory_lru_exp (the actual cache).
• max_entries - how many distinct reference prefixes to keep (1–16, default 1). If you alternate two reference videos, bump this or you'll thrash.
• maximum_cache_mib - the cap, default 1024 MiB, range 64–65536. This is CPU memory, not VRAM.
• cache_epoch - increment to start a fresh empty cache without touching the input CLIP. Handy when you're A/B-ing references and want a clean comparison.

Outputs: the wrapped clip, a cache_handle (the typed handle the Stats node reads), and report_json.

Installing

Part of T8mars MiniMax H3 Audio T8:

cd ComfyUI/custom_nodes
git clone https://github.com/T8mars/comfyui-minimax-h3-audio-T8

or ComfyUI Manager → search "MiniMax H3 Audio T8" → restart. No pip deps; the cache is pure in-process Python + the CLIP you already loaded.

When it's actually worth it

Honestly? Only when your reference repeats. The pack's own framing is that this exists for iteration-heavy work - generating seed variants of the same I2VA/Ref2VA scene, or re-running a clip with the same first frame. In that case caching the vision prefix can shave real wall-clock time off every run after the first. For one-off generation with unique references, leave mode at report_only and it costs you nothing but a report line.

The thing to watch is the max_entries/maximum_cache_mib interaction. One 1088×544 reference's vision prefix is already fat; a handful of long reference videos can eat your whole 1 GiB default budget. Read report_json from the sibling MiniMaxH3QwenPrefixCacheStatsT8Advanced node - that's the honest way to see whether your hit rate justifies the RAM. If the counter says you're getting hits and staying under budget, this is a quiet win on repeat runs. If it says you're missing every time, turn it off and don't look back.