# 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 valores de ese prefijo son cacheables entre pasos mediante el argumento `kv_cache`.

Cárgalo con:

```python
import torch
from diffusers import QwenImage21Transformer2DModel

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

## QwenImage21Transformer2DModel[[diffusers.QwenImage21Transformer2DModel]]

#### diffusers.QwenImage21Transformer2DModel[[diffusers.QwenImage21Transformer2DModel]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L716)

**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 cuadro, 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 el almacenamiento en 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 los pasos de desruido.

#### build_token_metadata[[diffusers.QwenImage21Transformer2DModel.build_token_metadata]]

```python
build_token_metadata(image_pad_mask: Tensor, img_shapes: list[tuple[int, int, int]])
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L822)

**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]]`) : `(frame, height, width)` en tokens latentes por imagen, 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[[diffusers.QwenImage21Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_shapes: list[list[tuple[int, int, int]]], img_mask: Tensor, encoder_hidden_states_mask: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, kv_cache: diffusers.models.transformers.transformer_qwenimage21.QwenImage21KVCache | None = None, kv_cache_mode: str | None = None, return_dict: bool = True)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L862)

**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)`) : Embeddings 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, cada uno representando 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 de LoRA.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un [Transformer2DModelOutput](/docs/diffusers/main/es/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) en lugar de una tupla simple.

**Devuelve:** [Transformer2DModelOutput](/docs/diffusers/main/es/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) o `tuple`

[Transformer2DModelOutput](/docs/diffusers/main/es/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) si `return_dict` es True, de lo contrario una `tuple` simple cuyo primer elemento son los latentes desruidados.

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**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](/docs/diffusers/main/es/api/models/transformer2d#diffusers.Transformer2DModel) es discreto): las salidas de estados ocultos condicionadas a la entrada `encoder_hidden_states`. Si es discreto, devuelve distribuciones de probabilidad para los píxeles latentes sin ruido.

La salida de [Transformer2DModel](/docs/diffusers/main/es/api/models/transformer2d#diffusers.Transformer2DModel).