ComfyUI_MinimaxH3HybridLoader README

The project's README from github.com/scottmudge/ComfyUI_MinimaxH3HybridLoader. As one markdown file: README.md.

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:

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.

good_settings

After testing this is what I, subjectively, think is the best in terms of reference capability and visual/audio quality:

All other settings default

Features

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.

Optional inputs

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_MinimaxH3HybridLoader (scottmudge/ComfyUI_MinimaxH3HybridLoader)

Searching Database…

What is this?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, producing a hybrid that ComfyUI treats exactly like a normal loaded model.
Is this a standalone app or does it plug into something else?It is a custom node (plugin) for ComfyUI, not a standalone program — it adds a new loader node to ComfyUI's model/loaders category.
Do I need specific checkpoints to use this?Yes — you need both the MiniMax H3 fl2va and ref2va safetensors checkpoints, since the node specifically merges tensor groups between those two models.
Does loading two checkpoints double my memory usage?No — both safetensors files are mmap-backed and streamed tensor-by-tensor, so peak memory stays at roughly one model's worth (~19.5GB for int8 checkpoints), the same as the stock loader.
What's the recommended hybrid setup?Use fl2va as the base and overlay only the per-block AdaLN modulation weights from ref2va for blocks 25 through 49 — the author found this balances output quality with retained reference-conditioning ability.
What does the 'none' preset do?It performs pure base-checkpoint loading, equivalent to ComfyUI's stock UNETLoader, with nothing taken from the overlay checkpoint.
Does using this modify my original checkpoint files?No, both safetensors files are opened read-only and are never written to or mutated on disk.
Why do the two MiniMax checkpoints need hybridizing at all?fl2va and ref2va share over 97% identical weights, but fl2va has higher output quality while ref2va alone has a known training-quality issue despite adding multimodal reference conditioning — blending lets you keep fl2va's quality while recovering ref2va's reference capability.
Creator
scottmudge
Size
0.1 MB
Stars
180
Updated
CommitAug 11
Age
2mo
Commits · 90 Days