Hugging Face's logo

Diffusers documentation

Flux3Transformer2DModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Flux3Transformer2DModel

Модель Transformer для изображений от FLUX.3, предназначенная для генерации изображений по тексту и по изображению. Три режима токенов объединяются в одну последовательность: токены зашумленного изображения, токены референсного изображения, закодированного VAE, и текстовый контекст. Сначала каждый режим проходит через собственные блоки Transformer, затем режимы конкатенируются для общих блоков, после чего токены изображения проходят через выходные слои. Шаги времени (timesteps) задаются для каждого токена: токены изображения несут timestep потока, а токены референса и текстовый контекст находятся на 0.

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

< >

( in_channels: int = 128cond_in_channels: int = 128num_layers: int = 5num_single_layers: int = 28attention_head_dim: int = 128num_attention_heads: int = 24joint_attention_dim: int = 20480timestep_channels: int = 256mlp_ratio: float = 3.0axes_dims_rope: tuple = (32, 32, 32, 32)rope_theta: int = 10000eps: float = 1e-06flow_map: bool = False )

Параметры

  • 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) — Коэффициент расширения в субблоках прямой передачи.
  • 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

< >

( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorimg_ids: Tensortxt_ids: Tensorimage_cond_hidden_states: typing.Optional[torch.Tensor] = Noneimage_cond_ids: typing.Optional[torch.Tensor] = Nonetarget_timestep: typing.Optional[torch.Tensor] = Noneattention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True )

Параметры

  • 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 вместо обычного кортежа.

Метод forward модели Flux3Transformer2DModel.

Transformer2DModelOutput

класс diffusers.models.modeling_outputs.Transformer2DModelOutput

< >

( sample: torch.Tensor )

Параметры

  • sample (torch.Tensor формы (batch_size, num_channels, height, width) или (batch size, num_vector_embeds - 1, num_latent_pixels), если Transformer2DModel дискретный) — Выходные скрытые состояния, обусловленные входом encoder_hidden_states. Если модель дискретная, возвращает распределения вероятностей для латентных пикселей без шума.

Вывод Transformer2DModel.

Update on GitHub

←Flux2Transformer2DModel FluxTransformer2DModel→