ComfyUI MiniMax H3 Hybrid Loader
A custom ComfyUI node that loads a MiniMax H3 (audio+video DiT) checkpoint by merging selected tensor groups from a second "overlay" checkpoint onto a "base" checkpoint, then hands the merged state dict to ComfyUI's stock load_diffusion_model_state_dict. The result is indistinguishable from a model loaded by Load Diffusion Model — same detection, same patcher, same multigpu deepclone support.
Why
Minimax shipped two MiniMax H3 checkpoints with identical weight layout:
minimax_h3_fl2va — trained on first/last-keyframe conditioning only; Minimax reports noticeably higher output quality.minimax_h3_ref2va — additionally trained on multimodal reference conditioning (image / video / audio references), but a confirmed training-quality issue makes its raw output worse.
A tensor-by-tensor comparison (see minimax_h3_analysis.md) shows >97% of the weights (attention QKV/O, MLPs, RMSNorms, patch projections, rope, token refiner) are bit-identical or cosine ≥ 0.9997 between the two. The only sub-component that differs meaningfully is the per-block adaln_proj.linear.* weights — the AdaLN modulation projections that route text / audio / video / reference modality tags through the residual stream — plus the final_layer.adaln_proj.linear.* weight (the single most discordant tensor in the model) and, to a lesser degree, the video_out / audio_out output heads.
So a promising hybrid is: load fl2va as the base (high-quality attention, MLPs, and output heads), and overlay only the per-block adaln_proj weights from ref2va (preserving the reference-conditioning pathway). This node exposes that configuration as its default preset, plus several coarser / finer presets and an explicit custom glob string so you can experiment.
Recommended Settings for Higher Ref2VA Quality:
After testing this is what I, subjectively, think is the best in terms of reference capability and visual/audio quality:
- fl2va model as base
- ref2va model as overlay
- block_range_adaln overlay preset
- block_range_start set to 25 (30 in screenshot, but 25 may be a better compromise between quality and reference retention)
- block_range_end set to 49
All other settings default
Features
- Memory-friendly: both safetensors files are opened mmap-backed and tensors are streamed one key at a time. Peak RSS is one model's worth (~19.5 GB for the int8 checkpoints), not 2× — the same as the stock loader.
- Read-only: neither safetensors file is mutated on disk.
- Stock-compatible: behaves exactly like
Load Diffusion Model when overlay_preset == "none".
- Quantization-aware: int8
.comfy_quant siblings always co-travel with the weight they belong to.
Presets
| Preset |
What it does |
none |
Pure base loading (equivalent to stock UNETLoader). |
ref2va_adaln_over_fl2va |
Take per-block adaln_proj.linear.* from the overlay only. The recommended hybrid. |
ref2va_all_adaln_over_fl2va |
Also take final_layer.adaln_proj from the overlay. "Max-reference, accept-quality-loss" knob. |
ref2va_full_over_fl2va / fl2va_full_over_ref2va |
Take everything from the overlay (sanity checks). |
block_range_adaln (default) |
Take adaln_proj only for blocks in [block_range_start, block_range_end] (inclusive, 0..49). |
custom |
Use custom_overlays / custom_base only. |
block_range_start / block_range_end — Only used with block_range_adaln. The MiniMax H3 DiT has 50 blocks indexed 0..49.final_adaln_from_overlay — Additive toggle (independent of preset) to pull final_layer.adaln_proj.linear.* from the overlay on top of whatever the preset already does.custom_overlays — Comma-separated keys / prefixes / globs to also take from the overlay on top of the preset. Bare prefixes ending in . match by prefix (e.g. blocks.49.); other strings are matched as fnmatch globs (e.g. blocks.[0-4].*.attn.qkv_proj.weight).custom_base — Comma-separated keys / prefixes / globs to force back to the base even if the preset or custom_overlays would take them from the overlay.weight_dtype — Same meaning as the stock Load Diffusion Model node (default, fp8_e4m3fn, fp8_e4m3fn_fast, fp8_e5m2).
Installation
Drop this repository into ComfyUI/custom_nodes/ and restart ComfyUI. The node appears under the model/loaders category as MiniMax H3 Hybrid Loader.
Further reading
The full per-tensor comparison of ref2va vs fl2va, including per-block trends and the rationale for each suggested hybrid configuration, is in minimax_h3_analysis.md.
一个自定义 ComfyUI 节点，通过把第二个“叠加”检查点中选定的张量组合并到“基础”检查点上，来加载 MiniMax H3（音频+视频 DiT）检查点，生成的混合模型会被 ComfyUI 完全当作普通加载的模型对待。