Tutorial FLUX.2: crie um visualizador de guarda-roupa cápsula com Gradio

Passo 1: configuração do ambiente

Primeiro, instale a versão mais recente da biblioteca diffusers a partir do GitHub e as demais dependências.

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

Depois, faça login no Hugging Face para baixar os pesos 4-bit do FLUX.2-dev:

from huggingface_hub import login
login() 

Informe seu token da HF quando solicitado e faça login para puxar o modelo. Em seguida, faça um sanity check rápido para ver se o CUDA está disponível e qual GPU está sendo usada:

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

Se você enxergar sua GPU na saída do nvidia-smi e CUDA available: True, está tudo certo.

Passo 2: modelo FLUX.2-dev (4 bits)

Agora vamos carregar os componentes 4-bit do FLUX.2-dev do repositório 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)

Com as dependências instaladas, podemos carregar o FLUX.2 usando a biblioteca diffusers e pareá-lo com um codificador de texto Mistral 3 do transformers. Em código, fica assim:

• Flux2Transformer2DModel: o transformador do tipo U-Net responsável pelo processo de remoção de ruído, carregado na forma quantizada em 4 bits.
• Mistral3ForConditionalGeneration: usado como codificador de texto, convertendo seu prompt em sinais de condicionamento para o processo de difusão.
• Flux2Pipeline: compõe o transformador, o codificador de texto e componentes de suporte em uma interface única e chamável para geração de imagens.

Usar device_map="auto" e torch_dtype=torch.bfloat16 mantém tudo flexível entre diferentes GPUs, sem abrir mão da eficiência de memória.

Passo 3: pré-processamento das imagens

O app permite que o usuário envie várias imagens de roupas. Precisamos de alguns utilitários para isso:

• Converter objetos de arquivo do Gradio em imagens PIL
• Redimensioná-las para um tamanho adequado para condicionamento

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

O código acima define duas funções auxiliares importantes.

• A função files_to_pil() recebe os objetos de arquivo retornados pelo Gradio, extrai seus caminhos e abre cada arquivo como um PIL.Image em RGB.
• A função preprocess_refs() redimensiona essas imagens para no máximo 512 × 512 preservando a proporção, o que é importante para velocidade e uso de memória.

Além disso, limitamos o número de imagens de referência com MAX_REFS = 10 para não sobrecarregar o conjunto de condicionamento.

Passo 4: prompt do look

Em vez de enviar um prompt simples, criei um prompt estruturado, no estilo JSON, que descreve:

• O ambiente de estúdio
• O sujeito e a pose
• As peças do look (vinculadas às imagens de referência)
• Informações de iluminação, clima e câmera

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)

A função build_outfit_prompt() faz três coisas importantes:

• Primeiro, usa outfit_indices e labels para gerar frases como "peça do guarda-roupa 1 da imagem de referência 1", unindo tudo em uma única string que descreve as peças selecionadas para aquele look.
• Depois, insere essas peças em um prompt em linguagem natural (mistral_prompt) que define o ambiente de estúdio, a iluminação, a lente, a profundidade de campo etc.
• Por fim, empacotamos tudo em um prompt_dict com campos de cena e sujeitos, e serializamos para JSON para que possa ser enviado como uma única string de prompt ao pipeline.

Conceitualmente, tratamos cada imagem enviada como uma “peça do guarda-roupa i” e pedimos ao modelo para “montar um look usando a peça 1, a peça 3 e a peça 4”, preservando cor, tecido e detalhes-chave de cada peça.

Observação: como usamos um modelo Mistral como codificador de texto neste pipeline, também usei o Mistral para ajudar a redigir o prompt longo de descrição de estúdio (mistral_prompt) via meta prompting. Isso mantém o estilo alinhado com o que o codificador “espera” e facilita ajustar o texto diretamente no código.

Passo 5: gerando a grade do guarda-roupa

O coração da demo é a capsule_fn, que:

• Recebe as imagens enviadas e os parâmetros da UI
• Seleciona aleatoriamente subconjuntos de peças para cada célula
• Chama o pipeline FLUX.2-dev para gerar múltiplas imagens
• E, por fim, compõe tudo em uma única grade

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

Essas duas funções formam o motor principal da nossa demo de guarda-roupa cápsula.

• A make_grid() cria uma tela em branco do tamanho necessário para o layout de linhas × colunas e cola cada imagem de look na posição correta, gerando uma única imagem em grade.
• A capsule_fn() prepara as imagens do usuário como referências, seleciona aleatoriamente 2–3 peças por célula, constrói um prompt estruturado e chama o pipeline FLUX.2 com a resolução, etapas, guidance e seed escolhidas. Ela coleta todas as células geradas e as envia para make_grid(), para que o usuário veja a grade final com looks mix & match.

