#
# Berlisensi di bawah Apache License, Versi 2.0 ("Lisensi");
# Anda mungkin tidak dapat menggunakan file ini kecuali sesuai dengan Lisensi.
# Anda dapat memperoleh salinan Lisensi di
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Kecuali diwajibkan oleh hukum yang berlaku atau disepakati secara tertulis, perangkat lunak
# distribusikan di bawah Lisensi berdasarkan basis "SEBAGAIMANA ADANYA",
# TANPA JAMINAN ATAU SYARAT DALAM BENTUK APAPUN, baik yang dinyatakan maupun yang tersirat.
# Lihat Lisensi untuk bahasa tertentu yang mengatur izin dan
# batasan di bawah Lisensi. -->

# Flux3Transformer2DModel

Model Transformer untuk data seperti gambar dari [FLUX.3](https://bfl.ai/), untuk generasi teks-ke-gambar dan gambar-ke-gambar. Tiga mode token berbagi satu urutan gabungan: token gambar berisik, token gambar referensi yang dikodekan VAE, dan konteks teks. Setiap mode pertama kali melewati blok transformer per-mode miliknya sendiri, kemudian mode-mode tersebut digabungkan untuk blok tunggal gabungan, dan token gambar melewati lapisan output. Timesteps bersifat per token: token gambar membawa timestep aliran, sedangkan token referensi dan konteks teks berada di `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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_flux3.py#L341)

**Parameter:**

in_channels (`int`, defaultnya `128`) : Lebar channel dari token gambar (laten VAE yang dikemas, `latent_channels * 4`).

cond_in_channels (`int`, defaultnya `128`) : Lebar channel dari token gambar referensi.

num_layers (`int`, defaultnya `5`) : Jumlah blok transformer per mode.

num_single_layers (`int`, defaultnya `28`) : Jumlah blok transformer tunggal gabungan.

attention_head_dim (`int`, defaultnya `128`) : Jumlah dimensi yang digunakan untuk setiap kepala perhatian.

num_attention_heads (`int`, defaultnya `24`) : Jumlah kepala perhatian (attention heads) yang akan digunakan.

joint_attention_dim (`int`, defaultnya `20480`) : Dimensi embedding/channel dari `encoder_hidden_states` (hidden states Qwen3-VL yang ditumpuk).

timestep_channels (`int`, defaultnya `256`) : Jumlah channel dari embedding timestep sinusoidal.

mlp_ratio (`float`, defaultnya `3.0`) : Rasio ekspansi dari sub-blok feedforward.

axes_dims_rope (`tuple[int]`, defaultnya `(32, 32, 32, 32)`) : Dimensi yang digunakan untuk rotary positional embeddings, per sumbu posisi `(t, h, w, l)`.

rope_theta (`int`, defaultnya `10000`) : Frekuensi dasar dari rotary positional embeddings.

eps (`float`, defaultnya `1e-6`) : Epsilon dari layer norms dan QK norms.

flow_map (`bool`, defaultnya `False`) : Apakah model tersebut merupakan flow map (step-distilled): menambahkan `target_timestep_embedder` dan membutuhkan `target_timestep` dalam forward pass.

Model Transformer yang diperkenalkan dalam FLUX.3 untuk generasi teks-ke-gambar dan gambar-ke-gambar.

Tiga mode token berbagi satu urutan bersama: token gambar berisik (`hidden_states`), token gambar referensi yang dikodekan VAE secara opsional (`image_cond_hidden_states`), dan konteks teks (`encoder_hidden_states`). Setiap mode pertama-tama melewati blok transformer per-mode miliknya sendiri (`mode_blocks` untuk mode gambar, `txt_mode_blocks` untuk konteks teks), kemudian konteks teks dan mode gambar yang aktif digabungkan untuk blok tunggal bersama, dan hanya token gambar yang melewati lapisan output. Modulasinya bersifat per mode: token gambar dimodulasi oleh timestep aliran, sedangkan token gambar referensi dan konteks teks oleh timestep `0`. Checkpoint flow-map (`flow_map=True`, model-model yang telah didistilasi langkah) juga menyematkan timestep yang dituju pada setiap langkah denoising dan menambahkannya ke modulasi setiap mode.

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_flux3.py#L494)

**Parameter:**

hidden_states (`torch.Tensor` dengan bentuk `(batch_size, image_seq_len, in_channels)`) : Token laten gambar berisik.

encoder_hidden_states (`torch.Tensor` dengan bentuk `(batch_size, text_seq_len, joint_attention_dim)`) : Embedding konteks teks (hidden states Qwen3-VL yang ditumpuk).

timestep (`torch.Tensor` dengan bentuk `(batch_size,)`) : Langkah waktu (timestep) aliran dalam `[0, 1]` untuk token gambar. Token gambar referensi dan konteks teks berada pada langkah waktu `0`.

img_ids (`torch.Tensor` dengan bentuk `(image_seq_len, 4)`) : Position ids `(t, h, w, l)` dari token gambar, digunakan untuk rotary positional embeddings dan dibagikan oleh semua sampel dalam batch.

txt_ids (`torch.Tensor` dengan bentuk `(text_seq_len, 4)`) : ID posisi untuk token konteks teks.

image_cond_hidden_states (`torch.Tensor` dengan bentuk `(batch_size, cond_seq_len, cond_in_channels)`, *opsional*) : token gambar referensi yang di-encode VAE (konten kondisioning bersih, untuk generasi gambar-ke-gambar).

image_cond_ids (`torch.Tensor` dengan bentuk `(cond_seq_len, 4)`, *opsional*) : ID posisi untuk token gambar referensi. Wajib diisi bersama `image_cond_hidden_states`.

target_timestep (`torch.Tensor` dengan bentuk `(batch_size,)`, *opsional*) : Langkah waktu flow dalam `[0, 1]` yang menjadi target lompatan langkah denoising saat ini. Diperlukan hanya oleh model flow-map (`flow_map=True`).

attention_kwargs (`dict`, *opsional*) : Kamus kwargs yang entri `scale`-nya, jika ditentukan, menskalakan lapisan LoRA untuk forward pass ini.

return_dict (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengembalikan `~models.transformer_2d.Transformer2DModelOutput` alih-alih tuple biasa.

**Mengembalikan:**

Jika `return_dict` bernilai True, sebuah `~models.transformer_2d.Transformer2DModelOutput` akan dikembalikan, selain itu sebuah `tuple` di mana elemen pertama adalah kecepatan prediksi dari token gambar, dengan bentuk yang sama seperti `hidden_states`.

Metode forward dari [Flux3Transformer2DModel](/docs/diffusers/v0.43.0/id/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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**Parameter:**

sample (`torch.Tensor` dengan bentuk `(batch_size, num_channels, height, width)` atau `(batch size, num_vector_embeds - 1, num_latent_pixels)` jika [Transformer2DModel](/docs/diffusers/v0.43.0/id/api/models/transformer2d#diffusers.Transformer2DModel) bersifat diskrit) : Output hidden states yang dikondisikan pada input `encoder_hidden_states`. Jika diskrit, mengembalikan distribusi probabilitas untuk piksel laten yang tidak berisik.

Output dari [Transformer2DModel](/docs/diffusers/v0.43.0/id/api/models/transformer2d#diffusers.Transformer2DModel).