# QwenImage21Transformer2DModel

Transformer luồng đơn được sử dụng bởi Qwen-Image 2.1. Latent của văn bản và hình ảnh chia sẻ một chuỗi duy nhất, và một phép chiếu `modulation` dùng chung duy nhất cung cấp cho mọi khối.

Hai hành vi phân biệt 2.1 với các transformer QwenImage trước đó:

- **Chú ý nhân quả theo khối** — chú ý tuân theo `(q_idx >= kv_idx) or same_image_block`, do đó chuỗi kết hợp là nhân quả trong khi mỗi khối ảnh vẫn giữ tính hai chiều bên trong. `QwenImage21AttnProcessor` triển khai điều này dưới dạng một lần gọi chú ý cho mỗi đoạn tiền tố và là mặc định. `QwenImage21FlexAttnProcessor` triển khai dưới dạng một lần gọi `flex_attention` duy nhất được điều khiển bởi `BlockMask`, nhanh hơn khi mô hình đã được biên dịch. Cả hai đều cho kết quả giống nhau.
- `causal_condition` — các token văn bản và ảnh điều kiện được điều biến từ `t = 0` thay vì từ bước thời gian được lấy mẫu. Kích hoạt của chúng độc lập với bước khử nhiễu, do đó các key và value của phần tiền tố đó có thể được lưu cache qua các bước thông qua đối số `kv_cache`.

Tải nó bằng cách:

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

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

**Tham số:**

patch_size (`int`, mặc định là `1`) : Độ dài cạnh của latent patch được gấp vào chiều kênh. Phiên bản 2.1 sử dụng latents không được patch.

in_channels (`int`, mặc định là `64`) : Số kênh tiềm ẩn của đầu vào.

out_channels (`int`, *tuỳ chọn*, mặc định là `64`) : Số kênh tiềm ẩn của đầu ra. Nếu không được chỉ định, sẽ dùng `in_channels`.

num_layers (`int`, mặc định là `32`) : Số lượng khối đơn luồng.

attention_head_dim (`int`, mặc định là `128`) : Số kênh cho mỗi đầu chú ý.

num_attention_heads (`int`, mặc định là `32`) : Số lượng đầu chú ý.

context_in_dim (`int`, mặc định là `4096`) : Kích thước kênh của `encoder_hidden_states`.

mlp_ratio (`int`, mặc định là `3`) : Hệ số mở rộng feed-forward.

axes_dims_rope (`tuple[int]`, mặc định là `(16, 56, 56)`) : Các chiều Rotary cho các trục frame, chiều cao và chiều rộng.

eps (`float`, mặc định là `1e-6`) : Epsilon cho các lớp chuẩn hóa.

causal_condition (`bool`, mặc định là `True`) : Điều biến các token văn bản và ảnh điều kiện từ `t = 0`. Bắt buộc cho việc đệm KV.

Transformer luồng đơn được sử dụng bởi Qwen-Image 2.1.

Latent của văn bản và hình ảnh chia sẻ một chuỗi duy nhất: các token của ảnh điều kiện được thay thế vào luồng văn bản tại các vị trí mà bộ mã hóa thị giác-ngôn ngữ đã dành sẵn cho chúng, và các token của ảnh đích được nối thêm vào cuối. Một phép chiếu `modulation` dùng chung duy nhất cung cấp cho mọi khối, do đó các khối không giữ các tham số modulation riêng của chúng.

Hai hành vi đặc trưng cho phiên bản 2.1:

- **Chú ý nhân quả theo khối** — chú ý tuân theo `(q_idx >= kv_idx) or same_image_block`, do đó chuỗi là nhân quả trong khi mỗi khối ảnh vẫn giữ tính hai chiều bên trong. Backend chú ý `flex` cho phép chú ý một lượt hiệu quả; nếu không có nó, mô hình sẽ dùng prefill SDPA đa lượt chính xác, xử lý từng khối riêng biệt.
- `causal_condition` — các token văn bản và ảnh điều kiện được điều biến từ `t = 0` thay vì bước thời gian được lấy mẫu, điều này cũng khiến kích hoạt của chúng không phụ thuộc vào bước thời gian và do đó có thể được đệm (cache) qua các bước khử nhiễu.

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

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

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

**Tham số:**

image_pad_mask (`torch.Tensor`) : `(seq_len,)` bool, `True` tại các vị trí token ảnh.

