#
# Được cấp phép theo Giấy phép Apache, Phiên bản 2.0 (gọi là "Giấy phép");
# bạn có thể không sử dụng tệp này ngoại trừ tuân thủ theo Giấy phép.
# Bạn có thể nhận được một bản sao của Giấy phép tại
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Trừ khi được yêu cầu bởi luật pháp có hiệu lực hoặc được thỏa thuận bằng văn bản, phần mềm
# được phân phối theo Giấy phép được phân phối trên cơ sở
# KHÔNG CÓ BẢO HÀNH HOẶC ĐIỀU KIỆN DƯỚI BẤT KỲ HÌNH THỨC NÀO, dù được nêu rõ hay ngụ ý.
# Xem Giấy phép để biết ngôn ngữ cụ thể điều chỉnh các quyền và
# giới hạn theo Giấy phép. -->

# Flux3Transformer2DModel

Một mô hình Transformer cho dữ liệu dạng ảnh từ [FLUX.3](https://bfl.ai/), dùng cho việc tạo ảnh từ văn bản và tạo ảnh từ ảnh. Ba chế độ token chia sẻ một chuỗi liên hợp: các token ảnh nhiễu, các token ảnh tham chiếu được mã hóa bằng VAE và ngữ cảnh văn bản. Mỗi chế độ trước tiên đi qua các khối transformer riêng của chế độ đó, sau đó các chế độ được nối lại cho các khối đơn liên hợp, và các token ảnh đi qua các lớp đầu ra. Timesteps là theo từng token: các token ảnh mang flow timestep, trong khi các token tham chiếu và ngữ cảnh văn bản nằm ở `0`.

```python
import torch
from diffusers import Flux3Transformer2DModel

transformer = Flux3Transformer2DModel.from_pretrained(
    "black-forest-labs/flux-3-image-klein-base", subfolder="transformer", dtype=torch.bfloat16
)
```

## Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

#### diffusers.Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

```python
diffusers.Flux3Transformer2DModel(in_channels: int = 128, cond_in_channels: int = 128, num_layers: int = 5, num_single_layers: int = 28, attention_head_dim: int = 128, num_attention_heads: int = 24, joint_attention_dim: int = 20480, timestep_channels: int = 256, mlp_ratio: float = 3.0, axes_dims_rope: tuple[int, ...] = (32, 32, 32, 32), rope_theta: int = 10000, eps: float = 1e-06, flow_map: bool = False)
```

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

**Tham số:**

in_channels (`int`, mặc định là `128`) : Độ rộng kênh của các token ảnh (các latents VAE đã đóng gói, `latent_channels * 4`).

cond_in_channels (`int`, mặc định là `128`) : Độ rộng kênh của các token ảnh tham chiếu.

num_layers (`int`, mặc định là `5`) : Số lượng khối transformer cho mỗi chế độ.

num_single_layers (`int`, mặc định là `28`) : Số lượng khối transformer đơn liên kết.

attention_head_dim (`int`, mặc định là `128`) : Số chiều được sử dụng cho mỗi đầu chú ý.

num_attention_heads (`int`, mặc định là `24`) : Số lượng đầu chú ý (attention heads) cần sử dụng.

joint_attention_dim (`int`, mặc định là `20480`) : Kích thước embedding/kênh của `encoder_hidden_states` (các trạng thái ẩn Qwen3-VL được xếp chồng).

timestep_channels (`int`, mặc định là `256`) : Số lượng kênh của nhúng bước thời gian hình sin.

mlp_ratio (`float`, mặc định là `3.0`) : Tỷ lệ mở rộng của các khối con feedforward.

axes_dims_rope (`tuple[int]`, mặc định là `(32, 32, 32, 32)`) : Các kích thước cần sử dụng cho các nhúng vị trí quay (rotary positional embeddings), theo từng trục vị trí `(t, h, w, l)`.

rope_theta (`int`, mặc định là `10000`) : Tần số cơ bản của các nhúng vị trí quay (rotary positional embeddings).

eps (`float`, mặc định là `1e-6`) : Epsilon của các layer norms và QK norms.

flow_map (`bool`, mặc định là `False`) : Xác định xem mô hình có phải là flow map (step-distilled) hay không: thêm `target_timestep_embedder` và yêu cầu `target_timestep` trong bước forward.

Mô hình Transformer được giới thiệu trong FLUX.3 cho việc tạo ảnh từ văn bản và tạo ảnh từ ảnh.

Ba chế độ token chia sẻ một chuỗi liên hợp: các token ảnh nhiễu (`hidden_states`), các token ảnh tham chiếu tùy chọn được mã hóa bằng VAE (`image_cond_hidden_states`) và ngữ cảnh văn bản (`encoder_hidden_states`). Mỗi chế độ trước tiên đi qua các khối transformer riêng của chế độ đó (`mode_blocks` cho các chế độ ảnh, `txt_mode_blocks` cho ngữ cảnh văn bản), sau đó ngữ cảnh văn bản và các chế độ ảnh đang hoạt động được nối với nhau cho các khối đơn liên hợp, và chỉ các token ảnh đi qua các lớp đầu ra. Sự điều biến là theo từng chế độ: các token ảnh được điều biến bởi bước thời gian của luồng, các token ảnh tham chiếu và ngữ cảnh văn bản được điều biến bởi bước thời gian `0`. Một checkpoint flow-map (`flow_map=True`, các mô hình đã chưng cất theo bước) ngoài ra còn nhúng bước thời gian mà mỗi bước khử nhiễu nhảy tới và cộng nó vào sự điều biến của mọi chế độ.

#### forward[[diffusers.Flux3Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_ids: Tensor, txt_ids: Tensor, image_cond_hidden_states: typing.Optional[torch.Tensor] = None, image_cond_ids: typing.Optional[torch.Tensor] = None, target_timestep: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

**Tham số:**

hidden_states (`torch.Tensor` có hình dạng `(batch_size, image_seq_len, in_channels)`) : Các token latent của ảnh nhiễu.

encoder_hidden_states (`torch.Tensor` có hình dạng `(batch_size, text_seq_len, joint_attention_dim)`) : Các embedding ngữ cảnh văn bản (các trạng thái ẩn Qwen3-VL được xếp chồng).

timestep (`torch.Tensor` có shape `(batch_size,)`) : Timestep của flow trong `[0, 1]` của các image tokens. Các image tokens tham chiếu và ngữ cảnh văn bản nằm ở timestep `0`.

img_ids (`torch.Tensor` có shape `(image_seq_len, 4)`) : Các id vị trí `(t, h, w, l)` của các token hình ảnh, được sử dụng cho các nhúng vị trí quay (rotary positional embeddings) và được chia sẻ bởi tất cả các mẫu trong batch.

txt_ids (`torch.Tensor` có shape `(text_seq_len, 4)`) : Position ids của các text context tokens.

image_cond_hidden_states (`torch.Tensor` có shape `(batch_size, cond_seq_len, cond_in_channels)`, *tuỳ chọn*) : các token của ảnh tham chiếu đã được mã hóa bởi VAE (nội dung điều kiện sạch, dùng cho tạo ảnh từ ảnh).

image_cond_ids (`torch.Tensor` có shape `(cond_seq_len, 4)`, *tùy chọn*) : Các position id của các token ảnh tham chiếu. Bắt buộc khi dùng `image_cond_hidden_states`.

target_timestep (`torch.Tensor` có shape `(batch_size,)`, *tùy chọn*) : Bước thời gian (timestep) của flow trong `[0, 1]` mà bước khử nhiễu hiện tại nhảy tới. Bắt buộc và chỉ bắt buộc với mô hình flow-map (`flow_map=True`).

attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs mà mục `scale`, nếu được chỉ định, sẽ điều chỉnh tỷ lệ các lớp LoRA cho lần truyền tiến này.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `~models.transformer_2d.Transformer2DModelOutput` thay vì một tuple thông thường hay không.

**Trả về:**

Nếu `return_dict` là True, một `~models.transformer_2d.Transformer2DModelOutput` sẽ được trả về, ngược lại một `tuple` trong đó phần tử đầu tiên là vận tốc dự đoán của các token ảnh, có cùng hình dạng với `hidden_states`.

Phương thức forward của [Flux3Transformer2DModel](/docs/diffusers/main/vi/api/models/flux3_transformer#diffusers.Flux3Transformer2DModel).

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