#
# Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
# 이 파일은 라이선스에 따라만 사용할 수 있습니다.
# 라이선스 사본은 다음에서 가져올 수 있습니다
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어
# 라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"
# 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.
# 권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요
# 라이선스 하의 제한 사항. -->

# Flux3Transformer2DModel

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

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

**매개변수:**

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 타임스텝 임베딩의 채널 수입니다.

mlp_ratio (`float`, 기본값 `3.0`) : 피드포워드 서브블록의 확장 비율입니다.

axes_dims_rope (`tuple[int]`, 기본값 `(32, 32, 32, 32)`) : `(t, h, w, l)` 위치 축별로 사용할 rotary positional embeddings의 차원입니다.

rope_theta (`int`, 기본값 `10000`) : 회전 위치 임베딩의 기본 주파수입니다.

eps (`float`, 기본값 `1e-6`) : layer norms과 QK norms의 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[[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)
```

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

**매개변수:**

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)`입니다. 회전 위치 임베딩에 사용되며 배치 내 모든 샘플에서 공유됩니다.

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`) : 일반 튜플 대신 `~models.transformer_2d.Transformer2DModelOutput`을 반환할지 여부.

**반환값:**

`return_dict`가 True이면 `~models.transformer_2d.Transformer2DModelOutput`이 반환되고, 그렇지 않으면 첫 번째 요소가 이미지 토큰의 예측 속도이며 `hidden_states`와 동일한 형상을 가지는 `tuple`이 반환됩니다.

[Flux3Transformer2DModel](/docs/diffusers/main/ko/api/models/flux3_transformer#diffusers.Flux3Transformer2DModel)의 forward 메서드입니다.

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**매개변수:**

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

[Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)의 출력입니다.