diffusers/main/ru/api/models/ltx2_video_transformer3d.md

LTX2VideoTransformer3DModel

Модель Diffusion Transformer для 3D-данных от LTX была представлена компанией Lightricks.

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

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]]

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[int, int, int] = (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)

Источник

Параметры:

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.

forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

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)

Источник

Параметры:

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.