fbjr/MiniMax-H3-Acc-LoRAs-sidecar

MiniMax-H3 Acc LoRAs, converted for a ComfyUI node

Node bugfix, 2026-08-29, about three hours after the first upload. If you downloaded comfyui_minimax_h3_pdd/ before then, replace it. The weights are unchanged — only the node. The first copy left the PDD head bank resident on the GPU and made ComfyUI report a memory leak on every model load after a PDD render.

Format conversions of alibaba-pai/MiniMax-H3-Acc-LoRAs, the official Parallel Decoding Distillation acceleration LoRAs for MiniMax H3.

Nothing here was trained. Every tensor originates in that release or in MiniMaxAI/MiniMax-H3; only the layout changed, so that a ComfyUI node can apply all three mechanisms the published file carries.

These weights do nothing on their own — you need the MiniMaxH3PDDLoRA node too. Without it the files load nothing through a stock LoRA loader and say so only in a log line (why). Get it either way below — you need one of them, not both, and they contain the same node:

• Either comfyui_minimax_h3_pdd/, in this repo. Download the folder, drop it in custom_nodes/, restart. Self-contained: one node, five files, no dependencies beyond ComfyUI. Take this one unless you have a reason not to — it is pinned to the commit these weights were built and tested against, and changes only when they do.
• Or clone ComfyUI-h3-explorations, the source repo, if you want the rest of the MiniMax H3 work or need to file an issue. Same PDD node, but it is an active research repo: it changes often, sometimes daily, and its other nodes, graphs and defaults move without notice.

If you clone the source repo you already have the node — do not also copy the folder. ComfyUI registers nodes by name into a plain dictionary, so the second one to load silently replaces the first with no warning, and which one you are running depends on load order.

Files

Four files: two partitions × two checkpoint compatibilities. Take the row that matches the checkpoint you render on.

file	use it when your checkpoint is	size
minimax_h3_fl2va_pdd_8step_comfy.safetensors	pruned FL2VA	1069 MiB
minimax_h3_fl2va_pdd_8step_adaln2688_comfy.safetensors	any FL2VA — pruned or not	1594 MiB
minimax_h3_ref2va_pdd_8step_comfy.safetensors	pruned Ref2VA	1069 MiB
minimax_h3_ref2va_pdd_8step_adaln2688_comfy.safetensors	any Ref2VA — pruned or not	1594 MiB

Take adaln2688 if you are unsure which checkpoint you have, if you have both, or if yours is unpruned. Where both apply they behave identically and the difference is 525 MiB of storage.

Match the partition — this is the trap. An FL2VA LoRA belongs on an FL2VA checkpoint. The two partitions ship identical key sets, so a mismatched pair loads with zero unmatched keys and renders something that looks structurally normal. Each file carries a fingerprint tensor so the node can refuse the swap; nothing in a stock loader would notice.

All four are 8 evaluations over a 32-point grid at block width 4, shift 12.0 video / 3.0 audio — the values the release declares and the LoRAs were distilled under.

Two folders come with them:

folder	what it is
comfyui_minimax_h3_pdd/	the node, required — copy into custom_nodes/
workflows/	four ready graphs, core ComfyUI plus that node

How to use these

1. Install the node, by either route above, so you end up with e.g.:

custom_nodes/comfyui_minimax_h3_pdd/

Skipping it does not fail loudly: the head bank is not a weight patch — it replaces the output-head forward — and on the adaln2688 files the modulation update is not one either, so a stock LoRA loader applies the backbone, silently skips the rest, and renders something plausible at the wrong quality.

2. Put the file in models/loras/ and pick the row from Files that matches your checkpoint.

3. Wire it. The node takes MODEL and returns MODEL and SIGMAS. Send the model to your guider and the sigmas to your sampler:

UNETLoader ──► MiniMaxH3PDDLoRA ──MODEL──► BasicGuider ──► SamplerCustomAdvanced
                      └──────────SIGMAS───────────────────────────┘

There is no BasicScheduler. The node emits the schedule its own heads were fused for, which is the point of the SIGMAS output — a scheduler set to the same step count does not produce the same sigmas, and the heads would then be decoding intervals the sampler never steps through.

Set steps on the node, not on a scheduler. Legal values and what each costs are in Step counts; 5 is a good default and 8 is what the release distilled.

Leave strength and head_strength at 1.0 unless you are ablating. Setting head_strength to 0.0 keeps the backbone and modulation updates while running the checkpoint's own output heads, which is a useful control.

Example workflows

workflows/ holds four ready graphs, all text-to-video-and-audio on the FL2VA partition, rendering a three-shot dialogue scene with two speakers.

file	partition	last step spans	what it is for
t2va_pdd_5step.json	[8,8,8,4,4]	63.2%	start here — cheapest count that keeps a narrow tail
t2va_pdd_8step.json	[4,4,4,4,4,4,4,4]	63.2%	the distilled count; the reference arm
t2va_pdd_4step.json	[8,8,8,8]	80%	fastest, and visibly coarser — see below
t2va_pdd_8step_heads_off.json	[4,4,4,4,4,4,4,4]	63.2%	control: head_strength=0.0 runs the checkpoint's own heads

Use 5 rather than 4 unless the time matters, and there is little point going past it — 6 and 7 are legal, one widget away, and within 2% of 5 (Step counts has the mechanism). The 4-step graph ships because it is the first thing most people try, and knowing why it looks coarse beats concluding the weights are broken.

