Hugging Face's logo

Diffusers documentation

QwenImage21Transformer2DModel

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

QwenImage21Transformer2DModel

El transformer de flujo único utilizado por Qwen-Image 2.1. Los latentes de texto e imagen comparten una sola secuencia, y una única proyección de modulation compartida alimenta cada bloque.

Dos comportamientos distinguen a 2.1 de los transformadores QwenImage anteriores:

  • Atención causal por bloques — la atención sigue (q_idx >= kv_idx) or same_image_block, de modo que la secuencia conjunta es causal mientras que cada bloque de imagen permanece internamente bidireccional. QwenImage21AttnProcessor lo implementa como una llamada de atención por segmento de prefijo y es el valor predeterminado. QwenImage21FlexAttnProcessor lo implementa como una única llamada a flex_attention controlada por una BlockMask, lo cual es más rápido una vez que el modelo está compilado. Ambos producen los mismos resultados.
  • causal_condition — los tokens de texto y de imagen de condición se modulan desde t = 0 en lugar del paso de tiempo muestreado. Sus activaciones son independientes del paso de desruido, por lo que las claves y los valores de ese prefijo son cacheables entre pasos mediante el argumento kv_cache.

Cárgalo con:

import torch
from diffusers import QwenImage21Transformer2DModel

transformer = QwenImage21Transformer2DModel.from_pretrained(
    "Qwen/Qwen-Image-2.1", subfolder="transformer", dtype=torch.bfloat16
)

QwenImage21Transformer2DModel

clase diffusers.QwenImage21Transformer2DModel

< >

( patch_size: int = 1in_channels: int = 64out_channels: int | None = 64num_layers: int = 32attention_head_dim: int = 128num_attention_heads: int = 32context_in_dim: int = 4096mlp_ratio: int = 3axes_dims_rope: tuple = (16, 56, 56)eps: float = 1e-06causal_condition: bool = True )

Parámetros

  • patch_size (int, por defecto 1) — Longitud del lado del parche latente plegado en la dimensión de canal. 2.1 consume latentes sin parchear.
  • in_channels (int, por defecto 64) — Canales latentes de la entrada.
  • out_channels (int, opcional, valor predeterminado 64) — Canales latentes de la salida. Si no se especifica, se usa in_channels.
  • num_layers (int, por defecto 32) — Número de bloques de flujo único.
  • attention_head_dim (int, por defecto 128) — Canales por cabeza de atención.
  • num_attention_heads (int, por defecto 32) — Número de cabezas de atención.
  • context_in_dim (int, por defecto 4096) — Dimensión de canal de encoder_hidden_states.
  • mlp_ratio (int, por defecto 3) — Factor de expansión de la red feed-forward.
  • axes_dims_rope (tuple[int], por defecto (16, 56, 56)) — Dimensiones rotativas para los ejes de fotograma, altura y ancho.
  • eps (float, por defecto 1e-6) — Epsilon para las capas de normalización.
  • causal_condition (bool, por defecto True) — Modula los tokens de texto y de imagen de condición desde t = 0. Es necesario para la caché de KV.

El Transformer de flujo único utilizado por Qwen-Image 2.1.

Los latentes de texto e imagen comparten una secuencia: los tokens de la imagen de condición se sustituyen en el flujo de texto en las posiciones que el codificador de visión-lenguaje reservó para ellos, y se agregan los tokens de la imagen objetivo. Una única proyección de modulation compartida alimenta a todos los bloques, por lo que los bloques no poseen parámetros de modulación propios.

Dos comportamientos distinguen a 2.1:

  • Atención causal por bloques — la atención sigue (q_idx >= kv_idx) or same_image_block, por lo que la secuencia es causal mientras que cada bloque de imagen permanece internamente bidireccional. El backend de atención flex ofrece una atención eficiente en un solo paso; sin él, el modelo utiliza un prefill SDPA exacto de múltiples pasos que procesa cada bloque por separado.
  • causal_condition — los tokens de texto y de imagen de condición se modulan desde t = 0 en lugar del paso de tiempo muestreado, lo que también hace que sus activaciones sean independientes del paso de tiempo y, por tanto, cacheables entre pasos de desruido.

