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

LTX2VideoTransformer3DModel

Un modelo Diffusion Transformer para datos 3D de LTX fue introducido por Lightricks.

El modelo se puede cargar con el siguiente fragmento de código.

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)

Fuente

Parámetros:

in_channels (int, por defecto 128) : El número de canales en la entrada.

out_channels (int, por defecto 128) : El número de canales en la salida.

patch_size (int, por defecto 1) : El tamaño de los parches espaciales a utilizar en la capa de incrustación de parches.

patch_size_t (int, por defecto 1) : El tamaño de los parches temporales a utilizar en la capa de incrustación de parches.

num_attention_heads (int, por defecto 32) : El número de cabezas a utilizar para la atención multi-cabeza.

attention_head_dim (int, por defecto 64) : El número de canales en cada cabeza.

cross_attention_dim (int, por defecto 2048 ) : El número de canales para las cabezas de atención cruzada.

num_layers (int, por defecto 28) : El número de capas de bloques Transformer a utilizar.

activation_fn (str, por defecto "gelu-approximate") : Función de activación a utilizar en la red feed-forward.

qk_norm (str, por defecto "rms_norm_across_heads") : La capa de normalización a utilizar.

ff_bias (bool, por defecto True) : Si las capas lineales de la capa feed-forward del video incluyen un término de sesgo. False para LTX-2.5.

audio_ff_bias (bool, por defecto True) : Si las capas lineales de la capa feed-forward de audio incluyen un término de sesgo.

use_prompt_adaln_single (bool, por defecto True) : Si la modulación de Key/Value de la atención cruzada del prompt depende del paso de tiempo. Cuando es False, utiliza en su lugar una tabla fija por capa, lo que permite cachear los valores de Key/Value de la atención cruzada entre los pasos de desruido para un prompt dado.

use_keyframes_abs_pos_embedding (bool, por defecto False) : Si se debe almacenar un embebido de posición absoluta aprendido (1, inner_dim) para los tokens de fotogramas clave generados (LTX-2.5). Cuando True, los tokens seleccionados por video_keyframes_mask reciben este embebido. El argumento es opcional; omitirlo deja el camino de propagación hacia adelante destilado sin cambios.

Un modelo Transformer para datos tipo video utilizado en 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)

Fuente

Parámetros:

hidden_states (torch.Tensor) : Latentes de video en parches de entrada con forma (batch_size, num_video_tokens, in_channels).

audio_hidden_states (torch.Tensor) : Latentes de audio en parches de entrada con forma (batch_size, num_audio_tokens, audio_in_channels).

encoder_hidden_states (torch.Tensor) : Embeddings de texto de entrada del video con forma (batch_size, text_seq_len, self.config.caption_channels).

audio_encoder_hidden_states (torch.Tensor) : Embeddings de texto de audio de entrada con forma (batch_size, text_seq_len, self.config.caption_channels).

timestep (torch.Tensor) : Paso de tiempo de entrada de forma (batch_size, num_video_tokens). Estos ya deben haber sido escalados por self.config.timestep_scale_multiplier.

audio_timestep (torch.Tensor, opcional) : Paso de tiempo de entrada de forma (batch_size,) o (batch_size, num_audio_tokens) para los parámetros de modulación de audio. Esto solo se utiliza en ciertas tuberías, como la tubería I2V.

sigma (torch.Tensor, opcional) : Paso temporal de entrada escalado de forma (batch_size,). Se utiliza para la modulación de atención cruzada de prompts de video en modelos como LTX-2.3.

audio_sigma (torch.Tensor, opcional) : Paso temporal escalado de entrada con forma (batch_size,). Se utiliza para la modulación de atención cruzada de prompts de audio en modelos como LTX-2.3. Si se proporciona sigma pero no audio_sigma, audio_sigma se establecerá con el valor de sigma proporcionado.

encoder_attention_mask (torch.Tensor, opcional) : Máscara de atención de texto multiplicativa opcional de forma (batch_size, text_seq_len).

audio_encoder_attention_mask (torch.Tensor, opcional) : Máscara de atención de texto multiplicativa opcional de forma (batch_size, text_seq_len) para modelado de audio.