Core ComfyUI nodes plus this one — no attention pack, no VideoHelperSuite; CreateVideo → SaveVideo muxes both streams. No sigma-shift node either: core's MiniMaxH3.sampling_settings already carries shift: 12.0, audio_shift: 3.0, so one setting those values does nothing.

The loaders name the checkpoints and VAEs as they are called here; repoint them at yours.

Step counts

Blocks must tile the 32-point grid, and the bank was distilled at width 4. A count is accepted by either of two routes: it divides 32, or it tiles unevenly with every block inside the trained envelope [4, 8].

nfe	partition	route	inside [4,8]	coarseness vs 8
1	[32]	divisor	no — wider	2.288x
2	[16,16]	divisor	no — wider	1.963x
4	[8,8,8,8]	divisor	yes	1.506x
5	[8,8,8,4,4]	envelope	yes	1.020x
6	[8,8,4,4,4,4]	envelope	yes	1.004x
7	[8,4,4,4,4,4,4]	envelope	yes	1.001x
8	[4,4,4,4,4,4,4,4]	divisor	yes	1.000x
16	[2]×16	divisor	no — narrower	0.578x
32	[1]×32	divisor	no — narrower	0.305x

3, and 9 through 31 except 16, are not expressible at all and the node raises rather than warning — the failure is otherwise silent, since the render completes and is merely wrong.

Coarseness is the summed square of each step's share of the sigma range; bench/measure_pdd_step_ladder.py in the companion repo computes it. Wide blocks lead so the final block stays narrow: a partition ending width-4 spends its last Euler step on 63.2% of the trajectory, one ending width-8 spends 80%.

5 to 8 is a plateau, not a ladder — 2% separates its ends. 16 and 32 leave the envelope the other way, fusing blocks narrower than the bank was distilled over; finer, and untested.

This is schedule geometry, not a quality claim: two step counts give different samples, not better and worse versions of one.

Why a conversion is needed

The published files match nothing in ComfyUI: their key suffixes are bare lora_up / lora_down, and their module names are diffusers-side (transformer_blocks.N.attn.to_q against ComfyUI's blocks.N.attn.qkv_proj).

It fails silently — every tensor is skipped and the render completes as an ordinary undistilled pass, so it looks like a weak LoRA rather than an unapplied one.

What was changed

Four transforms on the backbone, each verified numerically against the source:

• q/k/v fused into one qkv_proj — A concatenated over the rank axis, B made block-diagonal, bit-identical to the separate projections.
• Alpha scaled with the fuse, 64 → 192 against the tripled rank, so the applied alpha/rank stays 1.0. Left at 64 it would apply at a third strength, and still load and render.
• Explicit .alpha tensors added — ComfyUI reads alpha from a tensor and never from safetensors metadata, where the source declares it.
• SwiGLU output halves swapped, plus two renames (attn.to_out.0 → attn.out_proj, ff.net.2 → mlp.fc2).

The head bank ships verbatim: all 32 per-interval heads, fused per block at first use rather than collapsed at conversion time, so one file serves any legal step count without reconversion.

The modulation update is the only piece with two encodings, because a pruned checkpoint has no 2688-dimensional time space to patch. adaln2688 carries it in full; the others carry it pre-solved into the pruned checkpoint's rank-8 basis, which makes it an ordinary weight patch.

Head bank encoding

The banks here are verbatim heads, not deltas from head 0. ComfyUI core's own PDD path uses the opposite convention. The two coexist only because this node leaves final_layer.video_out.weight at its original shape; feeding these files to a path expecting delta-encoded rows produces a silently wrong render, not an error. If you are writing your own loader, check which convention you are reading.

Limitations

• Four evaluations cannot be improved. [8,8,8,8] is the only 4-block partition legal under the trained envelope, so its 80% tail is forced rather than chosen. Every count from five up reaches 63.2%, and 5 through 8 sit within 2% of each other.
• Block width 8 is 2× the trained width. It is the widest anything here has been used at, and nothing published has measured whether it holds up.
• Both streams degrade as blocks widen, and the audio does so audibly. Coarseness governs quality and it governs video and audio together. It is tempting to report this as an audio-only problem — the audio artefacts are the ones you notice — but that reading came from a metric blind to what happens to the video: raw video error is dominated by a term every partition preserves, so video looked flat while its contrast was falling. Treat widening as costing both.
• The distillation is 8-step. These are conversions of an 8-step release; running far from that is extrapolation.

Credits

• MiniMax for MiniMax H3.
• alibaba-pai for the Acc LoRAs these are converted from, and for the PDD method.
• The node is generated from ComfyUI-h3-explorations, which is where to file issues and where the rest of the H3 work lives.
• silveroxides, whose ComfyUI-UtilsCollection PDD implementation separates LoRA strength from head strength; the node that reads these files borrows that split.

Powered by MiniMax H3.

---

License

These are Model Derivatives of MiniMax H3 and are distributed under the MiniMax H3 Community License Agreement, the same terms as both upstream releases. The full agreement is in LICENSE; the required attribution is in NOTICE.

Two terms worth reading before you use these commercially or redistribute them, neither of which is unusual but both of which are easy to miss:

• The agreement is territorially limited — worldwide excluding the Excluded Territories it names.
• Commercial products or services generating over 20 million USD in yearly revenue need separate written authorisation from MiniMax.

If you redistribute these files or anything derived from them, the agreement requires you to pass on a copy of it, carry prominent notices on modified files, and include the NOTICE text. You may not relicense them under different terms.

MiniMax H3 is licensed under the MiniMax H3 Community License Agreement,
Copyright (c) 2026 MiniMax. All Rights Reserved.