build_token_metadata

< >

( image_pad_mask: Tensorimg_shapes: list ) → tuple[torch.Tensor, torch.Tensor]

Parámetros

  • image_pad_mask (torch.Tensor) — (seq_len,) bool, True en las posiciones de tokens de imagen.
  • img_shapes (list[tuple[int, int, int]]) — Por imagen, (frame, height, width) en tokens latentes, con las imágenes de condición primero y la imagen objetivo al final.

Devuelve

tuple[torch.Tensor, torch.Tensor]

image_ids (seq_len,) con -1 en las posiciones de texto y un id único por bloque de imagen, y target_token_mask (seq_len,) que marca los tokens de la imagen objetivo.

Etiqueta cada token de la secuencia conjunta con el bloque de imagen al que pertenece.

Las fronteras de los bloques provienen de las cantidades de tokens en img_shapes, no de las secuencias de True en image_pad_mask: dos imágenes de condición que resultan estar una al lado de la otra sin texto entre ellas forman una sola secuencia, pero deben mantenerse como bloques separados; de lo contrario, atenderían entre sí de forma bidireccional.

forward

< >

( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorimg_shapes: listimg_mask: Tensorencoder_hidden_states_mask: typing.Optional[torch.Tensor] = Noneattention_kwargs: dict[str, typing.Any] | None = Nonekv_cache: diffusers.models.transformers.transformer_qwenimage21.QwenImage21KVCache | None = Nonekv_cache_mode: str | None = Nonereturn_dict: bool = True ) → Transformer2DModelOutput or tuple

Parámetros

  • hidden_states (torch.Tensor de forma (batch_size, image_sequence_length, in_channels)) — Latentes empaquetados, con las imágenes de condición primero y la imagen objetivo al final.
  • encoder_hidden_states (torch.Tensor de forma (batch_size, text_sequence_length, context_in_dim)) — Incrustaciones de texto del codificador de visión-lenguaje.
  • timestep (torch.Tensor) — Paso actual de desruido, escalado a [0, 1].
  • img_shapes (list[list[tuple[int, int, int]]]) — Lista por muestra de (frame, height, width) en tokens latentes, con las imágenes de condición primero y la imagen objetivo al final. Todas las muestras deben compartir un mismo diseño.
  • img_mask (torch.Tensor de forma (batch_size, vlm_sequence_length)) — True en los espacios de imagen del codificador de visión-lenguaje, donde cada uno representa un grupo de 2x2 tokens latentes.
  • encoder_hidden_states_mask (torch.Tensor, opcional) — (batch_size, text_sequence_length) bool que marca los tokens de texto válidos. Las posiciones rellenas se excluyen de la atención.
  • kv_cache (QwenImage21KVCache, opcional) — Contenedor de caché. Pásalo junto con kv_cache_mode para habilitar la caché de KV de prefijo.
  • kv_cache_mode (str, opcional) — "extract" para prellenar la caché (primer paso de desruido), "cached" para decodificar desde ella (pasos posteriores). Requiere causal_condition=True.
  • attention_kwargs (dict, opcional) — Se reenvía a los procesadores de atención y lleva scale para las capas LoRA.
  • return_dict (bool, opcional, valor predeterminado True) — Indica si se debe devolver un Transformer2DModelOutput en lugar de una tupla simple.

Devuelve

Transformer2DModelOutput o tuple

Transformer2DModelOutput si return_dict es True, en caso contrario una tuple simple cuyo primer elemento son los latentes desruidos.

Transformer2DModelOutput

clase diffusers.models.modeling_outputs.Transformer2DModelOutput

< >

( sample: torch.Tensor )

Parámetros

  • sample (torch.Tensor de forma (batch_size, num_channels, height, width) o (batch size, num_vector_embeds - 1, num_latent_pixels) si Transformer2DModel es discreto) — La salida de estados ocultos condicionada a la entrada encoder_hidden_states. Si es discreto, devuelve distribuciones de probabilidad para los píxeles latentes sin ruido.

La salida de Transformer2DModel.

Update on GitHub

←PriorTransformer QwenImageTransformer2DModel→