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

Transformer single-stream yang digunakan oleh Qwen-Image 2.1. Laten teks dan gambar berbagi satu urutan, dan satu proyeksi modulation bersama memberi makan setiap blok.

Dua perilaku membedakan 2.1 dari transformer QwenImage sebelumnya:

  • Atensi kausal blok — atensi mengikuti (q_idx >= kv_idx) or same_image_block, sehingga urutan gabungan bersifat kausal sementara setiap blok gambar tetap bidireksional secara internal. QwenImage21AttnProcessor mengimplementasikannya sebagai satu panggilan atensi per segmen prefiks dan merupakan default. QwenImage21FlexAttnProcessor mengimplementasikannya sebagai satu panggilan flex_attention yang digerakkan oleh BlockMask, yang lebih cepat setelah model dikompilasi. Keduanya menghasilkan hasil yang sama.
  • causal_condition — token teks dan gambar kondisi dimodulasi dari t = 0, bukan dari timestep yang disampel. Aktivasi mereka independen dari langkah denoising, sehingga kunci dan nilai dari prefiks tersebut dapat di-cache melintasi langkah-langkah melalui argumen kv_cache.

Muat dengan:

import torch
from diffusers import QwenImage21Transformer2DModel

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

QwenImage21Transformer2DModel

kelas 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 )

Parameter

  • patch_size (int, defaultnya 1) — Panjang sisi dari patch laten yang dilipat ke dimensi channel. Versi 2.1 mengonsumsi laten tanpa patch.
  • in_channels (int, defaultnya 64) — Saluran laten dari input.
  • out_channels (int, opsional, defaultnya 64) — Saluran laten dari output. Kembali ke in_channels.
  • num_layers (int, defaultnya 32) — Jumlah blok single-stream.
  • attention_head_dim (int, defaultnya 128) — Jumlah channel per kepala perhatian.
  • num_attention_heads (int, defaultnya 32) — Jumlah kepala perhatian (attention heads).
  • context_in_dim (int, defaultnya 4096) — Dimensi channel dari encoder_hidden_states.
  • mlp_ratio (int, defaultnya 3) — Faktor ekspansi feed-forward.
  • axes_dims_rope (tuple[int], defaultnya (16, 56, 56)) — Dimensi rotasi untuk sumbu frame, tinggi, dan lebar.
  • eps (float, defaultnya 1e-6) — Epsilon untuk lapisan norm.
  • causal_condition (bool, defaultnya True) — Modulasi token teks dan gambar kondisi dari t = 0. Diperlukan untuk KV caching.

Transformer single-stream yang digunakan oleh Qwen-Image 2.1.

Latent teks dan gambar berbagi satu urutan: token gambar kondisi disubstitusikan ke dalam aliran teks pada posisi yang telah disediakan oleh encoder vision-language, dan token gambar target ditambahkan di akhir. Satu proyeksi modulation bersama memberi makan setiap blok, sehingga blok tidak memiliki parameter modulasi miliknya sendiri.

Dua perilaku yang membedakan 2.1:

  • Atensi blok-kausal — atensi mengikuti (q_idx >= kv_idx) or same_image_block, sehingga sekuens bersifat kausal sementara setiap blok gambar tetap bidireksional secara internal. Backend atensi flex memberikan atensi satu-lintas yang efisien; tanpanya, model menggunakan prefill SDPA multi-lintas yang tepat yang memproses setiap blok secara terpisah.
  • causal_condition — token teks dan gambar kondisi dimodulasi dari t = 0 alih-alih timestep yang disampelkan, yang juga membuat aktivasi mereka tidak bergantung pada timestep sehingga dapat di-cache di antara langkah-langkah denoising.

build_token_metadata

< >

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

Parameter

  • image_pad_mask (torch.Tensor) — (seq_len,) bool, True pada posisi token gambar.
  • img_shapes (list[tuple[int, int, int]]) — (frame, height, width) per gambar dalam token laten, dengan gambar kondisi di depan dan gambar target di akhir.

Mengembalikan

tuple[torch.Tensor, torch.Tensor]

image_ids (seq_len,) dengan -1 pada posisi teks dan id unik per blok gambar, serta target_token_mask (seq_len,) yang menandai token dari gambar target.

Label setiap token dari urutan gabungan dengan blok gambar yang menjadi keanggotaannya.

Batas blok berasal dari jumlah token dalam img_shapes, bukan dari rangkaian True dalam image_pad_mask: dua gambar kondisi yang kebetulan bersebelahan tanpa teks di antaranya membentuk satu rangkaian tetapi harus tetap menjadi blok terpisah, jika tidak mereka akan saling memperhatikan secara bidireksional.

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

Parameter

  • hidden_states (torch.Tensor dengan bentuk (batch_size, image_sequence_length, in_channels)) — Latents yang dikemas, dengan gambar kondisi di awal dan gambar target di akhir.
  • encoder_hidden_states (torch.Tensor dengan bentuk (batch_size, text_sequence_length, context_in_dim)) — Embedding teks dari encoder vision-language.
  • timestep (torch.Tensor) — Langkah denoising saat ini, diskalakan ke [0, 1].
  • img_shapes (list[list[tuple[int, int, int]]]) — Daftar per sampel berisi (frame, height, width) dalam token laten, dengan gambar kondisi di awal dan gambar target di akhir. Semua sampel harus berbagi tata letak yang sama.
  • img_mask (torch.Tensor dengan bentuk (batch_size, vlm_sequence_length)) — True pada slot gambar dari encoder vision-language, di mana masing-masing mewakili kelompok 2x2 token laten.
  • encoder_hidden_states_mask (torch.Tensor, opsional) — (batch_size, text_sequence_length) bool yang menandai token teks yang valid. Posisi yang di-*pad* dikecualikan dari perhatian (*attention*).
  • kv_cache (QwenImage21KVCache, opsional) — Wadah cache. Sampaikan bersama kv_cache_mode untuk mengaktifkan prefix KV caching.
  • kv_cache_mode (str, opsional) — "extract" untuk prefill cache (langkah denoising pertama), "cached" untuk decode darinya (langkah berikutnya). Memerlukan causal_condition=True.
  • attention_kwargs (dict, opsional) — Diteruskan ke prosesor perhatian, dan membawa scale untuk lapisan LoRA.
  • return_dict (bool, opsional, defaultnya True) — Apakah akan mengembalikan Transformer2DModelOutput alih-alih tuple biasa.

Mengembalikan

Transformer2DModelOutput atau tuple

Transformer2DModelOutput jika return_dict bernilai True, selain itu berupa tuple biasa yang elemen pertamanya adalah latents yang telah didenoise.

Transformer2DModelOutput

kelas diffusers.models.modeling_outputs.Transformer2DModelOutput

< >

( sample: torch.Tensor )

Parameter

  • sample (torch.Tensor dengan bentuk (batch_size, num_channels, height, width) atau (batch size, num_vector_embeds - 1, num_latent_pixels) jika Transformer2DModel bersifat diskrit) — Output hidden states yang dikondisikan pada input encoder_hidden_states. Jika diskrit, mengembalikan distribusi probabilitas untuk latent pixels yang tidak berisik.

Output dari Transformer2DModel.

Update on GitHub

←PriorTransformer QwenImageTransformer2DModel→