Tutorial FLUX.2: crea un visualizzatore di capsule wardrobe con Gradio

Passo 1: configurazione dell’ambiente

Per prima cosa, installa l’ultima libreria diffusers da GitHub e le altre dipendenze.

!pip install -q "git+https://github.com/huggingface/diffusers.git@main" \
               "transformers>=4.44.0" accelerate safetensors bitsandbytes gradio pillow

Poi effettua il login a Hugging Face così da poter scaricare i pesi FLUX.2-dev a 4 bit:

from huggingface_hub import login
login() 

Inserisci l’HF Token quando richiesto ed esegui il login a HF per scaricare il modello. Quindi, fai un rapido sanity check per vedere se CUDA è disponibile e quale GPU stiamo usando:

import torch, diffusers, bitsandbytes as bnb
print("diffusers:", diffusers.__version__)
print("CUDA available:", torch.cuda.is_available())
!nvidia-smi

Se vedi la tua GPU nell’output di nvidia-smi e CUDA available: True, sei a posto.

Passo 2: Modello FLUX.2-dev (4-bit)

Ora carichiamo i componenti FLUX.2-dev a 4 bit dal repo diffusers/FLUX.2-dev-bnb-4bit.

from diffusers import Flux2Pipeline, Flux2Transformer2DModel
from transformers import Mistral3ForConditionalGeneration
import torch
bnb_repo = "diffusers/FLUX.2-dev-bnb-4bit"   
torch_dtype = torch.bfloat16
device = "cuda"
print("Loading 4-bit transformer...")
transformer = Flux2Transformer2DModel.from_pretrained(
    bnb_repo,
    subfolder="transformer",
    torch_dtype=torch_dtype,
    device_map="auto",          
)
print("Loading 4-bit text encoder...")
text_encoder = Mistral3ForConditionalGeneration.from_pretrained(
    bnb_repo,
    subfolder="text_encoder",
    torch_dtype=torch_dtype,
    device_map="auto",
)
print("Building Flux2 pipeline...")
pipe = Flux2Pipeline.from_pretrained(
    bnb_repo,
    transformer=transformer,
    text_encoder=text_encoder,
    torch_dtype=torch_dtype,
).to(device)
pipe.set_progress_bar_config(disable=False)
print("Loaded. Example param device:", next(pipe.transformer.parameters()).device)

Una volta installate le dipendenze, possiamo caricare FLUX.2 usando la libreria diffusers e abbinarla a un text encoder Mistral 3 da transformers. Ecco come appare in codice:

• Flux2Transformer2DModel: è il trasformatore core in stile U-Net responsabile del processo di denoising ed è caricato in forma quantizzata a 4 bit.
• Mistral3ForConditionalGeneration: questo modello è usato come text encoder, trasformando il tuo prompt testuale in segnali di condizionamento per il processo di diffusione.
• Flux2Pipeline: questa pipeline compone il trasformatore, il text encoder e i componenti di supporto in un’unica interfaccia chiamabile per la generazione di immagini.

Usare device_map="auto" e torch_dtype=torch.bfloat16 mantiene le cose flessibili su diversi setup GPU rimanendo efficienti in memoria.

Passo 3: Preprocessare le immagini

L’app permette agli utenti di caricare più immagini del guardaroba. Ci servono alcune utility per farlo:

• Convertire gli oggetti file di Gradio in immagini PIL
• Ridimensionarle a una dimensione gestibile per il condizionamento

import gradio as gr
import random, json
from typing import List, Union
from PIL import Image
MAX_REFS = 10
def files_to_pil(files: List[Union[str, dict]]) -> List[Image.Image]:
    images = []
    for f in files:
        path = f.get("name") if isinstance(f, dict) else f
        if not path:
            continue
        img = Image.open(path).convert("RGB")
        images.append(img)
    return images
def preprocess_refs(refs: List[Image.Image], max_size: int = 512) -> List[Image.Image]:
    processed = []
    for img in refs:
        img = img.convert("RGB")
        img.thumbnail((max_size, max_size), Image.LANCZOS)
        processed.append(img)
    return processed

Il codice sopra definisce due funzioni helper chiave.

