diffusers/main/pt/api/models/qwenimage21_transformer2d.md

QwenImage21Transformer2DModel

O transformer de fluxo único usado pelo Qwen-Image 2.1. Os latentes de texto e imagem compartilham uma única sequência, e uma única projeção de modulation compartilhada alimenta todos os blocos.

Dois comportamentos distinguem o 2.1 dos transformers QwenImage anteriores:

• Atenção causal por bloco — a atenção segue (q_idx >= kv_idx) or same_image_block, de modo que a sequência conjunta é causal, enquanto cada bloco de imagem permanece internamente bidirecional. QwenImage21AttnProcessor implementa isso como uma chamada de atenção por segmento de prefixo e é o padrão. QwenImage21FlexAttnProcessor implementa isso como uma única chamada de flex_attention dirigida por um BlockMask, o que é mais rápido uma vez que o modelo é compilado. Ambos produzem os mesmos resultados.
• causal_condition — os tokens de texto e da imagem de condição são modulados a partir de t = 0, em vez do timestep amostrado. Suas ativações são independentes do passo de desruido, de modo que as chaves e valores desse prefixo podem ser armazenados em cache entre os passos por meio do argumento kv_cache.

Carregue-o com:

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

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)

Fonte

Parâmetros:

patch_size (int, padrão 1) : Comprimento do lado do patch latente dobrado na dimensão de canal. A versão 2.1 consome latentes sem patch.

in_channels (int, padrão 64) : Canais latentes da entrada.

out_channels (int, opcional, padrão 64) : Canais latentes da saída. Usa in_channels como padrão.

num_layers (int, padrão 32) : Número de blocos de fluxo único.

attention_head_dim (int, padrão 128) : Canais por cabeça de atenção.

num_attention_heads (int, padrão 32) : Número de cabeças de atenção.

context_in_dim (int, padrão 4096) : Dimensão do canal de encoder_hidden_states.

mlp_ratio (int, padrão 3) : Fator de expansão do feed-forward.

axes_dims_rope (tuple[int], padrão (16, 56, 56)) : Dimensões rotativas para os eixos de quadro, altura e largura.

eps (float, padrão 1e-6) : Epsilon para as camadas de normalização.

causal_condition (bool, padrão True) : Modula os tokens de texto e de imagem de condição a partir de t = 0. Necessário para o cache de KV.

O Transformer de fluxo único usado pelo Qwen-Image 2.1.

Os latentes de texto e imagem compartilham uma única sequência: os tokens da imagem de condição são substituídos no fluxo de texto nas posições reservadas para eles pelo codificador de visão-linguagem, e os tokens da imagem de destino são anexados. Uma única projeção de modulation compartilhada alimenta todos os blocos, de modo que os blocos não possuem parâmetros de modulação próprios.

Dois comportamentos distinguem a 2.1:

• Atenção causal por bloco — a atenção segue (q_idx >= kv_idx) or same_image_block, de modo que a sequência é causal, enquanto cada bloco de imagem permanece internamente bidirecional. O backend de atenção flex oferece atenção eficiente em uma única passagem; sem ele, o modelo usa um prefill SDPA exato em múltiplas passagens que processa cada bloco separadamente.
• causal_condition — os tokens de texto e da imagem de condição são modulados a partir de t = 0 em vez do timestep amostrado, o que também torna suas ativações independentes do timestep e, portanto, cacheáveis entre as etapas de desruidamento.

build_token_metadata[[diffusers.QwenImage21Transformer2DModel.build_token_metadata]]

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

Fonte

Parâmetros:

image_pad_mask (torch.Tensor) : (seq_len,) bool, True nas posições dos tokens de imagem.

img_shapes (list[tuple[int, int, int]]) : (frame, height, width) por imagem em tokens latentes, com as imagens de condição primeiro e a imagem de destino por último.

Retorna: tuple[torch.Tensor, torch.Tensor]

image_ids (seq_len,) com -1 nas posições de texto e um id único por bloco de imagem, e target_token_mask (seq_len,) marcando os tokens da imagem alvo.

Etiquete cada token da sequência conjunta com o bloco de imagem ao qual ele pertence.

As fronteiras dos blocos vêm das contagens de tokens em img_shapes, não de sequências de True em image_pad_mask: duas imagens de condição que por acaso ficam uma ao lado da outra, sem texto entre elas, formam uma única sequência, mas devem permanecer como blocos separados; caso contrário, elas fariam atenção bidirecional entre si.

forward[[diffusers.QwenImage21Transformer2DModel.forward]]

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)

Fonte

Parâmetros:

hidden_states (torch.Tensor de forma (batch_size, image_sequence_length, in_channels)) : Latentes empacotados, com as imagens de condição primeiro e a imagem de destino por último.

encoder_hidden_states (torch.Tensor de forma (batch_size, text_sequence_length, context_in_dim)) : Incorporações de texto do codificador de visão-linguagem.

timestep (torch.Tensor) : Etapa atual de remoção de ruído, escalada para [0, 1].

img_shapes (list[list[tuple[int, int, int]]]) : Lista por amostra de (frame, height, width) em tokens latentes, com as imagens de condição primeiro e a imagem de destino por último. Todas as amostras devem compartilhar um layout.

img_mask (torch.Tensor de forma (batch_size, vlm_sequence_length)) : True nos slots de imagem do codificador de visão-linguagem, cada um representando um grupo de 2x2 tokens latentes.

encoder_hidden_states_mask (torch.Tensor, opcional) : (batch_size, text_sequence_length) bool que marca os tokens de texto válidos. As posições preenchidas (padded) são excluídas da atenção.

kv_cache (QwenImage21KVCache, opcional) : Contêiner de cache. Passe junto com kv_cache_mode para habilitar o cache de KV de prefixo.

kv_cache_mode (str, opcional) : "extract" para pré-preencher o cache (primeira etapa de desruidamento), "cached" para decodificar a partir dele (etapas posteriores). Exige causal_condition=True.

attention_kwargs (dict, opcional) : Encaminhado aos processadores de atenção e carrega scale para as camadas LoRA.

return_dict (bool, opcional, padrão True) : Se deve ou não retornar um Transformer2DModelOutput em vez de uma tupla simples.

Retorna: Transformer2DModelOutput ou tuple

Transformer2DModelOutput se return_dict for True, caso contrário, uma tuple simples cujo primeiro elemento são os latentes desruídos.

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

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

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

Fonte

Parâmetros:

sample (torch.Tensor de forma (batch_size, num_channels, height, width) ou (batch size, num_vector_embeds - 1, num_latent_pixels) se Transformer2DModel for discreto) : A saída dos estados ocultos condicionada à entrada encoder_hidden_states. Se discreto, retorna distribuições de probabilidade para os pixels latentes sem ruído.

A saída de Transformer2DModel.