Hugging Face's logo

Diffusers documentation

Qwen-Image 2.1

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Qwen-Image 2.1

Qwen-Image 2.1 codifica el prompt y las imágenes de condición junto con un modelo Qwen3-VL y luego desruidifica la imagen objetivo con un transformer de flujo único y causal por bloques. Consulte QwenImage21Transformer2DModel para la atención causal por bloques, los procesadores de atención y causal_condition.

Los valores predeterminados son los que recomienda Qwen: 40 pasos y sin guía. Pasa un negative_prompt junto con true_cfg_scale > 1 para activar la guía libre de clasificador, lo que duplica el trabajo por paso.

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16).to("cuda")

# Text-to-image
image = pipe("A capybara wearing a wizard hat, oil painting").images[0]
image.save("t2i.png")

# Image-conditioned editing
edited = pipe("Move it to a snowy mountain top", image=image).images[0]
edited.save("edit.png")

Imágenes de múltiples condiciones

Pase una lista a image y cada entrada se convierte en su propio bloque en la secuencia conjunta: el codificador de Qwen3-VL las ve como contexto visual y el VAE aporta sus tokens latentes. La atención causal por bloques mantiene cada bloque internamente bidireccional, mientras permite que los bloques posteriores y la imagen objetivo atiendan a los anteriores, por lo que el orden en que las pase es el orden en que el modelo las lee.

edited = pipe("Put the flowers from the first image into the second scene", image=[flowers, scene]).images[0]

Atención más rápida con flex_attention

El QwenImage21AttnProcessor predeterminado ejecuta el prefill causal por bloques como una llamada de atención por segmento de prefijo. No requiere compilación y funciona en cualquier compilación de PyTorch. QwenImage21FlexAttnProcessor expresa la misma máscara como una única llamada a flex_attention, lo cual es más rápido una vez que el modelo está compilado.

Compila el modelo al cambiar al procesador flex. Un flex_attention sin compilar materializa la matriz completa de puntuaciones de atención en fp32, lo cual es mucho más lento y agota la memoria a alta resolución.

from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor

pipe.transformer.set_attn_processor(QwenImage21FlexAttnProcessor())
pipe.transformer.compile()

Carga de puntos de control de un solo archivo

import torch
from diffusers import QwenImage21Pipeline, QwenImage21Transformer2DModel

transformer = QwenImage21Transformer2DModel.from_single_file(
    "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/blob/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
    dtype=torch.bfloat16,
)
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", transformer=transformer, dtype=torch.bfloat16).to(
    "cuda"
)

Sigmas de muestreo

Los autores de modelos pueden configurar una cuadrícula de muestreo predeterminada con sample_sigmas en la configuración de la pipeline. Al cargar un checkpoint publicado, su cuadrícula predeterminada y la configuración del scheduler se restauran automáticamente.

Para experimentar con una cuadrícula diferente en tiempo de ejecución, pase sigmas a la llamada de la pipeline:

# Use the checkpoint's default sampling grid.
image = pipe(prompt).images[0]

# Override the default grid for this call.
image = pipe(prompt, sigmas=[1.0, 0.8, 0.5, 0.2]).images[0]

La cuadrícula personalizada anterior ilustra la API; la calidad de la generación depende del checkpoint y de la cuadrícula. Las listas de Sigma excluyen el sigma terminal, que el scheduler añade. Los sigmas explícitos reemplazan a los sample_sigmas configurados, y cualquiera de las dos listas determina el número de pasos en lugar de num_inference_steps. Si no se proporciona ninguna, el pipeline utiliza num_inference_steps para generar el schedule. El scheduler aplica su procesamiento configurado a cualquiera de las dos cuadrículas.

Modular

Qwen-Image 2.1 también está disponible como pipeline modular. Los mismos bloques ejecutan la generación de texto a imagen y la generación condicionada por imagen: pase image para condicionar en una o más imágenes. La guía sin clasificador se configura a través del componente guider en lugar de un argumento de llamada true_cfg_scale, y la caché KV de prefijo está activada por defecto (use_kv_cache=False la desactiva).

import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

# Turn classifier-free guidance on for an edit.
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=4.0))
edited = pipe(prompt="Move it to a snowy mountain top", negative_prompt="blurry", image=image).images[0]

El checkpoint de Turbo se corresponde con sus propios bloques (QwenImage21TurboAutoBlocks): se ejecuta sin un guider, no toma un negative_prompt y muestrea la cuadrícula de sigma que incluye. ModularPipeline.from_pretrained selecciona los bloques de Turbo a partir de la entrada sample_sigmas en la configuración del checkpoint, por lo que no es necesario configurar nada:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

