ComfyUI Extension

FreeFuse

FreeFuse: compose multi-subject LoRAs for FLUX, Z-Image, Klein, SDXL, Krea2, MOSS Image, Anima and native MiniMax H3 video. Upgrade to v1.0.14+ for GGUF tensor-format fixes.

By yaoliliu·Created 9 months ago·Updated a day ago· 246

yaoliliu/FreeFuse

Nodes—

On cloudLocal install

Stars246

Updateda day ago

Readme

FreeFuse: Multi-Subject LoRA Fusion via Adaptive Token-Level Routing at Test Time

<img src="assets/teaser.png" alt="Teaser" width="100%"> FreeFuse enables seamless multi-subject composition by fusing multiple LoRAs without additional training or user-defined masks.

📌 TODO

[x] Release basic inference code
[x] Release inference code for controlnet, ipadapter and redux
[x] Supports ComfyUI
[x] Supports Z-Image-turbo in diffusers
[x] Supports Z-Image-turbo in ComfyUI
[x] Supports FLUX.2-klein-4B/9B in diffusers
[x] Supports FLUX.2-klein-4B/9B in ComfyUI
[x] Supports Krea2 in ComfyUI
[x] Experimental MOSS Image Base/SFT support in Diffusers and ComfyUI
[x] Anima Base v1.0 support in ComfyUI
[x] Support ControlNet+FreeFuse in ComfyUI
[x] Native MiniMax H3 text-to-audio-video support in ComfyUI

📖 Abstract

This paper proposes FreeFuse, a training-free framework for multi-subject text-to-image generation through automatic fusion of multiple subject LoRAs. In contrast to prior studies that focus on retraining LoRA to alleviate feature conflicts, our analysis reveals that simply spatially confining the subject LoRA's output to its target region and preventing other LoRAs from directly intruding into this area is sufficient for effective mitigation. Accordingly, we implement Adaptive Token-Level Routing during the inference phase. We introduce FreeFuseAttn, a mechanism that exploits the flow matching model's intrinsic semantic alignment to dynamically match subject-specific tokens to their corresponding spatial regions at early denoising timesteps, thereby bypassing the need for external segmentors. FreeFuse distinguishes itself through high practicality: it necessitates no additional training, model modifications, or user-defined masks spatial conditions. Users need only provide subject activation words to achieve seamless integration into standard workflows. Extensive experiments validate that FreeFuse outperforms existing approaches in both identity preservation and compositional fidelity.

🎨 Results

Results on Flux.dev

<img src="assets/flux_res.png" alt="Flux Results" width="100%"> Qualitative results on Flux.dev. FreeFuse achieves superior identity preservation and compositional fidelity.

Results on SDXL

<img src="assets/il_res.png" alt="IL Results" width="100%"> Additional comparisons demonstrating FreeFuse's effectiveness on SDXL.

Results on MiniMax H3 video (ComfyUI)

Middle frame from the native ComfyUI workflow: global LoRAs on the left, automatic FreeFuse on the right. The example generates 768 × 768 videos with 124 frames and native audio. See the H3 workflow, model setup and validated scope.

🏗️ Architecture

<img src="assets/arch.png" alt="Architecture" width="100%"> Overview of FreeFuse architecture. FreeFuseAttn dynamically routes subject-specific LoRAs to their corresponding spatial regions via adaptive token-level routing, enabling training-free multi-subject LoRA fusion.

🚀 Quick Start

Installation with ComfyUI

# use comfy-cli
pip install comfy-cli
comfy node install freefuse

# or manual installation
cd <your ComfyUI path>/custom_nodes
git clone --depth 1 --branch comfyui https://github.com/yaoliliu/FreeFuse.git freefuse_comfyui

You can find example workflows in the freefuse_comfyui/workflows folder, including the MiniMax H3 video comparison workflow.

Installation with diffusers

You just need clone this repo and use uv to install dependencies.

apt-get update && apt-get install -y git-lfs && git lfs install
git clone https://github.com/yaoliliu/FreeFuse.git
git lfs pull
# or using huggingface if lfs budget is used up
hf download lsmpp/freefuse_example_loras --local-dir=./loras

uv venv
source .venv/bin/activate
uv sync

Running on Flux

without background identification

python main_freefuse_flux.py

with background identification and style LoRA

python main_freefuse_flux_bg_except.py

with redux

python redux_freefuse_flux_bg_except.py

with ipadapter

python ipadapter_freefuse_flux_bg_except.py

with controlnet

python controlnet_freefuse_flux_bg_except.py

If you running out of your vram, you can set the quantization variable in the script to 'True' to enable quantization, which will reduce the vram usage.

Running on SDXL

python main_freefuse_sdxl.py

Running on Z-Image-turbo

python main_freefuse_z_image.py

Acknowledgement

Thanks for Tekemo and jrewingwannabe947's ZIT LoRAs, which are used in our Z-Image-turbo examples.

Thanks to gpl1967 and merermero for the Krea2 support request and discussion in issue #26.

Single-LoRA character references are shown at the left of each row. See reference generation settings.

<img src="assets/compare_all_with_references.png" alt="Single-LoRA references and FreeFuse comparisons" width="100%"> FreeFuse solves feature conflicts between multiple subject LoRAs without additional training in flux1.dev, sdxl, z-image and more.