#
# Лицензия Apache License, Version 2.0 («Лицензия»);
# вы можете использовать этот файл только в соответствии с Лицензией.
# Вы можете получить копию Лицензии по адресу
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Если это не требуется применимым законодательством или не оговорено письменно, программное
# распространяется по Лицензии на условиях «КАК ЕСТЬ»,
# БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.
# См. Лицензию для получения конкретных условий, регулирующих разрешения и
# ограничениями Лицензии. -->

# Flux3Transformer2DModel

Модель Transformer для изображений от [FLUX.3](https://bfl.ai/), предназначенная для генерации изображений по тексту и по изображению. Три режима токенов объединяются в одну последовательность: токены зашумленного изображения, токены референсного изображения, закодированного VAE, и текстовый контекст. Сначала каждый режим проходит через собственные блоки Transformer, затем режимы конкатенируются для общих блоков, после чего токены изображения проходят через выходные слои. Шаги времени (timesteps) задаются для каждого токена: токены изображения несут timestep потока, а токены референса и текстовый контекст находятся на `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`) : Количество блоков трансформера для каждого режима.

num_single_layers (`int`, по умолчанию `28`) : Количество блоков единого трансформера.

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`) : Коэффициент расширения для подблоков feedforward.

axes_dims_rope (`tuple[int]`, по умолчанию `(32, 32, 32, 32)`) : Размеры, используемые для вращательных позиционных эмбеддингов, для каждой оси позиции `(t, h, w, l)`.

rope_theta (`int`, по умолчанию `10000`) : Базовая частота для вращательных позиционных эмбеддингов.

eps (`float`, по умолчанию `1e-6`) : Эпсилон для нормализации слоёв и нормализации QK.

flow_map (`bool`, по умолчанию `False`) : Указывает, является ли модель flow map (step-distilled): добавляет `target_timestep_embedder` и требует `target_timestep` в forward-проходе.

Модель Transformer, представленная в FLUX.3 для генерации изображений по тексту и преобразования изображений.

Три режима токенов разделяют одну общую последовательность: токены зашумлённого изображения (`hidden_states`), необязательные токены референсного изображения, закодированного VAE (`image_cond_hidden_states`), и текстовый контекст (`encoder_hidden_states`). Каждый режим сначала проходит через собственные блоки трансформера для этого режима (`mode_blocks` для режимов изображения, `txt_mode_blocks` для текстового контекста), затем текстовый контекст и активные режимы изображения конкатенируются для общих одиночных блоков, и только токены изображения проходят через выходные слои. Модуляция выполняется для каждого режима: токены изображения модулируются временным шагом потока, а токены референсного изображения и текстовый контекст — временным шагом `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/main/src/diffusers/models/transformers/transformer_flux3.py#L494)

**Параметры:**

hidden_states (`torch.Tensor` формы `(batch_size, image_seq_len, in_channels)`) : Шумные латентные токены изображения.

encoder_hidden_states (`torch.Tensor` формы `(batch_size, text_seq_len, joint_attention_dim)`) : Встраивания текстового контекста (стек скрытых состояний Qwen3-VL).

timestep (`torch.Tensor` формы `(batch_size,)`) : Шаг времени потока в диапазоне `[0, 1]` для токенов изображения. Токены референсного изображения и текстовый контекст находятся на шаге времени `0`.

img_ids (`torch.Tensor` формы `(image_seq_len, 4)`) : Идентификаторы позиций `(t, h, w, l)` для токенов изображения, используемые для вращательных позиционных эмбеддингов и общие для всех образцов в батче.

txt_ids (`torch.Tensor` формы `(text_seq_len, 4)`) : Идентификаторы позиций токенов текстового контекста.

image_cond_hidden_states (`torch.Tensor` формы `(batch_size, cond_seq_len, cond_in_channels)`, *необязательный*) : токены референсного изображения, закодированного VAE (чистое условное содержимое, для генерации изображения из изображения).

image_cond_ids (`torch.Tensor` формы `(cond_seq_len, 4)`, *необязательный*) : Идентификаторы позиций токенов опорного изображения. Обязателен при использовании `image_cond_hidden_states`.

target_timestep (`torch.Tensor` формы `(batch_size,)`, *необязательный*) : Шаг времени потока в диапазоне `[0, 1]`, к которому переходит текущий шаг денойзинга. Требуется только для модели flow-map (`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`, где первый элемент представляет собой предсказанную скорость токенов изображения той же формы, что и `hidden_states`.

Метод forward модели [Flux3Transformer2DModel](/docs/diffusers/main/ru/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/main/src/diffusers/models/modeling_outputs.py#L21)

**Параметры:**

sample (`torch.Tensor` формы `(batch_size, num_channels, height, width)` или `(batch size, num_vector_embeds - 1, num_latent_pixels)`, если [Transformer2DModel](/docs/diffusers/main/ru/api/models/transformer2d#diffusers.Transformer2DModel) дискретный): выходные скрытые состояния, обусловленные входом `encoder_hidden_states`. Если модель дискретная, возвращает распределения вероятностей для ненашумленных латентных пикселей.

Вывод [Transformer2DModel](/docs/diffusers/main/ru/api/models/transformer2d#diffusers.Transformer2DModel).