JR MiniMax H3 Hybrid Loader

If you run MiniMax H3 in ComfyUI you've probably noticed the model folder fills up fast - a full FL2VA checkpoint plus a REF2VA checkpoint is a lot of gigabytes, and loading both through the stock loader means keeping two models' worth of state in mind even when you only ever use one at a time. The JR H3 Hybrid Loader is this pack's answer to that: it loads one FL2VA checkpoint as the full native base and overlays a handful of REF2VA AdaLN parameters on top, so you get one MODEL output, not two.

The name is doing a lot of work, so let's be precise about what "hybrid" means here. It is not two models concatenated or blended. The FL checkpoint is the only complete base - architecture, output heads, metadata, everything. The REF checkpoint contributes only the tensor families the profile explicitly selects (by default the AdaLN blocks in a range like 25–49). It's a parameter-source strategy, not dual-model loading. On the inside the node reads both safetensors headers first to build a deterministic "hybrid plan," validates that the selected families match in key, shape, and dtype, then loads FL through ComfyUI's normal load_torch_file path while reading only the planned REF tensors before closing the REF handle. The whole result gets handed to the stock load_diffusion_model_state_dict, so you keep ComfyUI's normal model identification, ModelPatcher, and dynamic VRAM behavior.

The profile dropdown is where the action is

profile defaults to Recommended, which pulls AdaLN blocks 25–49 from REF and leaves the final AdaLN plus the video/audio output heads on FL. That specific range is an experimental suggestion from Scott Mudge's project - not a MiniMax official recommendation, and the README is upfront about it. Your other choices: All Block AdaLN (blocks 0–49 from REF, final from FL), All Block AdaLN + Final (also swap the final AdaLN), Custom Range (drive block_range_start / block_range_end and a final_adaln_from_ref toggle), Pure FL / Pure REF (just calls the stock loader on one file, no hybrid at all), and Advanced Custom for prefix/glob overrides.

The two filename dropdowns (fl_model_name, ref_model_name) enumerate your ComfyUI/models/diffusion_models folder directly, and weight_dtype lets you pick a quant representation (default, or fp8 variants). One gotcha the README is loud about: bf16 and the different INT8 representations of AdaLN differ so much in memory and format that you can't mix them across FL/REF - the node fail-closes rather than silently casting. Watch the log for the plan fingerprint and the selected tensor/family/byte counts; that's the honest record of what actually got loaded.

Install

The pack ships 16 nodes, so one install covers everything: search ComfyUI_JR_MiniMaxH3Node in ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Goldlionren/ComfyUI_JR_MiniMaxH3Node
<your-comfyui-python> -m pip install -r ComfyUI_JR_MiniMaxH3Node/requirements.txt

Use the exact same Python that runs ComfyUI - portable and launcher installs often aren't on your system python. Restart and hard-refresh the browser afterward. The only hard dependency is imageio-ffmpeg; the model files themselves come from MiniMax on HuggingFace and you need to be outside the territories H3's community license excludes (US, EU, UK, Korea) to run the weights at all.

Troubleshooting

• "Incompatible tensor family" errors usually mean your REF checkpoint is pruned or quantized differently from FL. Don't fight it - pick a profile that only selects families that actually exist in both, or fall back to Pure FL.
• No speedup visible. That's expected: the Recommended profile is about letting REF's AdaLN participate in conditioning, not about shrinking the model. It's a quality/parameter experiment, not a memory optimizer.
• Two checkpoints on disk still. Yes - the node needs both files present; it just doesn't keep both in memory.