#
# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
# このファイルは、ライセンスに準拠した場合にのみ使用できます。
# ライセンスのコピーは以下から入手できます
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
# 権限を管理する特定の言語については、ライセンスを参照してください。
# ライセンスの下での制限。-->

# Flux3Transformer2DModel

[FLUX.3](https://bfl.ai/)の画像類似データ向けのTransformerモデルで、テキストから画像への生成および画像から画像への生成に対応しています。3つのトークンモードが1つの結合シーケンスを共有します。それは、ノイズ付き画像トークン、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[int, ...] = (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`) : 各アテンションヘッドに使用する次元数。

num_attention_heads (`int`、デフォルトは`24`) : 使用するアテンションヘッドの数。

joint_attention_dim (`int`、デフォルトは `20480`) : `encoder_hidden_states`（スタックされた Qwen3-VL の隠れ状態）の埋め込み/チャネル次元です。

timestep_channels (`int`、デフォルトは`256`) : 正弦波タイムステップ埋め込みのチャネル数。

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`) : layer norms と QK norms の epsilon。

flow_map (`bool`、デフォルトは`False`) : モデルがフローマップ（ステップ蒸留済み）かどうかを指定します。`target_timestep_embedder`を追加し、forward pass で`target_timestep`を必要とします。

FLUX.3でテキストから画像へ、および画像から画像への生成のために導入されたTransformerモデル。

3つのトークンモードが1つの結合シーケンスを共有します。ノイズ付き画像トークン（`hidden_states`）、任意のVAEエンコードされた参照画像トークン（`image_cond_hidden_states`）、およびテキストコンテキスト（`encoder_hidden_states`）です。各モードはまず、モードごとの独自のtransformerブロック（画像モードには`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,)`) : 画像トークンの Flow timestep。値は `[0, 1]` の範囲です。参照画像トークンとテキストコンテキストは 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)`、*optional*) : VAEエンコードされた参照画像トークン（クリーンな条件付けコンテンツ、画像から画像への生成用）。

image_cond_ids (`torch.Tensor`、shape `(cond_seq_len, 4)`、*optional*) : 参照画像トークンの位置ID。`image_cond_hidden_states`を使用する場合に必要です。

target_timestep (`torch.Tensor`、shape `(batch_size,)`、*任意*) : 現在のデノイジングステップがジャンプする `[0, 1]` 内の Flow のタイムステップ。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` が返され、それ以外の場合は `tuple` が返されます。このとき、最初の要素は画像トークンの予測速度であり、`hidden_states` と同じ形状です。

[Flux3Transformer2DModel](/docs/diffusers/main/ja/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/ja/api/models/transformer2d#diffusers.Transformer2DModel) が離散型の場合 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 入力を条件とする隠れ状態の出力です。離散型の場合、ノイズ除去されていない潜在ピクセルの確率分布を返します。

[Transformer2DModel](/docs/diffusers/main/ja/api/models/transformer2d#diffusers.Transformer2DModel)の出力です。