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

LTX2VideoTransformer3DModel

Un modèle Diffusion Transformer pour des données 3D de LTX a été introduit par Lightricks.

Le modèle peut être chargé à l'aide du fragment de code suivant.

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)

Source

Paramètres :

in_channels (int, par défaut 128) : Le nombre de canaux dans l'entrée.

out_channels (int, par défaut 128) : Le nombre de canaux dans la sortie.

patch_size (int, par défaut 1) : La taille des patches spatiaux à utiliser dans la couche d'encodage de patches.

patch_size_t (int, par défaut 1) : La taille des patches temporels à utiliser dans la couche d'encodage de patches.

num_attention_heads (int, par défaut 32) : Le nombre de têtes à utiliser pour l'attention multi-têtes.

attention_head_dim (int, par défaut 64) : Le nombre de canaux dans chaque tête.

cross_attention_dim (int, par défaut 2048 ) : Le nombre de canaux pour les têtes d'attention croisée.

num_layers (int, par défaut 28) : Le nombre de blocs Transformer à utiliser.

activation_fn (str, par défaut "gelu-approximate") : Fonction d'activation à utiliser dans le réseau de neurones à propagation avant.

qk_norm (str, par défaut "rms_norm_across_heads") : La couche de normalisation à utiliser.

ff_bias (bool, par défaut True) : Indique si les couches linéaires de la couche feed-forward de la vidéo incluent un terme de biais. False pour LTX-2.5.

audio_ff_bias (bool, par défaut True) : Indique si les couches linéaires de la couche feed-forward audio incluent un terme de biais.

use_prompt_adaln_single (bool, par défaut True) : Indique si la modulation des clés/valeurs de l'attention croisée du prompt dépend de l'étape temporelle. Si False, une table fixe par couche est utilisée à la place, ce qui permet de mettre en cache les valeurs des clés/valeurs de l'attention croisée entre les étapes de débruitage pour un prompt donné.

use_keyframes_abs_pos_embedding (bool, par défaut False) : Indique s'il faut stocker un embedding de position absolue appris de forme (1, inner_dim) pour les jetons de keyframes générés (LTX-2.5). Si True, les jetons sélectionnés par video_keyframes_mask reçoivent cet embedding. L'argument est facultatif ; son omission laisse le chemin de propagation avant distillé inchangé.

Un modèle Transformer pour des données de type vidéo utilisé dans 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)

Source

Paramètres :

hidden_states (torch.Tensor) : Latents vidéo en entrée, patchifiées, de forme (batch_size, num_video_tokens, in_channels).

audio_hidden_states (torch.Tensor) : Latents audio patchifiés en entrée de forme (batch_size, num_audio_tokens, audio_in_channels).

encoder_hidden_states (torch.Tensor) : Embeddings de texte de la vidéo en entrée, de forme (batch_size, text_seq_len, self.config.caption_channels).

audio_encoder_hidden_states (torch.Tensor) : Embeddings de texte audio en entrée de forme (batch_size, text_seq_len, self.config.caption_channels).

timestep (torch.Tensor) : Pas de temps d'entrée de forme (batch_size, num_video_tokens). Ils doivent déjà être mis à l'échelle par self.config.timestep_scale_multiplier.

audio_timestep (torch.Tensor, facultatif) : Pas de temps d'entrée de forme (batch_size,) ou (batch_size, num_audio_tokens) pour les paramètres de modulation audio. N'est utilisé que par certains pipelines, tels que le pipeline I2V.

sigma (torch.Tensor, facultatif) : Timestep d'entrée mis à l'échelle de forme (batch_size,). Utilisé pour la modulation de l'attention croisée du prompt vidéo dans des modèles tels que LTX-2.3.

audio_sigma (torch.Tensor, facultatif) : Timestep d'entrée mis à l'échelle de forme (batch_size,). Utilisé pour la modulation de l'attention croisée du prompt audio dans des modèles tels que LTX-2.3. Si sigma est fourni mais que audio_sigma ne l'est pas, audio_sigma sera défini à la valeur de sigma fournie.

encoder_attention_mask (torch.Tensor, facultatif) : Masque d'attention textuelle multiplicatif facultatif de forme (batch_size, text_seq_len).

audio_encoder_attention_mask (torch.Tensor, facultatif) : Masque d'attention textuelle multiplicatif facultatif de forme (batch_size, text_seq_len) pour la modélisation audio.

