Hunyuan 3 Generate (HighRes Efficient)

Here's the puzzle this node solves: HunyuanImage-3 is a Mixture-of-Experts model with 64 expert MLPs per layer, and the standard "eager" MoE implementation builds a giant routing tensor that grows quadratically with the number of image tokens. At 1024×1024 it's fine. At 2048×1536 (3MP), it blows past ~83GB of VRAM on a 96GB card and dies. Hunyuan 3 Generate (HighRes Efficient) (class HunyuanImage3GenerateHighRes) rewrites that routing so the same generation runs in ~55GB at 3MP and ~70GB at 4MP - with, the author insists, identical quality. It's the node that makes 2K, 3MP and 4K Hunyuan renders actually possible on a single 96GB GPU.

The README's benchmark table tells the story. The standard Large/Offload node: 1MP fine (~42GB), 2MP fine (~55GB), 3MP OOM at ~83GB. HighRes Efficient: 3MP ~55GB, 4MP ~70GB, 8MP ~90GB (tight but survivable on 96GB). Same routing decisions, same expert MLPs, same output - just dispatched through a loop instead of a giant sparse matrix. It's a genuinely clever patch, and it's the difference between "Hunyuan at high res" being a datacenter flex and something you can actually run.

Why the standard node OOMs (in one paragraph)

With CFG enabled (guidance_scale > 1.0) the batch doubles, so a 3MP render pushes ~25,000 tokens through every MoE layer. The eager path builds a dispatch_mask of shape [tokens, 64 experts, tokens/8] - a 5GB boolean tensor that becomes 10GB when cast to bf16, plus a matching combine_weights, plus einsum intermediates: ~37GB of MoE overhead on top of 30GB of weights and 16GB of KV cache. The efficient node keeps only the top-8 indices per token ([25088, 8], about 0.8MB) and loops the experts. ~75× less intermediate memory, no quality delta.

The inputs that matter

Same shape as the other generate nodes - model, prompt, seed, steps, guidance_scale, offload_mode (smart / always / disabled), post_action - but the resolution dropdown is where it lives: 29 options reaching up into 2048x1536 (3.1MP), 4MP and beyond. Pair it with the Full BF16 Loader and set the loader's target_resolution to 3MP (or your target) so the right inference headroom is reserved.

Outputs: image, rewritten_prompt (STRING; the optional rewrite cluster needs an LLM API key, off by default), status, and trigger.

How to install it

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/Comfy_HunyuanImage3
cd Comfy_HunyuanImage3
pip install -r requirements.txt

Restart ComfyUI and hard-refresh. Or search HunyuanImage in ComfyUI Manager.

Common issues & troubleshooting

Still OOM at 3MP. Check you're actually feeding it a BF16 model from the Full BF16 loader - the efficient dispatch assumes full precision. And watch offload_mode: on a 96GB card, disabled is right for ≤4MP; let smart decide beyond that.

"Why is my image taking forever?" The README notes speed is similar, not faster - the loop dispatch adds negligible overhead versus the expert MLPs. The win is memory, not throughput. 8MP on a 96GB card is ~90GB of VRAM and a lot of patience.

Quality check. If you want proof the efficient path doesn't change output, the pack ships Hunyuan MoE Efficient Test - an A/B harness that runs the same prompt/seed through both paths so you can compare with your own eyes.