• La funzione files_to_pil() prende gli oggetti file restituiti da Gradio, ne estrae i percorsi e apre ogni file come PIL.Image RGB.
• La funzione preprocess_refs() ridimensiona queste immagini a una dimensione massima di 512 × 512 preservando il rapporto d’aspetto, cosa importante sia per la velocità sia per l’uso di memoria.

Inoltre, limitiamo il numero di immagini di riferimento con MAX_REFS = 10 per non sovraccaricare il set di condizionamento.

Passo 4: Prompt per l’outfit

Invece di inviare un singolo prompt testuale piatto, ho costruito un prompt strutturato in stile JSON che descrive:

• L’impostazione in studio
• Il soggetto e la posa
• I pezzi dell’outfit (collegati a immagini di riferimento)
• Illuminazione, mood e informazioni sulla fotocamera

def build_outfit_prompt(outfit_indices: List[int], labels: List[str]) -> str:
    item_phrases = [
        f"{labels[idx]} from reference image {idx+1}" for idx in outfit_indices
    ]
    outfit_items_str = ", ".join(item_phrases)
    mistral_prompt = """A professional full-body studio photograph of a high-end fashion editorial shoot, set against a flawless seamless neutral gray backdrop (#f5f5f5) in a controlled studio environment. The scene is bathed in soft, diffused three-point lighting (key, fill, and subtle rim) that eliminates harsh shadows, ensuring even illumination across the subject while preserving dimensionality and texture.
At the center of the frame stands a full-body adult model, exuding quiet confidence in a relaxed yet poised stance—one foot slightly forward, weight balanced, body angled subtly to the right. The model’s expression is natural, with a neutral gaze directed just off-camera, evoking a modern, minimalist lookbook aesthetic.
The outfit—meticulously styled and tailored—is the focal point, captured with ultra-realistic 8K resolution and razor-sharp detail. Fabrics display tactile depth: the weave of knits, the drape of silks, the sheen of leathers, and the crispness of cotton are all rendered with commercial-grade precision. The shallow depth of field (50mm prime lens, f/2.8) keeps the subject in crystalline focus while softly blurring the backdrop, emphasizing the outfit’s textures and proportions.
The composition adheres to classic fashion photography rules: vertical framing, ample headroom, and a slightly dynamic angle (eye-level) that flatters the model’s posture. The color palette is controlled and sophisticated, dominated by the outfit’s hues against the neutral gray, with subtle tonal contrasts to highlight layers and accessories.
Every element—from the studio-quality lighting to the catalog-ready styling—conveys luxury, clarity, and commercial appeal, designed to showcase the outfit as a covetable, high-end ensemble."""
    prompt_dict = {
        "scene": mistral_prompt,
        "subjects": [
            {
                "description": (
                    "The model is styled in an outfit composed of: "
                    + outfit_items_str
                    + ". Each garment should closely match the color, fabric, and key design details of its reference image."
                )
            }
        ]
    }
    return json.dumps(prompt_dict)

La funzione build_outfit_prompt() fa tre cose importanti:

• Per prima cosa, usa outfit_indices e labels per generare frasi come "pezzo del guardaroba 1 dalla immagine di riferimento 1", che vengono unite in una singola stringa che descrive i capi selezionati per quell’outfit.
• Poi incorpora questi capi in un mistral_prompt in linguaggio naturale che definisce l’ambiente dello studio, l’illuminazione, l’obiettivo, la profondità di campo, ecc. 
• Infine, impacchettiamo tutto in un prompt_dict con campi scene e subjects, quindi serializziamo quel dizionario in JSON per passarlo come singola stringa di prompt alla pipeline.

Concettualmente, trattiamo ogni immagine caricata del guardaroba come “pezzo del guardaroba i” e chiediamo al modello di “comporre un outfit usando il pezzo 1, il pezzo 3 e il pezzo 4”, preservando colore, tessuto e dettagli di design chiave di ciascun pezzo. 

Nota: poiché in questa pipeline usiamo un modello Mistral come text encoder, ho usato Mistral anche per aiutare a redigere il lungo prompt di descrizione dello studio (mistral_prompt) tramite meta prompting. Questo mantiene lo stile allineato a ciò che l’encoder “si aspetta” e rende facile affinare il testo direttamente nel codice.

