FLUX 3 Image Klein

FLUX 3 Image Klein é um modelo de geração de imagens de 5,6B da Black Forest Labs: um único transformer (Flux3Transformer2DModel) gera imagens a partir de um prompt de texto, sozinho ou junto com uma ou mais imagens de referência. A condicionamento de texto vem do Qwen3-VL, e as imagens usam o autoencoder empacotado FLUX.2 (AutoencoderKLFlux2).

FLUX 3 Image Klein é distribuído como um pipeline modular. Comece com uma geração de imagem a partir de texto:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")

image = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output="images",
)[0]
image.save("fox.png")

prompt é a única entrada obrigatória: o pipeline carrega as configurações de amostragem recomendadas (50 etapas, escala de orientação 3.5, deslocamento do agendador 6.93) e gera imagens de 1024 x 1024 por padrão. Ele aceita um prompt por chamada; use num_images_per_prompt para várias imagens do mesmo prompt.

Como você pode ver no exemplo acima, o carregamento e a execução diferem um pouco de um DiffusionPipeline. O carregamento é preguiçoso: from_pretrained() apenas constrói o pipeline, e você chama load_components() para carregar os pesos. Uma chamada retorna o estado do pipeline, e você solicita o que precisa com output: output="images" aqui, ou output=["images", "prompt"] para também obter a legenda que o prompt upsampler escreveu.

Se você está trabalhando com ModularPipeline pela primeira vez, leia o quickstart e Vindo do DiffusionPipeline se você conhece os pipelines padrão. Além do carregamento e das saídas, algumas outras coisas diferem: guidance, callbacks e offloading.

Ampliação de prompt

O prompt importa: o FLUX 3 Image Klein aceita legendas completas de cena que descrevem o sujeito, a composição, a iluminação e a atmosfera, e não prompt curtos; uma solicitação enviada como digitada gera uma saída genérica. É por isso que o pipeline executa o upsampler de prompt primeiro em todas as solicitações, tanto para texto-para-imagem quanto para edição. Trata-se de um modelo separado de 9B da Black Forest Labs (black-forest-labs/flux-3-image-klein-pup) que expande prompt para uma legenda assim antes do codificador de texto, e um prompt curto é tudo o que é necessário.

O prompt upsampler transforma uma solicitação curta, junto com as imagens de referência durante a edição, na legenda completa da cena que o modelo recebe: meio e estilo, cena, iluminação e câmera, cada sujeito com suas cores, materiais e posição no quadro. Um único modelo cobre texto-para-imagem, edição com imagens de referência e layout com caixas. A legenda que ele escreveu retorna como a saída prompt. No exemplo acima, solicite-a junto com as imagens para ver o que o modelo de imagem recebeu:

out = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)
print(out["prompt"])

Full-color outdoor wildlife photograph taken from a low eye-level perspective in a snow-covered forest clearing at golden hour. In the center foreground, a red fox stands in profile facing left, its body turned toward the viewer and its head raised as it looks across the clearing. The fox has dense rust-red winter fur, a white throat and chest, black lower legs, pointed ears with dark tips, and a long bushy tail ending in white. ...

A legenda completa tem cerca de 240 palavras; max_new_tokens limita seu comprimento (3584 por padrão).

Você pode imprimir o doc da etapa para ver o que ela recebe e o que ela grava:

print(pipe.blocks.sub_blocks["prompt_upsampler"].doc)

  Inputs:
      prompt (`str`):
          The edit instruction to expand into the full caption (one per call).
      image (`Image | list`, *optional*):
          The reference image(s) of the edit, at most 10; the same ones the pipeline receives.
      boxes (`list`, *optional*):
          Layout boxes, each {'id', 'desc', 'from', 'src_bbox', 'tgt_bbox'} with the boxes as [y_min, x_min, y_max, x_max] in
          0-1: ...
      max_new_tokens (`int`, *optional*, defaults to 3584):
          The most tokens the upsampler may generate for the caption.

  Outputs:
      prompt (`str`):
          The full caption, replacing the request.

Assim como os outros blocos do pipeline, o bloco prompt_upsampler também é executado de forma independente. A maneira recomendada é removê-lo dos blocos: o bloco removido se torna um upsampler autônomo, e os blocos restantes formam um pipeline que recebe a legenda expandida como prompt:

blocks = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base").blocks
pup_block = blocks.sub_blocks.pop("prompt_upsampler")

