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…

Что это?Пользовательский узел ComfyUI, который загружает чекпоинт MiniMax H3 (аудио+видео DiT), сливая выбранные группы тензоров из второго «оверлейного» чекпоинта с «базовым» чекпоинтом, и создаёт гибрид, который ComfyUI обрабатывает точно как обычную загруженную модель.
Это отдельное приложение или оно подключается к чему-то ещё?Это пользовательский узел (плагин) для ComfyUI, а не отдельная программа — он добавляет новый узел загрузки в категорию model/loaders ComfyUI.
Нужны ли определённые чекпоинты, чтобы это использовать?Да — нужны оба чекпоинта safetensors MiniMax H3, fl2va и ref2va, поскольку узел сливает группы тензоров именно между этими двумя моделями.
Удваивает ли загрузка двух чекпоинтов потребление памяти?Нет — оба файла safetensors работают через mmap и читаются потоково тензор за тензором, поэтому пиковая память держится на уровне примерно одной модели (~19.5 ГБ для чекпоинтов int8), как и у штатного загрузчика.
Какая гибридная настройка рекомендуется?Используйте fl2va как базу и накладывайте только послойные веса модуляции AdaLN из ref2va для блоков с 25 по 49 — автор установил, что это уравновешивает качество вывода с сохранённой способностью conditioning на референсы.
Что делает пресет 'none'?Он выполняет чистую загрузку базового чекпоинта, эквивалентную штатному UNETLoader ComfyUI, не беря ничего из оверлейного чекпоинта.
Изменяет ли использование этого мои исходные файлы чекпоинтов?Нет, оба файла safetensors открываются только для чтения и никогда не записываются и не изменяются на диске.
Зачем вообще гибридизировать два чекпоинта MiniMax?fl2va и ref2va разделяют более 97% одинаковых весов, но у fl2va выше качество вывода, тогда как у ref2va одного есть известная проблема качества обучения, несмотря на добавление мультимодального conditioning на референсы — смешивание позволяет сохранить качество fl2va, вернув способность ref2va работать с референсами.
Creator
scottmudge
Size
0.1 MB
Stars
180
Updated
CommitAug 11
Age
2mo
Commits · 90 Days