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

Một mô hình Transformer cho dữ liệu dạng ảnh từ FLUX.3, 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.

import torch
from diffusers import Flux3Transformer2DModel

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

Flux3Transformer2DModel

lớp 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 )

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 ghép nối.
  • attention_head_dim (int, mặc định là 128) — Số chiều sử dụng cho mỗi đầu chú ý (attention head).
  • num_attention_heads (int, mặc định là 24) — Số lượng đầu attention cần sử dụng.
  • joint_attention_dim (int, mặc định là 20480) — Chiều embedding/kênh của encoder_hidden_states (các hidden state của Qwen3-VL được xếp chồng).
  • timestep_channels (int, mặc định là 256) — Số lượng kênh của embedding 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 chiều 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

< >

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

Tham số

  • hidden_states (torch.Tensor có hình dạng (batch_size, image_seq_len, in_channels)) — Các token tiềm ẩn của ảnh có 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,)) — Bước thời gian (timestep) của luồng trong khoảng [0, 1] cho các token ảnh. Các token ảnh tham chiếu và ngữ cảnh văn bản nằm ở timestep 0.
  • img_ids (torch.Tensor có hình dạng (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ó hình dạng (text_seq_len, 4)) — Các id vị trí của các token ngữ cảnh văn bản.
  • image_cond_hidden_states (torch.Tensor có hình dạng (batch_size, cond_seq_len, cond_in_channels), tùy chọn) — Các token ả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ó hình dạng (cond_seq_len, 4), tùy chọn) — Các id vị trí của các token ảnh tham chiếu. Bắt buộc khi sử dụng cùng với image_cond_hidden_states.
  • target_timestep (torch.Tensor có shape (batch_size,), tuỳ chọn) — Bước thời gian (timestep) của flow trong [0, 1] mà bước khử nhiễu hiện tại sẽ nhảy tới. Bắt buộc và chỉ bắt buộc đối 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 của nó, nếu được chỉ định, sẽ điều chỉnh tỷ lệ các lớp LoRA cho bước 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.

Phương thức forward của Flux3Transformer2DModel.

Transformer2DModelOutput

lớp diffusers.models.modeling_outputs.Transformer2DModelOutput

< >

( sample: torch.Tensor )

Tham số

  • sample (torch.Tensor có hình dạng (batch_size, num_channels, height, width) hoặc (batch size, num_vector_embeds - 1, num_latent_pixels) nếu Transformer2DModel là rời rạc) — Trạng thái ẩn đầu ra được điều kiện bởi đầu vào encoder_hidden_states. Nếu là rời rạc, trả về các phân phối xác suất cho các pixel tiềm ẩn không nhiễu.

Đầu ra của Transformer2DModel.

Update on GitHub

←Flux2Transformer2DModel FluxTransformer2DModel→