Passo 6: UI no Gradio

Agora conectamos o motor do guarda-roupa cápsula ao app em Gradio. O usuário envia imagens, escolhe as configurações de grade e geração e recebe de volta a grade composta de looks.

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)

Como montamos o app em Gradio:

• A lista de inputs define todos os controles interativos do app. O input de peças do guarda-roupa é um upload múltiplo de 2–10 fotos de roupas ou produtos, enquanto os sliders de linhas e colunas definem o formato da grade e, portanto, quantos looks são gerados por lote.
• Os sliders de altura e largura controlam a resolução de cada célula — valores mais altos usam mais VRAM e tempo.
• O slider de etapas de difusão determina quantos passos de remoção de ruído o modelo executa (16–24 é um bom padrão), e a guidance scale controla o quanto o modelo segue o prompt de texto versus as referências.
• A chamada gr.Interface conecta esses inputs à função capsule_fn e declara uma única saída gr.Image. O launch(share=True, debug=True) inicia o servidor do Gradio, expõe um link público para demos e habilita logs de debug no console para ajudar no diagnóstico.

Com a interface no ar:

• Envie um conjunto pequeno de roupas (ex.: 2 camisas, 2 calças, 1 jaqueta, 1 par de sapatos).
• Escolha uma grade 3x3 ou 2x2, resolução 512x384, ~20 etapas e guidance de 2,5.
• Clique em Submit e acompanhe a grade sendo preenchida com imagens em estilo editorial.

Exemplos e observações do Flux 2

Para entender o comportamento do FLUX.2-dev na prática, rodei alguns experimentos rápidos com o app final. Variei as etapas de difusão e a guidance scale, e testei tanto múltiplas imagens da mesma peça quanto uma imagem por peça única para ver quanta variedade o modelo produz.

• Etapas de difusão e guidance afetam principalmente velocidade e nitidez, não memória. Aumentar de 28 para 30 etapas e a guidance de 2,5 para 5,0 mantém o uso de VRAM aproximadamente igual, mas deixa cada lote um pouco mais lento, com looks mais definidos. Porém, contagens de etapas altas (como 50) podem mudar perceptivelmente o visual da grade e aumentar a latência, com potencial de qualidade maior.
• Em uma A100, 4 bits é um padrão bem confortável. Com o checkpoint 4-bit do FLUX.2-dev, grades 3x3 em 512x384 com ~20–28 etapas ficam rápidas e seguras para demos em uma única GPU. Se você tiver uma H100 e puder carregar o checkpoint original (não quantizado), muitas vezes dá para obter qualidade de imagem maior em latência semelhante. Claro, sua experiência real pode variar conforme VRAM e tamanho do lote.

Exemplo 1: configurações padrão com múltiplas vistas da mesma peça

Primeiro, enviei várias imagens do mesmo look em ângulos diferentes, mantive as etapas padrão e guidance moderada. O modelo produziu iluminação de estúdio consistente e detalhes de tecido fiéis, com looks que parecem variações de um mesmo conjunto cápsula.

Exemplo 2: mais etapas de difusão com múltiplas vistas da mesma peça

Depois, mantive as mesmas referências, aumentei as etapas de difusão para 28 (e ajustei levemente a guidance). A grade ficou um pouco mais nítida e polida, ainda recombinando as mesmas peças principais. A troca foi um aumento pequeno, mas perceptível, no tempo por lote.

Experimento 3: uma imagem por peça única

Por fim, enviei um produto por peça distinta e gerei outra grade 3x3. Os looks ficaram bem mais variados entre as células, misturando diferentes partes de cima e de baixo de formas interessantes. Ainda houve alguma repetição, mas, no geral, a grade ficou mais próxima de um guarda-roupa cápsula real, com combinações mais diversas para a mesma seed e configurações.

Conclusão

O FLUX.2-dev em 4 bits é um ótimo modelo para aplicações de imagem. Neste tutorial, configuramos um pipeline FLUX.2-dev em 4 bits com o diffusers, construímos um fluxo de referência com múltiplas imagens que trata as peças do guarda-roupa como pistas de condicionamento e empacotamos tudo em um app Gradio.

O resultado é um visualizador de guarda-roupa cápsula poderoso, que pode servir como protótipo para ferramentas de e-commerce de moda ou simplesmente uma forma divertida de remixar seu próprio armário. A partir daqui, você pode conectar o mesmo pipeline a sistemas mais agentivos, como um LLM que sugere looks por dress code ou clima, ou integrá-lo ao backend de um catálogo real de produtos.