num_frames (int, opcional) : El número de fotogramas latentes del video. Se utiliza al calcular las coordenadas del video para RoPE.

height (int, opcional) : La altura del video latente. Se utiliza si se calculan las coordenadas del video para RoPE.

width (int, opcional) : El ancho del video latente. Se utiliza si se calculan las coordenadas del video para RoPE.

fps : (float, opcional, valor predeterminado 24.0): Los fotogramas por segundo deseados del video generado. Se utiliza si se calculan las coordenadas del video para RoPE.

audio_num_frames : (int, opcional): El número de fotogramas de audio latentes. Se utiliza al calcular las coordenadas de audio para RoPE.

video_coords (torch.Tensor, opcional) : Las coordenadas del vídeo que se utilizarán al calcular los embeddings posicionales rotatorios (RoPE) de forma (batch_size, 3, num_video_tokens, 2). Si no se proporciona, se calculará dentro de forward.

audio_coords (torch.Tensor, opcional) : Las coordenadas de audio que se utilizarán al calcular los embeddings posicionales rotatorios (RoPE) de forma (batch_size, 1, num_audio_tokens, 2). Si no se proporciona, se calculará dentro de forward.

isolate_modalities (bool, opcional, valor predeterminado False) : Si se debe aislar cada modalidad desactivando la atención cruzada entre modalidades (de audio a video y de video a audio) en todos los bloques. Úsalo para la guía de modalidades en LTX-2.3.

spatio_temporal_guidance_blocks (list[int], opcional, valor predeterminado None) : Los índices de bloques del transformer en los que se aplicará la guía espaciotemporal (STG), que acorta las operaciones de autoatención utilizando simplemente los valores en lugar de la operación completa de atención de producto escalar (SDPA). Si es None o está vacío, no se aplicará STG a ningún bloque.

perturbation_mask (torch.Tensor, opcional) : Máscara de perturbación para STG de forma (batch_size,) o (batch_size, 1, 1). Debe ser 0 en los elementos del lote donde se debe aplicar STG y 1 en el resto. Si se está usando STG pero no se proporciona perturbation_mask, se aplicará STG (perturbación) a todos los elementos del lote por defecto.

use_cross_timestep (bool opcional, por defecto False) : Si se debe usar la sigma de la modalidad cruzada (el audio es la modalidad cruzada del video, y viceversa) al calcular los parámetros de modulación de la atención cruzada. True es el comportamiento más reciente (p. ej. LTX-2.3); False es el comportamiento heredado de LTX-2.0.

attention_kwargs (dict[str, Any], opcional) : Diccionario opcional de argumentos de palabra clave que se pasarán al procesador de atención.

video_self_attention_mask (torch.Tensor, opcional) : Máscara de autoatención multiplicativa opcional de forma (batch_size, num_video_tokens, num_video_tokens) aplicada a la autoatención del video en cada bloque transformer. Valores en [0, 1] donde 1 significa atención completa y 0 significa enmascarado. Se usa, por ejemplo, en el pipeline IC-LoRA para controlar la intensidad de la atención entre tokens ruidosos y tokens de referencia añadidos. La autoatención de audio no se ve afectada.

video_keyframes_mask (torch.Tensor, opcional) : Marcador opcional por token de forma (batch_size, num_video_tokens, 1), no nulo en los tokens de video cuyo marco latente codifica un solo marco de píxeles. Esos tokens reciben keyframes_abs_pos_embedding. Se ignora cuando el modelo se construyó sin use_keyframes_abs_pos_embedding.

return_dict (bool, opcional, por defecto True) : Si se debe devolver una salida estructurada tipo diccionario de tipo AudioVisualModelOutput o una tupla.

Devuelve: AudioVisualModelOutput o tuple

Si return_dict es True, devuelve una salida estructurada de tipo AudioVisualModelOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es la secuencia de parches latentes del video desruidado y cuyo segundo elemento es la secuencia de parches latentes del audio desruido.

Paso hacia adelante para el transformador audiovisual de video LTX-2.0.