pup = pup_block.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pup.load_components(dtype=torch.bfloat16)
pup.to("cuda")
caption = pup(prompt="A red fox in a snow-covered forest clearing at golden hour", output="prompt")

pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")
image = pipe(prompt=caption, generator=torch.Generator().manual_seed(0), output="images")[0]

Dessa forma, ele pode ser servido como um estágio separado, em sua própria GPU ou atrás de seu próprio endpoint, e uma interface pode exibir a legenda que ele escreveu e permitir que o usuário a edite antes de gerar. Qualquer outro LLM pode assumir o lugar do upsampler, com os mesmos system prompts: forneça system_prompts["t2i"] do repositório do upsampler (ou "i2i", com as referências primeiro na mensagem do usuário) como o system prompt e a solicitação como a mensagem do usuário, e passe a legenda que ele retorna como prompt para pipe.

Imagem para imagem

Passe uma ou mais imagens de referência com image. Uma única referência é mantida inteira: ela é redimensionada apenas acima de 4 megapixels, preenchida até a grade de 16 pixels e a geração usa seu tamanho por padrão, de modo que a edição retorna no tamanho da entrada. Várias referências são ajustadas individualmente para menos de 1 megapixel e recortadas para a grade, e a geração usa o tamanho da primeira por padrão. Um height/width específico substitui o padrão. Descreva a imagem alvo como uma legenda completa da referência com sua edição incorporada, em vez de uma instrução de uma linha, ou deixe que o prompt upsampler a escreva a partir da instrução e das referências:

night = pipe(
    prompt="the same scene at night under a full moon",
    image=image,
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)

Com várias referências, refira-se a elas como a primeira imagem, a segunda imagem, … na ordem em que são passadas para image; a legenda as nomeia como <ref_image_0>, <ref_image_1>, … para o modelo de imagem:

combined = pipe(
    prompt="the fox from the first image sitting on the wooden bench from the second image",
    image=[image, bench],
    height=768,
    width=1360,
    output="images",
)[0]

Pass height e/ou width para substituir o tamanho derivado.

Controle de layout

Para posicionar o conteúdo explicitamente, passe boxes: para cada elemento, um id, uma desc curta e um bbox de [y_min, x_min, y_max, x_max] em 0-1 (origem no canto superior esquerdo), para que seja independente do tamanho da saída. O upsampler escreve a legenda ao redor deles, citando cada elemento como <id>, e anexa a tabela de boxes, mantendo os seus exatamente:

boxes = [
    {"id": "balloon_1", "desc": "a red and yellow striped hot-air balloon", "bbox": [0.08, 0.06, 0.48, 0.38]},
    {"id": "balloon_2", "desc": "a small blue hot-air balloon", "bbox": [0.20, 0.62, 0.42, 0.80]},
]
out = pipe(prompt="hot-air balloons over a green valley at sunrise", boxes=boxes, output=["images", "prompt"])

Ao editar, uma caixa nomeia sua origem com from: "target" com um tgt_bbox adiciona um novo elemento ali, "ref_image_0" com um src_bbox e um tgt_bbox move um elemento daquela referência (caixas iguais o mantêm no lugar):

boxes = [{"id": "cactus", "desc": "a small potted cactus", "from": "target", "src_bbox": None, "tgt_bbox": [0.55, 0.62, 0.85, 0.85]}]
out = pipe(prompt="add a small potted cactus in the marked spot", image=mug, boxes=boxes, output=["images", "prompt"])

boxes = [{"id": "knight", "desc": "the knight figure", "from": "ref_image_0", "src_bbox": [0.50, 0.15, 0.85, 0.35], "tgt_bbox": [0.19, 0.06, 0.54, 0.26]}]
out = pipe(prompt="move the knight up and to the left, keep the rest unchanged", image=knight, boxes=boxes, output=["images", "prompt"])

A legenda que o modelo de imagem lê tem os elementos marcados com <id> no texto e a tabela anexada como JSON, com as caixas em um canvas de 0 a 1000; imprima a saída de prompt para vê-la. Uma legenda escrita manualmente nesse formato vai para o pipeline sem a etapa, como em Prompt upsampling.

Escala de orientação

O pipeline aplica a orientação sem classificador por meio de seu componente guider e não aceita um argumento guidance_scale no momento da chamada. O guider padrão é ClassifierFreeGuidance com guidance_scale=3.5, a configuração recomendada para ambos os fluxos de trabalho. Para alterá-lo, crie uma cópia atualizada do guider:

