#
# 根据 Apache 许可证 2.0 版本（“许可证”）授权
# 您只能在遵守许可证的情况下使用本文件。
# 您可以在以下位置获取许可证副本
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 除非适用法律要求或双方书面同意，软件
# 根据许可证分发，本软件按“原样”
# 不附带任何明示或暗示的保证或条件。
# 请参阅许可证中关于权限的具体语言
# 许可证下的限制。-->

# Flux3Transformer2DModel

用于 [FLUX.3](https://bfl.ai/) 类图像数据的 Transformer 模型，支持文本生成图像和图像生成图像。三种 token 模式共享一个联合序列：带噪图像 token、经 VAE 编码的参考图像 token 以及文本上下文。每种模式首先通过其专属的按模式划分的 Transformer 块，随后各模式进行拼接以进入联合单块，最后图像 token 通过输出层。时间步是按 token 划分的：图像 token 携带流时间步，而参考 token 和文本上下文均位于 `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/v0.43.0/src/diffusers/models/transformers/transformer_flux3.py#L341)

**参数：**

in_channels (`int`，默认值为 `128`)：图像 token 的通道宽度（即打包后的 VAE 潜变量，`latent_channels * 4`）。

cond_in_channels (`int`，默认为 `128`)：参考图像 token 的通道宽度。

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`)：层归一化和 QK 归一化的 epsilon 值。

flow_map (`bool`，默认为 `False`)：模型是否为流映射（步数蒸馏）：会添加 `target_timestep_embedder`，并要求在 forward 传递中提供 `target_timestep`。

FLUX.3 中用于文本到图像和图像到图像生成的 Transformer 模型。

三种 token 模式共享一个联合序列：带噪图像 token（`hidden_states`）、可选的 VAE 编码参考图像 token（`image_cond_hidden_states`）以及文本上下文（`encoder_hidden_states`）。每种模式首先通过其各自的按模式划分的 transformer 块（图像模式使用 `mode_blocks`，文本上下文使用 `txt_mode_blocks`），随后将文本上下文与当前激活的图像模式进行拼接，用于联合单块处理，且只有图像 token 通过输出层。调制是按模式进行的：图像 token 由 flow 时间步调制，而参考图像 token 和文本上下文则由时间步 `0` 调制。Flow-map 检查点（`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/v0.43.0/src/diffusers/models/transformers/transformer_flux3.py#L494)

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch_size, image_seq_len, in_channels)`)：带噪声的图像潜在 token。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, text_seq_len, joint_attention_dim)`)：文本上下文嵌入（堆叠的 Qwen3-VL 隐藏状态）。

timestep (`torch.Tensor`，形状为 `(batch_size,)`)：图像 token 在 `[0, 1]` 区间内的 Flow 时间步。参考图像 token 和文本上下文位于时间步 `0`。

img_ids (`torch.Tensor`，形状为 `(image_seq_len, 4)`)：图像 token 的位置 ID `(t, h, w, l)`，用于旋转位置嵌入，并在批次中的所有样本间共享。

txt_ids (`torch.Tensor`，形状为 `(text_seq_len, 4)`)：文本上下文 token 的位置 ID。

image_cond_hidden_states (`torch.Tensor`，形状为 `(batch_size, cond_seq_len, cond_in_channels)`，*可选*)：VAE 编码的参考图像 token（干净的 conditioning 内容，用于图像到图像生成）。

image_cond_ids (`torch.Tensor`，形状为 `(cond_seq_len, 4)`，*可选*)：参考图像 token 的位置 ID。使用 `image_cond_hidden_states` 时必填。

target_timestep (`torch.Tensor`，形状为 `(batch_size,)`，*可选*)：当前去噪步骤所跳转到的 `[0, 1]` 区间内的流时间步。仅由流映射模型（`flow_map=True`）需要。

attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定了其 `scale` 项，则会在本次前向传播中对 LoRA 层进行缩放。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~models.transformer_2d.Transformer2DModelOutput` 而不是普通元组。

**返回值：**

如果 `return_dict` 为 True，则返回一个 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是图像 token 的预测速度，其形状与 `hidden_states` 相同。

[Flux3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/flux3_transformer#diffusers.Flux3Transformer2DModel) 的前向方法。

## 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/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**参数：**

sample (`torch.Tensor`，形状为 `(batch_size, num_channels, height, width)`；若 [Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/transformer2d#diffusers.Transformer2DModel) 为离散模式，则为 `(batch size, num_vector_embeds - 1, num_latent_pixels)`)：以 `encoder_hidden_states` 输入为条件的隐藏状态输出。若为离散模式，则返回未加噪潜在像素的概率分布。

[Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/transformer2d#diffusers.Transformer2DModel) 的输出。