# Flux2Transformer2DModel

用于 [Flux2](https://hf.co/black-forest-labs/FLUX.2-dev) 图像类数据的 Transformer 模型。

## Flux2Transformer2DModel[[diffusers.Flux2Transformer2DModel]]

#### diffusers.Flux2Transformer2DModel[[diffusers.Flux2Transformer2DModel]]

```python
diffusers.Flux2Transformer2DModel(patch_size: int = 1, in_channels: int = 128, out_channels: int | None = None, num_layers: int = 8, num_single_layers: int = 48, attention_head_dim: int = 128, num_attention_heads: int = 48, joint_attention_dim: int = 15360, timestep_guidance_channels: int = 256, mlp_ratio: float = 3.0, axes_dims_rope: tuple[int, ...] = (32, 32, 32, 32), rope_theta: int = 2000, eps: float = 1e-06, guidance_embeds: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_flux2.py#L1059)

**参数：**

patch_size (`int`，默认为 `1`)：用于将输入数据划分为小块的补丁大小。

in_channels (`int`，默认为 `128`)：输入中的通道数。

out_channels (`int`，*可选*，默认为 `None`)：输出中的通道数。如果未指定，则默认为 `in_channels`。

num_layers (`int`，默认为 `8`)：要使用的双流 DiT 块层数。

num_single_layers (`int`，默认为 `48`)：要使用的单流 DiT 块层数。

attention_head_dim (`int`，默认为 `128`)：每个注意力头使用的维度数。

num_attention_heads (`int`，默认为 `48`)：要使用的注意力头数量。

joint_attention_dim (`int`，默认为 `15360`)：用于联合注意力的维度数（`encoder_hidden_states` 的嵌入/通道维度）。

pooled_projection_dim (`int`，默认为 `768`)：用于池化投影的维度数。

guidance_embeds (`bool`，默认为 `True`)：是否使用引导嵌入（guidance embeddings）来支持模型的引导蒸馏变体。

axes_dims_rope (`tuple[int]`，默认为 `(32, 32, 32, 32)`)：用于旋转位置嵌入的维度。

Flux 2 中引入的 Transformer 模型。

参考：https://blackforestlabs.ai/announcing-black-forest-labs/

#### forward[[diffusers.Flux2Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor = None, timestep: LongTensor = None, img_ids: Tensor = None, txt_ids: Tensor = None, guidance: Tensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True, kv_cache: Flux2KVCache | None = None, kv_cache_mode: str | None = None, num_ref_tokens: int = 0, ref_fixed_timestep: float = 0.0)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_flux2.py#L1225)

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch_size, image_sequence_length, in_channels)`) : 输入 `hidden_states`。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, text_sequence_length, joint_attention_dim)`)：要使用的条件嵌入（从输入条件（例如提示词）计算得出的嵌入）。

timestep (`torch.LongTensor`)：用于指示去噪步骤。

img_ids (`torch.Tensor`) : 用于计算旋转位置嵌入的图像位置 ID。

txt_ids (`torch.Tensor`) : 用于计算旋转位置嵌入的文本位置 ID。

guidance (`torch.Tensor`, *可选*) : 用于模型引导蒸馏变体的引导尺度嵌入。

joint_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。

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

kv_cache (`Flux2KVCache`，*可选*)：用于参考图像 token 的 KV 缓存。当 `kv_cache_mode` 为 "extract" 时，会创建并返回一个新缓存。当为 "cached" 时，将使用提供的缓存，在注意力计算期间注入参考 K/V。

kv_cache_mode (`str`, *可选*) : 取值为 "extract"（使用 ref tokens 的第一步）或 "cached"（使用缓存的 ref K/V 的后续步骤）。当 `None` 时，执行不带 KV 缓存的标准前向传播。

num_ref_tokens (`int`，默认为 `0`)：添加到 `hidden_states` 前面的参考图像 token 数量（仅在 `kv_cache_mode="extract"` 时使用）。

ref_fixed_timestep (`float`，默认为 `0.0`)：用于参考 token 调制的固定时间步（仅在 `kv_cache_mode="extract"` 时使用）。

**返回值：**

如果 `return_dict` 为 True，则返回 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是样本张量。当 `kv_cache_mode="extract"` 时，还会返回已填充的 `Flux2KVCache`。

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

## Flux2Transformer2DModelOutput[[diffusers.models.transformers.transformer_flux2.Flux2Transformer2DModelOutput]]

#### diffusers.models.transformers.transformer_flux2.Flux2Transformer2DModelOutput[[diffusers.models.transformers.transformer_flux2.Flux2Transformer2DModelOutput]]

```python
diffusers.models.transformers.transformer_flux2.Flux2Transformer2DModelOutput(sample: torch.Tensor, kv_cache: Flux2KVCache | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_flux2.py#L46)

**参数：**

sample (`torch.Tensor`，形状为 `(batch_size, num_channels, height, width)`)：基于 `encoder_hidden_states` 输入条件生成的隐藏状态输出。

kv_cache (`Flux2KVCache`，*可选*)：用于参考图像 token 的已填充 KV 缓存。仅在 `kv_cache_mode="extract"` 时返回。

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