pipe.guider = pipe.guider.new(guidance_scale=5.0)

Consulte o guia de guias para alternar para um método de orientação diferente.

Modelo destilado por etapa

O checkpoint destilado por etapas gera em 16 passos sem classifier-free guidance. Seu transformer é um mapa de fluxo: em cada passo, ele recebe o timestep atual e aquele para o qual o passo salta. Ele é carregado como o modelo base (o modular_model_index.json do repositório resolve para Flux3DistilledModularPipeline e Flux3DistilledAutoBlocks); o pipeline não possui guider e não aceita negative_prompt:

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt=prompt, generator=torch.Generator().manual_seed(0), output="images")[0]

Ele atende aos mesmos dois fluxos de trabalho que o modelo base. num_inference_steps tem o valor padrão de 16; o modelo é treinado para 4 a 16 etapas.

Geração reproduzível

Um generator fixa o ruído que o pipeline sorteia (veja Reprodutibilidade). Para reutilizar um ruído sorteado em outro lugar, passe-o como latents com a forma (batch_size, 128, height // 16, width // 16). Por exemplo, a implementação da BFL sorteia seu ruído como tokens de imagem na CPU e o converte para bf16; isso reproduz sua amostra para uma semente dada:

height, width = 1024, 1024
h, w = height // 16, width // 16

noise = torch.randn((h * w, 128), generator=torch.Generator().manual_seed(0)).to(torch.bfloat16)
latents = noise.T.reshape(1, 128, h, w)

image = pipe(prompt=prompt, latents=latents, height=height, width=width, output="images")[0]

Fluxos de trabalho

O pipeline atende a dois fluxos de trabalho, text2image e image_conditioned; o que é executado é selecionado pelas entradas (image seleciona image-to-image). from_pretrained() também pode construir um pipeline para um fluxo de trabalho com o argumento workflow, que então espera e carrega apenas os componentes necessários para esse fluxo de trabalho:

from diffusers.modular_pipelines import Flux3AutoBlocks

print(Flux3AutoBlocks().available_workflows)
# ["text2image", "image_conditioned"]

t2i = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", workflow="text2image")
print(t2i.blocks.doc)

Callbacks por etapa

Para usar uma função de callback existente, insira um bloco no loop de desruidificação. O guia de callbacks tem um exemplo simples com o bloco CallbackOnStepEnd e o auxiliar walk_denoise_loops:

blocks = Flux3AutoBlocks()  # or Flux3DistilledAutoBlocks
for loop in walk_denoise_loops(blocks):
    loop.sub_blocks["callback"] = CallbackOnStepEnd()
pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")

image = pipe(prompt=caption, callback_on_step_end=my_callback, output="images")[0]

Para interromper precocemente, lance uma exceção a partir do callback; não existe a flag interrupt.

Memória

Carregar tudo em bf16 consome cerca de 39 GB de pesos: o transformer tem 5,5B parâmetros, o codificador de texto Qwen3-VL-4B tem 4B e o prompt upsampler tem 9B (cerca de 19 GB por si só), com o VAE de imagem em fp32. Um pipeline construído sem a etapa de upsampler (veja lá) carrega cerca de 20 GB. Para GPUs com menos memória, habilite o offloading de componentes; o gerenciador move os componentes entre a CPU e a GPU conforme cada etapa os necessita, incluindo o upsampler:

from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", components_manager=manager)
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
manager.enable_auto_cpu_offload(device="cuda")

Carregamento de arquivo único

Flux3Transformer2DModel carrega o transformer diretamente de um pacote de modelo da Black Forest Labs com from_single_file(). O pacote config.json não é lido; passe a configuração do diffusers com config e subfolder.

import torch
from diffusers import Flux3Transformer2DModel, ModularPipeline

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.update_components(transformer=transformer)
pipe.to("cuda")

Carregue primeiro os outros componentes pelo nome: load_components() sem names também carregaria o transformer do repositório do pipeline.

O carregamento dos checkpoints de arquivo único FP8r e NVFP4 também é suportado. Ambos são carregados por meio da mesma chamada com um BFLQuantizationConfig. Consulte o guia de quantização BFL para os requisitos de kernel de cada esquema.

from diffusers import BFLQuantizationConfig

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Ao carregar os checkpoints destilados por etapa, precisamos de seus configs (flow_map=True):

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Flux3ModularPipeline

Flux3AutoBlocks

Flux3DistilledAutoBlocks

Flux3DistilledModularPipeline