Passo 5: Generare la griglia del guardaroba

Il cuore della demo è capsule_fn, che:

• Prende le immagini caricate e i parametri della UI
• Seleziona casualmente sottoinsiemi di pezzi del guardaroba per ogni riquadro
• Poi chiama la pipeline FLUX.2-dev per generare più immagini
• Infine, le compone in un’unica griglia

def make_grid(images: List[Image.Image], rows: int, cols: int) -> Image.Image:
    w, h = images[0].size
    grid = Image.new("RGB", (cols * w, rows * h), (255, 255, 255))
    for idx, img in enumerate(images):
        r, c = divmod(idx, cols)
        grid.paste(img, (c * w, r * h))
    return grid
def capsule_fn(files, rows, cols, height, width, steps, guidance, seed):
    if not files or len(files) < 2:
        return None
    images = files_to_pil(files)
    images = images[:MAX_REFS]
    refs = preprocess_refs(images, max_size=512)
    labels = [f"wardrobe piece {i+1}" for i in range(len(refs))]
    random.seed(int(seed))
    tiles = []
    num_tiles = rows * cols
    for i in range(num_tiles):
        k = min(len(refs), random.randint(2, 3))
        outfit_idxs = random.sample(range(len(refs)), k=k)
        prompt = build_outfit_prompt(outfit_idxs, labels)
        generator = torch.Generator(device=device).manual_seed(int(seed) + i)
        out = pipe(
            prompt=prompt,
            image=refs,   
            height=height,
            width=width,
            num_inference_steps=steps,
            guidance_scale=guidance,
            generator=generator,
        )
        tiles.append(out.images[0])
    grid = make_grid(tiles, rows, cols)
    return grid

Le due funzioni sopra costituiscono il motore principale della demo di capsule wardrobe.

• La funzione make_grid() crea una tela vuota abbastanza grande per un layout righe × colonne, quindi incolla ogni immagine generata dell’outfit nella posizione corretta, producendo un’unica immagine a griglia.
• La funzione capsule_fn() prepara le immagini del guardaroba dell’utente come riferimenti, seleziona casualmente 2–3 pezzi per riquadro, costruisce un prompt strutturato per l’outfit e chiama la pipeline FLUX.2 con la risoluzione, gli step, la guidance e il seed scelti. Raccoglie tutti i riquadri generati e li passa a make_grid(), così l’utente vede una griglia finale di outfit mix-and-match.

Passo 6: UI Gradio

Questo passaggio collega il motore della capsule wardrobe all’app Gradio. L’utente carica immagini del guardaroba, sceglie impostazioni di griglia e generazione e ottiene una griglia composita di outfit.

inputs = [
    gr.File(file_types=["image"], file_count="multiple", label="Wardrobe pieces (2–10 images)"),
    gr.Slider(1, 4, value=2, step=1, label="Grid rows"),
    gr.Slider(1, 4, value=2, step=1, label="Grid cols"),
    gr.Slider(384, 896, value=512, step=64, label="Image height"),
    gr.Slider(256, 640, value=384, step=64, label="Image width"),
    gr.Slider(10, 30, value=16, step=2, label="Diffusion steps"),
    gr.Slider(1.0, 7.0, value=2.5, step=0.5, label="Guidance scale"),
    gr.Number(value=42, precision=0, label="Seed")
]
iface = gr.Interface(
    fn=capsule_fn,
    inputs=inputs,
    outputs=gr.Image(type="pil", label="Capsule wardrobe grid"),
    title="Capsule Wardrobe Visualizer – FLUX.2-dev (4-bit)",
    description="Upload 2–10 product images; mix & match outfits using FLUX.2-dev with multi-image reference.",
)
iface.launch(share=True, debug = True)

Ecco come costruiamo l’app Gradio:

• La lista inputs definisce tutti i controlli interattivi dell’app. L’input per i pezzi del guardaroba è un upload multiplo di 2–10 scatti di capi o prodotti, mentre gli slider rows e cols impostano la forma della griglia e quindi quanti outfit vengono generati per batch. 
• Gli slider image height e image width controllano la risoluzione di ogni riquadro: valori più alti usano più VRAM e tempo. 
• Lo slider diffusion steps determina quanti step di denoising esegue il modello (16–24 è un buon default), mentre guidance scale controlla quanto il modello segua il prompt testuale rispetto ai riferimenti. 
• La chiamata gr.Interface collega questi input alla funzione capsule_fn e dichiara una singola uscita gr.Image. La chiamata launch(share=True, debug=True) avvia il server Gradio, espone un link pubblico condivisibile per le demo e abilita il logging di debug in console per aiutare la diagnosi di eventuali problemi.

