Diffusers

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Flux3Transformer2DModel

FLUX.3의 이미지형 데이터용 Transformer 모델로, 텍스트-이미지 생성 및 이미지-이미지 생성에 사용됩니다. 세 가지 토큰 모드가 하나의 결합된 시퀀스를 공유합니다: 노이즈 이미지 토큰, VAE 인코딩된 참조 이미지 토큰, 텍스트 컨텍스트입니다. 각 모드는 먼저 해당 모드 전용 Transformer 블록을 통과한 후, 결합된 단일 블록을 위해 모드들이 연결되고, 이미지 토큰이 출력 레이어를 통과합니다. 타임스텝은 토큰별로 설정됩니다: 이미지 토큰은 플로우 타임스텝을 가지며, 참조 토큰과 텍스트 컨텍스트는 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

클래스 diffusers.Flux3Transformer2DModel

< source >

( 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[int, ...] = (32, 32, 32, 32)rope_theta: int = 10000eps: float = 1e-06flow_map: bool = False )

매개변수

in_channels (int, 기본값 128) — 이미지 토큰의 채널 폭(패킹된 VAE 잠재 변수, latent_channels * 4).
cond_in_channels (int, 기본값 128) — 참조 이미지 토큰의 채널 폭입니다.
num_layers (int, 기본값 5) — 모드별 transformer 블록의 수입니다.
num_single_layers (int, 기본값 28) — 연결된 단일 transformer 블록의 수입니다.
attention_head_dim (int, 기본값 128) — 각 attention head에 사용할 차원의 수입니다.
num_attention_heads (int, 기본값 24) — 사용할 attention head의 수입니다.
joint_attention_dim (int, 기본값 20480) — encoder_hidden_states의 임베딩/채널 차원(스택된 Qwen3-VL 히든 상태).
timestep_channels (int, 기본값 256) — 사인oidal timestep 임베딩의 채널 수입니다.
mlp_ratio (float, 기본값 3.0) — 피드포워드 서브 블록의 확장 비율입니다.
axes_dims_rope (tuple[int], 기본값 (32, 32, 32, 32)) — (t, h, w, l) 위치 축별로 회전 위치 임베딩에 사용할 차원입니다.
rope_theta (int, 기본값 10000) — 회전 위치 임베딩의 기본 주파수입니다.
eps (float, 기본값 1e-6) — 레이어 노름과 QK 노름의 epsilon 값입니다.
flow_map (bool, 기본값 False) — 모델이 flow map(단계 증류)인지 여부입니다. target_timestep_embedder를 추가하고 forward pass에서 target_timestep를 요구합니다.

텍스트-이미지 생성 및 이미지-이미지 생성을 위해 FLUX.3에 도입된 Transformer 모델.

세 가지 토큰 모드가 하나의 결합된 시퀀스를 공유합니다: 노이즈 이미지 토큰(hidden_states), 선택적인 VAE 인코딩된 참조 이미지 토큰(image_cond_hidden_states), 그리고 텍스트 컨텍스트(encoder_hidden_states). 각 모드는 먼저 해당 모드 전용의 트랜스포머 블록(mode_blocks은 이미지 모드용, txt_mode_blocks는 텍스트 컨텍스트용)을 통과한 후, 텍스트 컨텍스트와 활성 이미지 모드가 결합된 단일 블록을 위해 연결됩니다. 그리고 이미지 토큰만 출력 레이어를 통과합니다. 모듈레이션은 모드별로 적용됩니다: 이미지 토큰은 플로우 타임스텝으로, 참조 이미지 토큰과 텍스트 컨텍스트는 타임스텝 0으로 모듈레이션됩니다. 플로우맵 체크포인트(flow_map=True, 스텝 디스틸레이션된 모델)는 각 디노이징 스텝이 점프하는 타임스텝을 추가로 임베딩하여 모든 모드의 모듈레이션에 더합니다.

forward

< source >

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

매개변수

hidden_states (torch.Tensor, shape (batch_size, image_seq_len, in_channels)) — 노이즈가 포함된 이미지 잠재 토큰.
encoder_hidden_states (torch.Tensor, shape (batch_size, text_seq_len, joint_attention_dim)) — 텍스트 컨텍스트 임베딩(스택된 Qwen3-VL 히든 상태).
timestep (torch.Tensor, shape (batch_size,)) — 이미지 토큰의 [0, 1] 범위 내 Flow timestep입니다. 참조 이미지 토큰과 텍스트 컨텍스트는 timestep 0에 위치합니다.
img_ids (torch.Tensor, shape (image_seq_len, 4)) — 이미지 토큰의 위치 ID (t, h, w, l)입니다. 회전 위치 임베딩(rotary positional embeddings)에 사용되며 배치 내 모든 샘플에서 공유됩니다.
txt_ids (torch.Tensor, shape (text_seq_len, 4)) — 텍스트 컨텍스트 토큰의 위치 ID입니다.
image_cond_hidden_states (torch.Tensor, shape (batch_size, cond_seq_len, cond_in_channels), 선택 사항) — VAE로 인코딩된 참조 이미지 토큰(이미지-대-이미지 생성을 위한 깨끗한 조건부 콘텐츠).
image_cond_ids (torch.Tensor, shape (cond_seq_len, 4), 선택 사항) — 참조 이미지 토큰의 위치 ID입니다. image_cond_hidden_states와 함께 사용해야 합니다.
target_timestep (torch.Tensor, shape (batch_size,), 선택 사항) — 현재 denoising 단계가 점프하는 [0, 1] 범위의 Flow timestep입니다. flow-map 모델(flow_map=True)에서만 필요합니다.
attention_kwargs (dict, 선택 사항) — 지정된 경우, scale 항목이 이 forward pass의 LoRA 레이어를 스케일링하는 kwargs 사전입니다.
return_dict (bool, 선택 사항, 기본값 True) — 단순 tuple 대신 ~models.transformer_2d.Transformer2DModelOutput를 반환할지 여부.

Flux3Transformer2DModel의 forward 메서드입니다.

Transformer2DModelOutput

클래스 diffusers.models.modeling_outputs.Transformer2DModelOutput

< source >

( sample: torch.Tensor )

매개변수

sample (torch.Tensor, shape (batch_size, num_channels, height, width) 또는 Transformer2DModel이 discrete인 경우 (batch size, num_vector_embeds - 1, num_latent_pixels)) — encoder_hidden_states 입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.

Transformer2DModel의 출력입니다.

Update on GitHub

←Flux2Transformer2DModel FluxTransformer2DModel→