Hugging Face's logo

Diffusers documentation

LTX2VideoTransformer3DModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

classe 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 = (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 )

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'incorporation 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

< >

( 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

Paramètres

  • hidden_states (torch.Tensor) — Latents vidéo patchifiés en entrée 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 d'entrée de forme (batch_size, text_seq_len, self.config.caption_channels).
  • audio_encoder_hidden_states (torch.Tensor) — Embeddings d'entrée audio 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, comme le pipeline I2V.
  • sigma (torch.Tensor, facultatif) — Pas de temps 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) — Pas de temps d’entrée mis à l’échelle de forme (batch_size,). Utilisé pour la modulation de l’attention croisée des prompts 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 textuel multiplicatif facultatif de forme (batch_size, text_seq_len).
  • audio_encoder_attention_mask (torch.Tensor, facultatif) — Masque d'attention textuel 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) — Hauteur de la vidéo latente. 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 à l'intérieur de 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) — Indices des blocs du 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 aux é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 inversement) lors du calcul des paramètres de modulation de l'attention croisée. True correspond au comportement plus récent (par ex. 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 multiplicatif 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 cadre de pixels. Ces jetons reçoivent keyframes_abs_pos_embedding. Ignoré lorsque 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.

Update on GitHub

←LongCatImageTransformer2DModel LTXVideoTransformer3DModel→