Una volta che l’interfaccia è attiva:

• Carica un piccolo set di capi (per esempio, 2 magliette, 2 pantaloni, 1 giacca, 1 paio di scarpe).
• Scegli una griglia 3x3 o 2x2, risoluzione 512x384, ~20 step e una guidance di 2.5.
• Clicca su Submit e guarda la griglia riempirsi con immagini in stile editoriale.

Esempi e osservazioni su Flux 2

Per capire come si comporta FLUX.2-dev in pratica, ho eseguito alcuni piccoli esperimenti con l’app finale. Ho variato gli step di diffusione e la guidance scale, e ho provato sia più immagini dello stesso capo sia una immagine per capo unico per vedere quanta varietà produce il modello.

• Gli step di diffusione e la guidance influiscono soprattutto su velocità e nitidezza, non sulla memoria. Aumentare gli step da 28 a 30 e la guidance da 2.5 a 5.0 mantiene l’uso di VRAM più o meno uguale ma rende ogni batch un po’ più lento pur producendo outfit più definiti. Tuttavia, conteggi di step teoricamente alti (come 50) possono cambiare in modo evidente l’aspetto della griglia e aumentare la latenza con output di qualità superiore.
• Su una A100, i 4 bit sembrano un default molto confortevole. Con il checkpoint FLUX.2-dev a 4 bit, griglie 3x3 a 512x384 con ~20–28 step risultano veloci e sicure per demo su singola GPU. Se hai accesso a una H100 e puoi caricare invece il checkpoint originale (non quantizzato), spesso puoi ottenere qualità d’immagine più alta a latenza simile. Ovviamente, la tua esperienza può variare in base a VRAM e dimensione del batch. 

Esempio 1: Impostazioni predefinite con più viste dello stesso capo

Per prima cosa ho caricato diverse immagini dello stesso outfit riprese da angolazioni diverse, ho mantenuto gli step di diffusione predefiniti e una guidance moderata. Il modello ha prodotto un’illuminazione da studio coerente e dettagli di tessuto convincenti, con outfit che sembravano variazioni di un singolo set capsule.

Esempio 2: Più step di diffusione con più viste dello stesso capo

Successivamente, ho mantenuto le stesse immagini di riferimento ma ho aumentato gli step di diffusione a 28 (e leggermente regolato la guidance). La griglia è diventata un po’ più nitida e rifinita, ma focalizzata ancora sulla ricombinazione degli stessi capi principali. Il compromesso è stato un piccolo ma percepibile aumento del tempo di generazione per batch.

Esperimento 3: Una immagine per capo unico

Infine, ho caricato uno scatto di prodotto per ogni capo distinto e ho generato un’altra griglia 3x3. Gli outfit risultanti erano molto più vari tra i riquadri, mescolando top e bottom diversi in modi interessanti. È comparsa ancora un po’ di ripetizione, ma nel complesso la griglia è sembrata più vicina a una vera capsule wardrobe, con combinazioni più diverse a parità di seed e impostazioni.

Conclusione

FLUX.2-dev in forma a 4 bit è un ottimo modello per applicazioni di imaging. In questo tutorial, abbiamo configurato una pipeline FLUX.2-dev a 4 bit con diffusers e costruito un flusso di lavoro con riferimenti multi-immagine che tratta i pezzi del guardaroba come indizi di condizionamento, racchiudendo il tutto in un’app Gradio.

Il risultato è un potente Capsule Wardrobe Visualizer che può fungere da prototipo per strumenti di e-commerce fashion, o semplicemente un modo divertente per remixare il tuo armadio. Da qui, puoi collegare la stessa pipeline a sistemi agentici più ampi, come un LLM che suggerisce outfit in base al dress code o al meteo, oppure connetterla a un vero backend di catalogo prodotti.