img_shapes (`list[tuple[int, int, int]]`) : `(frame, height, width)` theo từng ảnh, tính bằng số token tiềm ẩn, với các ảnh điều kiện đứng trước và ảnh đích đứng cuối.

**Trả về:** `tuple[torch.Tensor, torch.Tensor]`

`image_ids` `(seq_len,)` với `-1` tại các vị trí văn bản và một id duy nhất cho mỗi khối hình ảnh, cùng `target_token_mask` `(seq_len,)` đánh dấu các token của hình ảnh đích.

Gán nhãn cho từng token của chuỗi kết hợp với khối hình ảnh mà nó thuộc về.

Các ranh giới khối được xác định từ số lượng token trong `img_shapes`, chứ không phải từ các chuỗi `True` liên tiếp trong `image_pad_mask`: hai ảnh điều kiện nằm cạnh nhau mà không có văn bản xen giữa sẽ tạo thành một chuỗi duy nhất nhưng vẫn phải được giữ làm các khối riêng biệt, nếu không chúng sẽ chú ý lẫn nhau theo hai chiều.

#### 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)
```

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

**Tham số:**

hidden_states (`torch.Tensor` có shape `(batch_size, image_sequence_length, in_channels)`) : Các latents đã đóng gói, với các ảnh điều kiện ở trước và ảnh đích ở cuối.

encoder_hidden_states (`torch.Tensor` có hình dạng `(batch_size, text_sequence_length, context_in_dim)`) : Các vector nhúng văn bản từ bộ mã hóa thị giác-ngôn ngữ.

timestep (`torch.Tensor`) : Bước khử nhiễu hiện tại, được quy đổi về `[0, 1]`.

img_shapes (`list[list[tuple[int, int, int]]]`) : Danh sách theo mẫu gồm các `(frame, height, width)` trong latent tokens, với ảnh điều kiện đứng trước và ảnh đích đứng sau. Tất cả các mẫu phải cùng một bố cục.

img_mask (`torch.Tensor` có hình dạng `(batch_size, vlm_sequence_length)`) : `True` tại các vị trí ảnh của bộ mã hóa thị giác-ngôn ngữ, mỗi vị trí đại diện cho một nhóm `2x2` các token tiềm ẩn.

encoder_hidden_states_mask (`torch.Tensor`, *tùy chọn*) : `(batch_size, text_sequence_length)` bool đánh dấu các token văn bản hợp lệ. Các vị trí được đệm (padding) sẽ bị loại khỏi chú ý (attention).

kv_cache (`QwenImage21KVCache`, *tùy chọn*) : Container chứa cache. Truyền cùng với `kv_cache_mode` để bật tính năng cache KV cho phần đầu (prefix).

kv_cache_mode (`str`, *tùy chọn*) : `"extract"` để nạp trước bộ nhớ đệm (bước khử nhiễu đầu tiên), `"cached"` để giải mã từ bộ nhớ đệm đó (các bước sau). Yêu cầu `causal_condition=True`.

attention_kwargs (`dict`, *tùy chọn*) : Được chuyển tiếp đến các bộ xử lý chú ý và mang theo `scale` cho các lớp LoRA.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một [Transformer2DModelOutput](/docs/diffusers/main/vi/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) thay vì một tuple thông thường hay không.

**Trả về:** [Transformer2DModelOutput](/docs/diffusers/main/vi/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) hoặc `tuple`

[Transformer2DModelOutput](/docs/diffusers/main/vi/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) nếu `return_dict` là True, ngược lại là một `tuple` thông thường mà phần tử đầu tiên là các latents đã khử nhiễu.

## 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)
```

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

**Tham số:**

sample (`torch.Tensor` có shape `(batch_size, num_channels, height, width)` hoặc `(batch size, num_vector_embeds - 1, num_latent_pixels)` nếu [Transformer2DModel](/docs/diffusers/main/vi/api/models/transformer2d#diffusers.Transformer2DModel) là discrete) : Đầu ra của hidden states được điều kiện bởi đầu vào `encoder_hidden_states`. Nếu là discrete, trả về các phân phối xác suất cho các latent pixels chưa bị nhiễu.

Đầu ra của [Transformer2DModel](/docs/diffusers/main/vi/api/models/transformer2d#diffusers.Transformer2DModel).