# LTX2VideoTransformer3DModel

Модель Diffusion Transformer для 3D-данных от [LTX](https://huggingface.co/Lightricks/LTX-2) была представлена компанией Lightricks.

Модель можно загрузить с помощью следующего фрагмента кода.

```python
from diffusers import LTX2VideoTransformer3DModel

transformer = LTX2VideoTransformer3DModel.from_pretrained("Lightricks/LTX-2", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
```

## LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

#### diffusers.LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

```python
diffusers.LTX2VideoTransformer3DModel(in_channels: int = 128, out_channels: int | None = 128, patch_size: int = 1, patch_size_t: int = 1, num_attention_heads: int = 32, attention_head_dim: int = 128, cross_attention_dim: int = 4096, vae_scale_factors: tuple = (8, 32, 32), pos_embed_max_pos: int = 20, base_height: int = 2048, base_width: int = 2048, gated_attn: bool = False, cross_attn_mod: bool = False, audio_in_channels: int = 128, audio_out_channels: int | None = 128, audio_patch_size: int = 1, audio_patch_size_t: int = 1, audio_num_attention_heads: int = 32, audio_attention_head_dim: int = 64, audio_cross_attention_dim: int = 2048, audio_scale_factor: int = 4, audio_pos_embed_max_pos: int = 20, audio_sampling_rate: int = 16000, audio_hop_length: int = 160, audio_gated_attn: bool = False, audio_cross_attn_mod: bool = False, num_layers: int = 48, activation_fn: str = 'gelu-approximate', qk_norm: str = 'rms_norm_across_heads', norm_elementwise_affine: bool = False, norm_eps: float = 1e-06, caption_channels: int = 3840, attention_bias: bool = True, attention_out_bias: bool = True, rope_theta: float = 10000.0, rope_double_precision: bool = True, causal_offset: int = 1, timestep_scale_multiplier: int = 1000, cross_attn_timestep_scale_multiplier: int = 1000, rope_type: str = 'interleaved', use_prompt_embeddings = True, perturbed_attn: bool = False, ff_bias: bool = True, audio_ff_bias: bool = True, use_prompt_adaln_single: bool = True, use_keyframes_abs_pos_embedding: bool = False)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_ltx2.py#L1081)

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

in_channels (`int`, по умолчанию `128`) : количество каналов на входе.

out_channels (`int`, по умолчанию `128`) : Количество каналов на выходе.

patch_size (`int`, по умолчанию `1`) : Размер пространственных патчей, используемых в слое встраивания патчей.

patch_size_t (`int`, по умолчанию `1`) : Размер временных патчей, используемых в слое встраивания патчей.

num_attention_heads (`int`, по умолчанию `32`) : Количество головок для использования в механизме внимания с несколькими головками.

attention_head_dim (`int`, по умолчанию `64`) : Количество каналов в каждой голове.

cross_attention_dim (`int`, по умолчанию `2048 `) : Количество каналов для голов кросс-внимания.

num_layers (`int`, по умолчанию `28`) : Количество блоков Transformer, которые следует использовать.

activation_fn (`str`, по умолчанию `"gelu-approximate"`) : Функция активации, используемая в полносвязном слое.

qk_norm (`str`, по умолчанию `"rms_norm_across_heads"`) : Слой нормализации, который следует использовать.

ff_bias (`bool`, по умолчанию `True`) : Включают ли линейные слои полносвязного слоя видео член смещения. `False` для LTX-2.5.

audio_ff_bias (`bool`, по умолчанию `True`) : Включают ли линейные слои аудио-прямой (feed-forward) сети смещение (bias).

use_prompt_adaln_single (`bool`, по умолчанию `True`) : Указывает, зависит ли модуляция Key/Value кросс-внимания для промпта от временного шага. Если `False`, используется фиксированная таблица для каждого слоя, что позволяет кэшировать значения Key/Value кросс-внимания между шагами денойзинга для данного промпта.

use_keyframes_abs_pos_embedding (`bool`, по умолчанию `False`) : Флаг, определяющий, следует ли сохранять обученное абсолютное позиционное вложение размера `(1, inner_dim)` для токенов сгенерированных ключевых кадров (LTX-2.5). Если `True`, токены, выбранные с помощью `video_keyframes_mask`, получают это вложение. Аргумент является необязательным; его отсутствие оставляет дистиллированный прямой проход неизменным.

Модель Transformer для видеоподобных данных, используемая в [LTX](https://huggingface.co/Lightricks/LTX-Video).

#### forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, audio_encoder_hidden_states: Tensor, timestep: LongTensor, audio_timestep: typing.Optional[torch.LongTensor] = None, sigma: typing.Optional[torch.Tensor] = None, audio_sigma: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, audio_encoder_attention_mask: typing.Optional[torch.Tensor] = None, num_frames: int | None = None, height: int | None = None, width: int | None = None, fps: float = 24.0, audio_num_frames: int | None = None, video_coords: typing.Optional[torch.Tensor] = None, audio_coords: typing.Optional[torch.Tensor] = None, isolate_modalities: bool = False, spatio_temporal_guidance_blocks: list[int] | None = None, perturbation_mask: typing.Optional[torch.Tensor] = None, use_cross_timestep: bool = False, attention_kwargs: dict[str, typing.Any] | None = None, video_self_attention_mask: typing.Optional[torch.Tensor] = None, video_keyframes_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_ltx2.py#L1365)

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

hidden_states (`torch.Tensor`) : Входные латенты видео, разбитые на патчи, с формой `(batch_size, num_video_tokens, in_channels)`.

audio_hidden_states (`torch.Tensor`) : Входные патчифицированные аудио-латенты формы `(batch_size, num_audio_tokens, audio_in_channels)`.

encoder_hidden_states (`torch.Tensor`) : Входящие текстовые эмбеддинги видео формы `(batch_size, text_seq_len, self.config.caption_channels)`.

audio_encoder_hidden_states (`torch.Tensor`) : Входящие эмбеддинги текста аудио с формой `(batch_size, text_seq_len, self.config.caption_channels)`.

timestep (`torch.Tensor`) : Входной временной шаг формы `(batch_size, num_video_tokens)`. Значения должны быть уже масштабированы множителем `self.config.timestep_scale_multiplier`.

audio_timestep (`torch.Tensor`, *необязательный*) : Входной временной шаг формы `(batch_size,)` или `(batch_size, num_audio_tokens)` для параметров аудио-модуляции. Используется только в некоторых конвейерах, например, в конвейере I2V.

sigma (`torch.Tensor`, *необязательный*) : Входящий масштабированный временной шаг формы (batch_size,). Используется для модуляции кросс-внимания видеопромпта в таких моделях, как LTX-2.3.

audio_sigma (`torch.Tensor`, *optional*) : Входящий масштабированный timestep формы (batch_size,). Используется для модуляции кросс-внимания аудио-промпта в моделях, таких как LTX-2.3. Если `sigma` передано, а `audio_sigma` — нет, `audio_sigma` будет установлено в значение переданного `sigma`.

encoder_attention_mask (`torch.Tensor`, *необязательный*) : Необязательная мультипликативная маска внимания для текста с формой `(batch_size, text_seq_len)`.

audio_encoder_attention_mask (`torch.Tensor`, *необязательный*) : Необязательная мультипликативная маска внимания для текста формы `(batch_size, text_seq_len)` для моделирования аудио.

num_frames (`int`, *optional*) : Количество латентных кадров видео. Используется при вычислении координат видео для RoPE.

height (`int`, *optional*) : Высота латентного видео. Используется при вычислении координат видео для RoPE.

width (`int`, *optional*) : Ширина латентного видео. Используется при вычислении координат видео для RoPE.

fps : (`float`, *необязательный*, по умолчанию `24.0`): Требуемое количество кадров в секунде для генерируемого видео. Используется при вычислении координат видео для RoPE.

audio_num_frames : (`int`, *optional*): Количество латентных кадров аудио. Используется при вычислении координат аудио для RoPE.

video_coords (`torch.Tensor`, *необязательный*) : Координаты видео, используемые при вычислении вращательных позиционных эмбеддингов (RoPE) формы `(batch_size, 3, num_video_tokens, 2)`. Если не указано, будет вычислено внутри `forward`.

audio_coords (`torch.Tensor`, *необязательный*) : Координаты аудио, используемые при вычислении вращательных позиционных эмбеддингов (RoPE) формы `(batch_size, 1, num_audio_tokens, 2)`. Если не указано, они будут вычислены внутри `forward`.

isolate_modalities (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли изолировать каждую модальность, отключая кросс-модальное (аудио-в-видео и видео-в-аудио) кросс-внимание (для всех блоков). Используйте для направленного управления модальностями в LTX-2.3.

spatio_temporal_guidance_blocks (`list[int]`, *optional*, по умолчанию `None`) : Индексы блоков трансформера, на которых применяется пространственно-временное наведение (STG), сокращающее операции само-внимания путём использования значений вместо полной операции масштабированного внимания на основе скалярного произведения (SDPA). Если `None` или пусто, STG не будет применяться ни к одному блоку.

perturbation_mask (`torch.Tensor`, *необязательный*) : Маска возмущения для STG формы `(batch_size,)` или `(batch_size, 1, 1)`. Должна быть равна 0 для элементов батча, к которым следует применить STG, и 1 в остальных случаях. Если STG используется, но `perturbation_mask` не передан, по умолчанию STG (возмущение) будет применено ко всем элементам батча.

use_cross_timestep (`bool` *optional*, по умолчанию `False`) : Использовать ли сигму кросс-модальности (аудио является кросс-модальностью для видео и наоборот) при вычислении параметров модуляции кросс-внимания. `True` — это более новое поведение (например, LTX-2.3); `False` — это устаревшее поведение LTX-2.0.

attention_kwargs (`dict[str, Any]`, *необязательный*) : Необязательный словарь аргументов с ключами, передаваемых в процессор внимания.

video_self_attention_mask (`torch.Tensor`, *optional*) : Необязательная мультипликативная маска self-attention формы `(batch_size, num_video_tokens, num_video_tokens)`, применяемая к self-attention видео в каждом блоке трансформера. Значения в диапазоне `[0, 1]`, где `1` означает полное внимание, а `0` — маскирование. Используется, например, в пайплайне IC-LoRA для управления силой внимания между зашумлёнными токенами и добавленными референсными токенами. Self-attention аудио не затрагивается.

video_keyframes_mask (`torch.Tensor`, *необязательный*) : Необязательный маркер для каждого токена формы `(batch_size, num_video_tokens, 1)`, ненулевой для видео-токенов, чья латентная рамка кодирует одиночный пиксельный кадр. Эти токены получают `keyframes_abs_pos_embedding`. Игнорируется, если модель была создана без `use_keyframes_abs_pos_embedding`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли структурированный вывод типа `AudioVisualModelOutput`, похожий на словарь, или кортеж.

**Возвращает:** `AudioVisualModelOutput` или `tuple`

Если `return_dict` равно `True`, возвращается структурированный вывод типа `AudioVisualModelOutput`, иначе возвращается `tuple`, где первый элемент — это последовательность латентных патчей видео после шумоподавления, а второй — последовательность латентных патчей аудио после шумоподавления.

Прямой проход для аудиовизуального видео-трансформера LTX-2.0.