QwenImage21Pipeline

clase diffusers.QwenImage21Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImage21text_encoder: Qwen3VLForConditionalGenerationprocessor: Qwen3VLProcessortransformer: QwenImage21Transformer2DModelsample_sigmas: list[float] | None = None )

Parámetros

  • scheduler (FlowMatchEulerDiscreteScheduler) — Programador utilizado para desruidar los latentes de la imagen codificada.
  • vae (AutoencoderKLQwenImage21) — Autoencoder variacional que mapea imágenes hacia y desde el espacio latente de 64 canales.
  • text_encoder (Qwen3VLForConditionalGeneration) — Modelo Qwen3-VL que genera las incrustaciones conjuntas de texto e imagen.
  • processor (Qwen3VLProcessor) — Procesador que construye la plantilla de chat y tokeniza el prompt y las imágenes de condición.
  • transformer (QwenImage21Transformer2DModel) — El transformer de flujo único con causalidad por bloques que desruidiza los latentes.
  • sample_sigmas (list[float], opcional) — Sigmas de muestreo predeterminados configurados por el autor del modelo, excluyendo la sigma terminal. Su longitud determina el número de pasos de desruido. Para experimentar con una cuadrícula diferente en tiempo de ejecución, pase sigmas a __call__.

Generación de texto a imagen y generación condicionada por imagen con Qwen-Image 2.1.

Las imágenes de prompt y de condición se codifican juntas mediante un modelo Qwen3-VL, por lo que una imagen de condición ocupa los espacios de visión que el codificador reservó para ella y el transformer ve una secuencia intercalada de texto e imágenes.

__call__

< >

( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']output_resolution: int = 1024use_kv_cache: bool = True ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

Parámetros

  • prompt (str o list[str], opcional) — El prompt para guiar la generación de imágenes. Pasa prompt_embeds en su lugar para proporcionar embeddings directamente.
  • image (PipelineImageInput, opcional) — Una o más imágenes de condición, como una imagen PIL o un array de numpy. Se codifican por el codificador de texto como contexto visual y por el VAE en tokens latentes que se antepone al ruido. Una lista es un conjunto de imágenes compartido por cada prompt del lote, no una entrada por prompt.
  • negative_prompt (str o list[str], opcional) — El prompt que no debe guiar la generación de la imagen. Se ignora cuando true_cfg_scale no es mayor que 1.
  • true_cfg_scale (float, opcional, valor predeterminado 1.0) — Escala de guía sin clasificador. Se activa con true_cfg_scale > 1 junto con un prompt negativo. Qwen-Image 2.1 está diseñado para muestrear sin guía, por lo que el valor predeterminado es 1.0.
  • height (int, opcional) — Altura en píxeles de la imagen generada. Si se omite, se deriva de la relación de aspecto de la imagen de condición.
  • width (int, opcional) — Ancho en píxeles de la imagen generada. Si se omite, se deriva de la relación de aspecto de la imagen de condición.
  • num_inference_steps (int, opcional, valor predeterminado 40) — Número de pasos de desruido. Se ignora cuando se usa sigmas o el sample_sigmas configurado en el pipeline; la longitud de esa secuencia determina el número de pasos.
  • sigmas (list[float], opcional) — Sigmas de muestreo a probar en esta llamada, excluyendo la sigma terminal. Anula el sample_sigmas configurado en el pipeline y determina el número de pasos de desruido. El programador aplica su procesamiento configurado a estos valores.
  • num_images_per_prompt (int, opcional, valor predeterminado 1) — Número de imágenes generadas por indicación.
  • generator (torch.Generator o list[torch.Generator], opcional) — Generador(es) para hacer la generación determinista.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas que omiten la codificación del prompt. Pasa prompt_embeds_mask junto con ellas.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara booleana que marca las posiciones válidas de prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas, utilizadas en lugar de negative_prompt. Pasa negative_prompt_embeds_mask junto con ellas.
  • negative_prompt_embeds_mask (torch.Tensor, opcional) — Máscara booleana que marca las posiciones válidas de negative_prompt_embeds.
  • output_type (str, opcional, por defecto "pil") — Formato de salida, "pil", "np", "pt" o "latent".
  • return_dict (bool, opcional, valor predeterminado True) — Si se debe devolver un ~pipelines.qwenimage.QwenImagePipelineOutput en lugar de una tupla simple.
  • attention_kwargs (dict, opcional) — Se transmite al procesador de atención.
  • callback_on_step_end (Callable, opcional) — Se llama al final de cada paso de desruido.
  • callback_on_step_end_tensor_inputs (list[str], opcional, valor predeterminado ["latents"]) — Tensores del bucle de desruido que se pasan a callback_on_step_end. Deben estar listados en _callback_tensor_inputs del pipeline.
  • output_resolution (int, opcional, valor predeterminado 1024) — Lado objetivo utilizado para derivar height/width y para redimensionar las imágenes de condición.
  • use_kv_cache (bool, opcional, por defecto True) — Almacena en caché las claves y valores del texto y de la imagen de condición después del primer paso. Es válido porque causal_condition modula esos tokens desde t = 0, haciendo que sus activaciones sean independientes del paso. Alternar esta opción no reproduce la misma imagen bit a bit en precisión reducida. La caché hace que el paso de decodificación atienda con un diseño de secuencia diferente al del paso de prellenado, por lo que ambos se dividen en bloques de forma distinta y caen en redondeos diferentes; ambos coinciden con una referencia en fp32 dentro de la misma tolerancia. Una diferencia de un ULP en el primer bloque se amplifica entonces con 32 bloques y cada paso del muestreador, por lo que ambas configuraciones producen muestras igualmente válidas pero visualmente distintas. Para fijar una muestra, fije esta bandera.

    Alternar esta opción no reproduce la misma imagen bit a bit en precisión reducida. La caché hace que el paso de decodificación atienda con un diseño de secuencia diferente al del paso de prellenado, por lo que los dos se dividen en bloques de forma distinta y caen en redondeos diferentes; ambos coinciden con una referencia en fp32 dentro de la misma tolerancia. Una diferencia de un ULP en el primer bloque se amplifica entonces por 32 bloques y cada paso del muestreador, por lo que las dos configuraciones producen muestras igualmente válidas pero visualmente distintas. Fije una muestra fijando esta bandera.

Devuelve

~pipelines.qwenimage.QwenImagePipelineOutput o tuple

~pipelines.qwenimage.QwenImagePipelineOutput si return_dict es True, de lo contrario una tuple cuyo primer elemento es una lista con las imágenes generadas.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

>>> import torch
>>> from diffusers import QwenImage21Pipeline

>>> pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A capybara wearing a wizard hat, reading a book by candlelight, oil painting"
>>> image = pipe(prompt).images[0]
>>> image.save("qwenimage21.png")

encode_prompt

< >

( prompt: str | list[str]image: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneimage_pad_mask: typing.Optional[torch.Tensor] = None )

Parámetros

  • prompt (str o list[str], opcional) — Prompt a codificar.
  • image (list[PipelineImageInput], opcional) — Imágenes de condición para codificar junto con el prompt.
  • device (torch.device) — Dispositivo de Torch.
  • num_images_per_prompt (int) — Número de imágenes generadas por prompt.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Omite la codificación si se proporciona.

QwenImagePipelineOutput

clase diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

Parámetros

  • images (list[PIL.Image.Image] o np.ndarray) — lista de imágenes PIL desruidas de longitud batch_size o array de numpy de forma (batch_size, height, width, num_channels). Las imágenes PIL o el array de numpy presentan las imágenes desruidas del pipeline de difusión.

Clase de salida para las tuberías de Stable Diffusion.

QwenImage21ModularPipeline

clase diffusers.QwenImage21ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Un ModularPipeline para Qwen-Image 2.1.

QwenImage21AutoBlocks

clase diffusers.QwenImage21AutoBlocks

< >

( )

Pipeline modular automático para la generación de texto a imagen y generación condicionada por imagen usando Qwen-Image 2.1.

  • para la generación de texto a imagen, solo necesitas proporcionar prompt
  • para la generación condicionada por imagen, debes proporcionar prompt e image (una imagen o una lista)

Flujos de trabajo admitidos:

  • text2image: requiere prompt
  • image_conditioned: requiere prompt, image

Componentes: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) guider (ClassifierFreeGuidance) transformer (QwenImage21Transformer2DModel)

