Hugging Face's logo

Diffusers documentation

Flux3Transformer2DModel

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

Flux3Transformer2DModel

Model Transformer untuk data seperti gambar dari FLUX.3, 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.

import torch
from diffusers import Flux3Transformer2DModel

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

Flux3Transformer2DModel

kelas diffusers.Flux3Transformer2DModel

< >

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

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 (attention head).
  • num_attention_heads (int, defaultnya 24) — Jumlah 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 sinusoidal timestep.
  • 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 adalah 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 opsional yang dikodekan VAE (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 yang telah didistilasi langkah) juga menyematkan timestep yang dituju pada setiap langkah denoising dan menambahkannya ke modulasi setiap mode.

forward

< >

( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorimg_ids: Tensortxt_ids: Tensorimage_cond_hidden_states: typing.Optional[torch.Tensor] = Noneimage_cond_ids: typing.Optional[torch.Tensor] = Nonetarget_timestep: typing.Optional[torch.Tensor] = Noneattention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True )

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,)) — Timestep aliran dalam [0, 1] dari token gambar. Token gambar referensi dan konteks teks berada pada timestep 0.
  • img_ids (torch.Tensor dengan bentuk (image_seq_len, 4)) — ID posisi (t, h, w, l) dari token gambar, digunakan untuk embedding posisi rotasi 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) — Timestep flow dalam [0, 1] yang menjadi tujuan lompatan langkah denoising saat ini. Diwajibkan hanya oleh model flow-map (flow_map=True).
  • attention_kwargs (dict, opsional) — Kamus kwargs yang entri scale-nya, jika ditentukan, akan menskalakan lapisan LoRA untuk langkah forward ini.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~models.transformer_2d.Transformer2DModelOutput alih-alih tuple biasa.

Metode forward dari Flux3Transformer2DModel.

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

←Flux2Transformer2DModel FluxTransformer2DModel→