Easy-Insert

       

Easy-Insert is a LoRA model for FLUX.2-klein-base-4B that performs reference-based object insertion: given a background image with a masked region and a reference image highlighting an object, the model inserts the object into the masked region while preserving the background, lighting, and surrounding elements for a seamless, natural result.

• 🤗 Model weights: HuanJue/Easy-Insert
• 🧠 Base model: black-forest-labs/FLUX.2-klein-base-4B
• 💾 Low VRAM mode: runs on 8 GB GPUs (see low_varm_inference.py)

Results

Each example shows the background image with its insert mask, the reference image with its object mask, and the generated result.

Example 1

Background + Insert Mask	Reference + Object Mask	Result

Example 2

Background + Insert Mask	Reference + Object Mask	Result

Example 3

Background + Insert Mask	Reference + Object Mask	Result

Example 4

Background + Insert Mask	Reference + Object Mask	Result

Usage

Installation

pip install -r requirements.txt

Standard inference

Run inference.py to reproduce Example 1 (saved to examples/result/1.png):

python inference.py

The script downloads the base model and LoRA from Hugging Face automatically, then:

1. Crops the background around the insert mask and resizes it to 1024×1024.

2. Crops the reference object and composites it onto a white canvas.

3. Runs the FLUX.2-klein pipeline with the fixed prompt:

   Replace the white mask of image1 with the content in image2. Preserving the background, lighting, and surrounding elements, maintain a seamless and natural result.

4. Pastes the generation back into the original full-resolution background.

Diffusers inference

inference_diffusers.py is an alternative to inference.py built on 🧨 Diffusers instead of DiffSynth. It uses the LiXiY/Easy-Insert Diffusers-format LoRA with Flux2KleinPipeline:

python inference_diffusers.py

The preprocessing, fixed prompt, and output are identical to inference.py; only the backend differs:

• Loads the base model with Flux2KleinPipeline.from_pretrained and applies the LoRA via pipe.load_lora_weights.
• Exposes seed, num_inference_steps, and guidance_scale as plain configuration variables at the top of the script.

Low VRAM inference (8 GB)

low_varm_inference.py is a drop-in variant of inference.py for GPUs with as little as 8 GB of VRAM. It works by:

• Keeping the text encoder and transformer offloaded to disk / CPU in float8 (torch.float8_e4m3fn) when idle, and streaming them into CUDA as bfloat16 only during computation (vram_config).
• Deriving the VRAM budget dynamically from the actual free memory of the GPU (torch.cuda.mem_get_info), so the offloader always leaves a small safety margin.

The interface and output are identical to inference.py:

python low_varm_inference.py

Note: because weights are streamed from disk/CPU between steps, this mode is significantly slower than the standard one — it trades speed for a much smaller memory footprint.

Gradio web UI

app.py provides an interactive demo with brush/eraser masking on both the background and reference images, plus the four examples above loadable with one click:

python app.py

Then open http://localhost:7860 in a browser.

Input format

Each generation requires four inputs (see the examples/ directory):

Input	Description
Background image	The target scene.
Insert mask	White region on the background marking where the object should appear.
Reference image	An image containing the object to insert.
Reference mask	White region on the reference image marking the object.