FLUX 3 Image Klein

FLUX 3 Image Klein es un modelo de generación de imágenes de 5.6B de Black Forest Labs: un único transformador (Flux3Transformer2DModel) genera imágenes a partir de un prompt de texto, solo o junto con una o más imágenes de referencia. La condicionación de texto proviene de Qwen3-VL, y las imágenes utilizan el autoencoder empaquetado de FLUX.2 (AutoencoderKLFlux2).

FLUX 3 Image Klein se distribuye como un pipeline modular. Comienza con una generación de imagen 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 es la única entrada obligatoria: el pipeline aplica la configuración de muestreo recomendada (50 pasos, escala de guía 3.5, desplazamiento del programador 6.93) y genera imágenes de 1024 x 1024 píxeles de forma predeterminada. Acepta un solo prompt por llamada; use num_images_per_prompt para generar varias imágenes a partir del mismo prompt.

Como puede ver en el ejemplo anterior, la carga y la ejecución difieren un poco de un DiffusionPipeline. La carga es perezosa: from_pretrained() solo construye el pipeline, y llama a load_components() para cargar los pesos. Una llamada devuelve el estado del pipeline, y solicita lo que necesita con output: output="images" aquí, o output=["images", "prompt"] para obtener también la descripción que escribió el amplificador de prompts.

Si estás trabajando con ModularPipeline por primera vez, lee el quickstart y Coming from DiffusionPipeline si conoces las pipelines estándar. Además de la carga y las salidas, hay algunas otras diferencias: guidance, callbacks y offloading.

Ampliación de prompts

Prompting matters: FLUX 3 Image Klein takes full scene captions that describe the subject, composition, lighting, and atmosphere, not short prompts; a request sent as typed gives generic output. That is why the pipeline runs the prompt upsampler first on every request, text-to-image and editing alike. It is a separate 9B model from Black Forest Labs (black-forest-labs/flux-3-image-klein-pup) that expands prompt into such a caption before the text encoder, and a short prompt is all it takes.

El amplificador de prompts convierte una solicitud breve, junto con las imágenes de referencia en caso de edición, en la descripción completa de la escena que recibe el modelo: medio y estilo, escena, iluminación y cámara, cada sujeto con sus colores, materiales y posición en el encuadre. Un solo modelo cubre texto a imagen, edición con imágenes de referencia y diseño con cajas. La descripción que genera se devuelve como salida de prompt. En el ejemplo anterior, solicítela junto con las imágenes para ver lo que recibió el modelo de imagen:

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. ...

La leyenda completa tiene aproximadamente 240 palabras; max_new_tokens limita su longitud (3584 por defecto).

Puedes imprimir el doc del paso para ver qué recibe y qué escribe:

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.

Como otros bloques de la pipeline, el bloque prompt_upsampler también se ejecuta de forma independiente. La forma recomendada es extraerlo de los bloques: el bloque extraído se convierte en un amplificador independiente, y los bloques restantes forman una pipeline que toma la descripción ampliada 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]

De esta forma, puede servirse como una etapa independiente, en su propia GPU o detrás de su propio endpoint, y una interfaz de usuario puede mostrar la descripción que escribió y permitir al usuario editarla antes de generar. Cualquier otro LLM puede ocupar el lugar del amplificador, con los mismos prompts de sistema: proporciónale system_prompts["t2i"] del repositorio del amplificador (o "i2i", con las referencias primero en el mensaje del usuario) como prompt de sistema y la solicitud como mensaje del usuario, y pasa la descripción que devuelve como prompt a pipe.

Imagen a imagen

Pase una o más imágenes de referencia con image. Una sola referencia se mantiene íntegra: solo se reduce si supera los 4 megapíxeles, se rellena hasta la cuadrícula de 16 píxeles y la generación usa su tamaño por defecto, por lo que la edición se devuelve con el tamaño de la entrada. Varias referencias se ajustan cada una a menos de 1 megapíxel y se recortan a la cuadrícula, y la generación usa por defecto el tamaño de la primera. Un height/width dado anula el valor por defecto. Describa la imagen objetivo como una leyenda completa de la referencia con su edición integrada, en lugar de una instrucción de una línea, o deje que el prompt upsampler la escriba a partir de la instrucción y las referencias:

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

