Hugging Face's logo

Diffusers documentation

LTX2VideoTransformer3DModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

clase diffusers.LTX2VideoTransformer3DModel

< >

( in_channels: int = 128out_channels: int | None = 128patch_size: int = 1patch_size_t: int = 1num_attention_heads: int = 32attention_head_dim: int = 128cross_attention_dim: int = 4096vae_scale_factors: tuple[int, int, int] = (8, 32, 32)pos_embed_max_pos: int = 20base_height: int = 2048base_width: int = 2048gated_attn: bool = Falsecross_attn_mod: bool = Falseaudio_in_channels: int = 128audio_out_channels: int | None = 128audio_patch_size: int = 1audio_patch_size_t: int = 1audio_num_attention_heads: int = 32audio_attention_head_dim: int = 64audio_cross_attention_dim: int = 2048audio_scale_factor: int = 4audio_pos_embed_max_pos: int = 20audio_sampling_rate: int = 16000audio_hop_length: int = 160audio_gated_attn: bool = Falseaudio_cross_attn_mod: bool = Falsenum_layers: int = 48activation_fn: str = 'gelu-approximate'qk_norm: str = 'rms_norm_across_heads'norm_elementwise_affine: bool = Falsenorm_eps: float = 1e-06caption_channels: int = 3840attention_bias: bool = Trueattention_out_bias: bool = Truerope_theta: float = 10000.0rope_double_precision: bool = Truecausal_offset: int = 1timestep_scale_multiplier: int = 1000cross_attn_timestep_scale_multiplier: int = 1000rope_type: str = 'interleaved'use_prompt_embeddings = Trueperturbed_attn: bool = Falseff_bias: bool = Trueaudio_ff_bias: bool = Trueuse_prompt_adaln_single: bool = Trueuse_keyframes_abs_pos_embedding: bool = False )

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 que se usarán en la capa de incrustación de parches.
  • patch_size_t (int, por defecto 1) — El tamaño de los parches temporales que se usarán 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 vídeo 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 de avance hacia adelante de audio incluyen un término de sesgo.
  • use_prompt_adaln_single (bool, por defecto True) — Indica si la modulación de Key/Value de la atención cruzada del prompt depende del paso de tiempo. Cuando es False, se 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, valor predeterminado False) — Indica si se debe almacenar un embebido de posición absoluta aprendido de (1, inner_dim) para los tokens de keyframes generados (LTX-2.5). Cuando True, los tokens seleccionados por video_keyframes_mask reciben este embebido. El argumento es opcional; omitirlo deja sin cambios la ruta de propagación hacia adelante destilada.

Un modelo Transformer para datos tipo video utilizado en LTX.

forward

< >

( hidden_states: Tensoraudio_hidden_states: Tensorencoder_hidden_states: Tensoraudio_encoder_hidden_states: Tensortimestep: LongTensoraudio_timestep: typing.Optional[torch.LongTensor] = Nonesigma: typing.Optional[torch.Tensor] = Noneaudio_sigma: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.Tensor] = Noneaudio_encoder_attention_mask: typing.Optional[torch.Tensor] = Nonenum_frames: int | None = Noneheight: int | None = Nonewidth: int | None = Nonefps: float = 24.0audio_num_frames: int | None = Nonevideo_coords: typing.Optional[torch.Tensor] = Noneaudio_coords: typing.Optional[torch.Tensor] = Noneisolate_modalities: bool = Falsespatio_temporal_guidance_blocks: list[int] | None = Noneperturbation_mask: typing.Optional[torch.Tensor] = Noneuse_cross_timestep: bool = Falseattention_kwargs: dict[str, typing.Any] | None = Nonevideo_self_attention_mask: typing.Optional[torch.Tensor] = Nonevideo_keyframes_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool = True ) → AudioVisualModelOutput or tuple

Parámetros

  • hidden_states (torch.Tensor) — Latentes de video segmentados en parches de entrada con forma (batch_size, num_video_tokens, in_channels).
  • audio_hidden_states (torch.Tensor) — Latentes de audio segmentados de entrada con forma (batch_size, num_audio_tokens, audio_in_channels).
  • encoder_hidden_states (torch.Tensor) — Incorporaciones de texto de video de entrada 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 haberse escalado 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 pipelines, como la pipeline I2V.
  • sigma (torch.Tensor, opcional) — Paso temporal de entrada escalado de forma (batch_size,). Se utiliza para la modulación de la atención cruzada del prompt de vídeo en modelos como LTX-2.3.
  • audio_sigma (torch.Tensor, opcional) — Paso temporal de entrada escalado de forma (batch_size,). Se utiliza para la modulación de la 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á en 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 el 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 al calcular las coordenadas del video para RoPE.
  • audio_num_frames — (int, opcional): El número de fotogramas latentes de audio. Se utiliza al calcular las coordenadas de audio para RoPE.
  • video_coords (torch.Tensor, opcional) — Las coordenadas del video 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 aísla 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 aplica 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, por defecto se aplicará STG (perturbación) a todos los elementos del lote.
  • use_cross_timestep (bool opcional, valor predeterminado False) — Indica si se debe utilizar 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 los tokens ruidosos y los tokens de referencia añadidos. La autoatención del 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 frame latente codifica un solo frame 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, valor predeterminado True) — Si se devuelve 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.

Update on GitHub

←LongCatImageTransformer2DModel LTXVideoTransformer3DModel→