num_frames (int, facultatif) : Le nombre de trames vidéo latentes. Utilisé lors du calcul des coordonnées vidéo pour RoPE.

height (int, facultatif) : La hauteur latente de la vidéo. Utilisée lors du calcul des coordonnées vidéo pour RoPE.

width (int, facultatif) : La largeur de la vidéo latente. Utilisée lors du calcul des coordonnées vidéo pour RoPE.

fps : (float, facultatif, valeur par défaut 24.0) : Le nombre de images par seconde souhaité pour la vidéo générée. Utilisé lors du calcul des coordonnées vidéo pour RoPE.

audio_num_frames : (int, facultatif) : Le nombre de trames audio latentes. Utilisé lors du calcul des coordonnées audio pour RoPE.

video_coords (torch.Tensor, facultatif) : Les coordonnées vidéo à utiliser lors du calcul des embeddings positionnels rotatifs (RoPE) de forme (batch_size, 3, num_video_tokens, 2). Si non fourni, elles seront calculées dans forward.

audio_coords (torch.Tensor, facultatif) : Les coordonnées audio à utiliser lors du calcul des embeddings positionnels rotatifs (RoPE) de forme (batch_size, 1, num_audio_tokens, 2). Si non fourni, elles seront calculées à l'intérieur de forward.

isolate_modalities (bool, facultatif, valeur par défaut False) : Indique s'il faut isoler chaque modalité en désactivant l'attention croisée inter-modalités (audio-vers-vidéo et vidéo-vers-audio) (pour tous les blocs). À utiliser pour le guidage par modalité dans LTX-2.3.

spatio_temporal_guidance_blocks (list[int], facultatif, valeur par défaut None) : Les indices des blocs de transformer auxquels appliquer le guidage spatio-temporel (STG), qui contourne les opérations d'auto-attention en utilisant simplement les valeurs plutôt que l'opération complète d'attention par produit scalaire normalisé (SDPA). Si None ou vide, le STG ne sera appliqué à aucun bloc.

perturbation_mask (torch.Tensor, facultatif) : Masque de perturbation pour le STG de forme (batch_size,) ou (batch_size, 1, 1). Doit être 0 pour les éléments du lot où le STG doit être appliqué et 1 ailleurs. Si le STG est utilisé mais que perturbation_mask n'est pas fourni, le STG (perturbation) sera appliqué par défaut à tous les éléments du lot.

use_cross_timestep (bool facultatif, par défaut False) : Indique s'il faut utiliser la sigma de la modalité croisée (l'audio est la modalité croisée de la vidéo, et vice versa) lors du calcul des paramètres de modulation de l'attention croisée. True correspond au comportement plus récent (par exemple LTX-2.3) ; False correspond au comportement hérité de LTX-2.0.

attention_kwargs (dict[str, Any], facultatif) : Dictionnaire facultatif d'arguments nommés à passer au processeur d'attention.

video_self_attention_mask (torch.Tensor, facultatif) : Masque de self-attention multiplicative facultatif de forme (batch_size, num_video_tokens, num_video_tokens) appliqué à la self-attention vidéo dans chaque bloc transformer. Les valeurs sont comprises dans [0, 1], où 1 signifie une attention complète et 0 signifie masqué. Utilisé par exemple par le pipeline IC-LoRA pour contrôler l'intensité de l'attention entre les tokens bruités et les tokens de référence ajoutés. La self-attention audio n'est pas affectée.

video_keyframes_mask (torch.Tensor, facultatif) : Marqueur facultatif par jeton de forme (batch_size, num_video_tokens, 1), non nul pour les jetons vidéo dont le cadre latent encode un seul pixel. Ces jetons reçoivent keyframes_abs_pos_embedding. Ignoré si le modèle a été construit sans use_keyframes_abs_pos_embedding.

return_dict (bool, facultatif, par défaut True) : Indique s'il faut retourner une sortie structurée de type dictionnaire de type AudioVisualModelOutput ou un tuple.

Retourne : AudioVisualModelOutput ou tuple

Si return_dict est True, renvoie une sortie structurée de type AudioVisualModelOutput, sinon un tuple est renvoyé dont le premier élément est la séquence de patches latents vidéo débruités et le second élément est la séquence de patches latents audio débruités.

Passage avant pour le transformateur vidéo audiovisuel LTX-2.0.