Con varias referencias, hágase referencia a ellas como la primera imagen, la segunda imagen, … en el orden en que se pasan a image; la descripción las denomina <ref_image_0>, <ref_image_1>, … para el modelo de imagen:

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]

Pasa height y/o width para anular el tamaño derivado.

Control de diseño

To place content explicitly, pass boxes: for each element an id, a short desc, and a bbox of [y_min, x_min, y_max, x_max] in 0-1 (origin top-left), so it is independent of the output size. The upsampler writes the caption around them, citing each element as <id>, and appends the table of boxes, yours kept exactly:

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"])

Al editar, una caja indica su origen con from: "target" con un tgt_bbox añade un nuevo elemento allí, "ref_image_0" con un src_bbox y un tgt_bbox mueve un elemento de esa referencia (las cajas iguales lo mantienen en su 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"])

La leyenda que lee el modelo de imagen tiene los elementos etiquetados con <id> en el texto y la tabla añadida como JSON, con las cajas en un lienzo de 0 a 1000; imprime la salida de prompt para verla. Una leyenda escrita a mano en ese formato se envía a la pipeline sin ese paso, como en Prompt upsampling.

Escala de guía

El pipeline aplica la guía sin clasificador a través de su componente guider y no acepta un argumento guidance_scale en el momento de la llamada. El guider predeterminado es ClassifierFreeGuidance con guidance_scale=3.5, la configuración recomendada para ambos flujos de trabajo. Para cambiarlo, cree una copia actualizada del guider:

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

Consulte la guía de guías para cambiar a un método de guía diferente.

Modelo destilado por pasos

El checkpoint destilado por pasos genera en 16 pasos sin guía libre de clasificador. Su transformer es un mapa de flujo: en cada paso se le indica el paso temporal actual y el paso al que salta. Se carga como el modelo base (el modular_model_index.json del repositorio se resuelve en Flux3DistilledModularPipeline y Flux3DistilledAutoBlocks); el pipeline no tiene guider y no acepta 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]

Sirve para los mismos dos flujos de trabajo que el modelo base. num_inference_steps tiene un valor predeterminado de 16; el modelo se entrena para 4 a 16 pasos.

Generación reproducible

Un generator fija el ruido que extrae el pipeline (consulte Reproducibilidad). Para reutilizar un ruido extraído en otro lugar, páselo como latents con forma (batch_size, 128, height // 16, width // 16). Por ejemplo, la implementación de BFL extrae su ruido como tokens de imagen en la CPU y lo convierte a bf16; esto reproduce su muestra para una semilla 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]

Flujos de trabajo

El pipeline atiende dos flujos de trabajo, text2image y image_conditioned; el que se ejecuta se elige según las entradas (image selecciona image-to-image). from_pretrained() también puede construir un pipeline para un solo flujo de trabajo con el argumento workflow, que entonces solo espera y carga los componentes que ese flujo de trabajo necesita:

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 paso

Para usar una función de callback existente, inserte un bloque en el bucle de desruido. La guía de callbacks tiene un ejemplo sencillo con el bloque CallbackOnStepEnd y el helper 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 detener el proceso de forma anticipada, lanza una excepción desde el callback; no existe una bandera interrupt.

Memoria

Cargar todo en bf16 requiere aproximadamente 39 GB de pesos: el transformer tiene 5.5B de parámetros, el codificador de texto Qwen3-VL-4B tiene 4B y el prompt upsampler tiene 9B (unos 19 GB por sí solo), con el VAE de imagen en fp32. Un pipeline construido sin el paso de upsampler (ver allí) carga aproximadamente 20 GB. Para GPUs con menos memoria, habilite el offloading de componentes; el gestor mueve los componentes entre la CPU y la GPU según lo que necesite cada paso, incluido el 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")

Carga de un solo archivo

Flux3Transformer2DModel carga el transformer directamente desde un paquete de modelos de Black Forest Labs con from_single_file(). El paquete config.json no se lee; pase la configuración de diffusers con config y 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")

Cargue primero los demás componentes por nombre: load_components() sin names también cargaría el transformer del repositorio de la pipeline.

La carga de los puntos de control de archivo único FP8r y NVFP4 también está admitida. Ambos se cargan mediante la misma llamada con una BFLQuantizationConfig. Consulte la guía de cuantización de BFL para conocer los 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,
)

Al cargar los puntos de control destilados por pasos, necesitamos sus configuraciones (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