Entradas: image (Image | list, opcional): Imagen(es) de referencia para el desruido. Puede ser una sola imagen o una lista de imágenes. output_resolution (int, opcional, valor predeterminado 1024): Longitud del lado objetivo utilizada para derivar el tamaño de salida y para redimensionar las imágenes de condición. prompt (str): El prompt o prompts para guiar la generación de imágenes. negative_prompt (str, opcional): El prompt o prompts que no deben guiar la generación de imágenes. generator (Generator, opcional): Generador de Torch para una generación determinista. num_images_per_prompt (int, opcional, valor predeterminado 1): El número de imágenes a generar por prompt. height (int, opcional): La altura en píxeles de la imagen generada. width (int, opcional): El ancho en píxeles de la imagen generada. image_latents (list, opcional): Latentes normalizados de cada imagen de condición. Pueden generarse desde el paso vae_encoder. latents (Tensor): Latentes ruidosos pregenerados para la generación de imágenes. num_inference_steps (int): El número de pasos de desruido. sigmas (list, opcional): Sigmas personalizados para el proceso de desruido. use_kv_cache (bool, opcional, valor predeterminado True): Almacena en caché las claves y valores del texto y de la imagen de condición después del primer paso. Es válido porque causal_condition modula esos tokens desde t = 0, lo que hace que sus activaciones sean independientes del paso. Alternar esta opción no reproduce la misma imagen bit a bit en precisión reducida. attention_kwargs (dict, opcional): Kwargs adicionales para los procesadores de atención. *denoiser_input_fields (None,opcional): entradas del modelo condicional para el desruidador: por ejemplo, prompt_embeds, negative_prompt_embeds, etc. output_type (str,opcional*, valor predeterminado pil): Formato de salida: ‘pil’, ‘np’, ‘pt’.

Salidas: images (list): Imágenes generadas.

QwenImage21TurboModularPipeline

clase diffusers.QwenImage21TurboModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Un ModularPipeline para Qwen-Image 2.1 Turbo, el punto de control acelerado que muestrea en pocos pasos sin guía.

QwenImage21TurboAutoBlocks

clase diffusers.QwenImage21TurboAutoBlocks

< >

( )

Auto Modular pipeline para la generación de texto a imagen y la generación condicionada por imagen usando Qwen-Image 2.1 Turbo, el checkpoint acelerado que muestrea su cuadrícula de sigma incluida en pocos pasos sin guía.

  • para la generación de texto a imagen, solo necesitas proporcionar prompt
  • para la generación condicionada por imagen, debes proporcionar prompt e image (una imagen o una lista)

Flujos de trabajo admitidos:

  • text2image: requiere prompt
  • image_conditioned: requiere prompt, image

Componentes: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) transformer (QwenImage21Transformer2DModel)

Configs: sample_sigmas (predeterminado: None): Cuadrícula de muestreo que se incluye con el punto de control, utilizada cuando no se pasa sigmas.

Entradas: image (Image | list, opcional): Imagen(es) de referencia para el desruido. Puede ser una sola imagen o una lista de imágenes. output_resolution (int, opcional, valor predeterminado 1024): Longitud del lado objetivo utilizada para derivar el tamaño de salida y para redimensionar las imágenes de condición. prompt (str): El prompt o prompts para guiar la generación de imágenes. generator (Generator, opcional): Generador de Torch para una generación determinista. num_images_per_prompt (int, opcional, valor predeterminado 1): El número de imágenes a generar por prompt. height (int, opcional): La altura en píxeles de la imagen generada. width (int, opcional): El ancho en píxeles de la imagen generada. image_latents (list, opcional): Latentes normalizados de cada imagen de condición. Pueden generarse desde el paso vae_encoder. latents (Tensor): Latentes ruidosos pregenerados para la generación de imágenes. num_inference_steps (int): El número de pasos de desruido. sigmas (list, opcional): Sigmas personalizados para el proceso de desruido. use_kv_cache (bool, opcional, valor predeterminado True): Almacena en caché las claves y valores del texto y de la imagen de condición después del primer paso. Es válido porque causal_condition modula esos tokens desde t = 0, lo que hace que sus activaciones sean independientes del paso. Alternar esta opción no reproduce la misma imagen bit a bit en precisión reducida. attention_kwargs (dict, opcional): Kwargs adicionales para los procesadores de atención. *denoiser_input_fields (None,opcional): entradas del modelo condicional para el desruidador: p. ej. prompt_embeds, negative_prompt_embeds, etc. output_type (str,opcional*, valor predeterminado pil): Formato de salida: ‘pil’, ‘np’, ‘pt’.

Salidas: images (list): Imágenes generadas.

Update on GitHub

←PRX Pixel QwenImage→