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

Model Diffusion Transformer untuk data 3D dari LTX diperkenalkan oleh Lightricks.

Model dapat dimuat dengan potongan kode berikut.

from diffusers import LTX2VideoTransformer3DModel

transformer = LTX2VideoTransformer3DModel.from_pretrained("Lightricks/LTX-2", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"

LTX2VideoTransformer3DModel

kelas 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 )

Parameter

  • in_channels (int, defaultnya 128) — Jumlah channel pada input.
  • out_channels (int, defaultnya 128) — Jumlah channel pada output.
  • patch_size (int, defaultnya 1) — Ukuran patch spasial yang akan digunakan di lapisan patch embedding.
  • patch_size_t (int, defaultnya 1) — Ukuran patch temporal yang digunakan di lapisan patch embedding.
  • num_attention_heads (int, defaultnya 32) — Jumlah head yang digunakan untuk multi-head attention.
  • attention_head_dim (int, defaultnya 64) — Jumlah saluran di setiap head.
  • cross_attention_dim (int, defaultnya 2048 ) — Jumlah saluran untuk kepala cross attention.
  • num_layers (int, defaultnya 28) — Jumlah lapisan blok Transformer yang akan digunakan.
  • activation_fn (str, defaultnya "gelu-approximate") — Fungsi aktivasi yang digunakan dalam feed-forward.
  • qk_norm (str, default "rms_norm_across_heads") — Lapisan normalisasi yang digunakan.
  • ff_bias (bool, defaultnya True) — Apakah lapisan linear pada lapisan feed-forward video menyertakan istilah bias. False untuk LTX-2.5.
  • audio_ff_bias (bool, defaultnya True) — Apakah lapisan linear pada lapisan feed-forward audio menyertakan istilah bias.
  • use_prompt_adaln_single (bool, default True) — Apakah modulasi Key/Value cross-attention prompt bergantung pada timestep. Jika False, digunakan tabel per-layer yang tetap, sehingga nilai Key/Value cross-attention dapat di-cache di antara langkah denoising untuk prompt tertentu.
  • use_keyframes_abs_pos_embedding (bool, defaultnya False) — Apakah akan menyimpan embedding posisi absolut (1, inner_dim) yang dipelajari untuk token keyframe yang dihasilkan (LTX-2.5). Jika True, token yang dipilih oleh video_keyframes_mask akan menerima embedding ini. Argumen ini opsional; jika diabaikan, jalur forward yang terdistilasi tidak berubah.

Model Transformer untuk data mirip video yang digunakan dalam 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

Parameter

  • hidden_states (torch.Tensor) — Latens video patchified input dengan bentuk (batch_size, num_video_tokens, in_channels).
  • audio_hidden_states (torch.Tensor) — Latent audio patchified input dengan bentuk (batch_size, num_audio_tokens, audio_in_channels).
  • encoder_hidden_states (torch.Tensor) — Embedding teks video input dengan bentuk (batch_size, text_seq_len, self.config.caption_channels).
  • audio_encoder_hidden_states (torch.Tensor) — Embedding teks audio input dengan bentuk (batch_size, text_seq_len, self.config.caption_channels).
  • timestep (torch.Tensor) — Timestep input dengan bentuk (batch_size, num_video_tokens). Nilai ini seharusnya sudah diskalakan oleh self.config.timestep_scale_multiplier.
  • audio_timestep (torch.Tensor, opsional) — Timestep input dengan bentuk (batch_size,) atau (batch_size, num_audio_tokens) untuk parameter modulasi audio. Ini hanya digunakan oleh beberapa pipeline tertentu, seperti pipeline I2V.
  • sigma (torch.Tensor, opsional) — Timestep input yang diskalakan dengan bentuk (batch_size,). Digunakan untuk modulasi cross attention prompt video dalam model seperti LTX-2.3.
  • audio_sigma (torch.Tensor, opsional) — Timestep input yang diskalakan dengan bentuk (batch_size,). Digunakan untuk modulasi cross attention prompt audio pada model seperti LTX-2.3. Jika sigma diberikan tetapi audio_sigma tidak, audio_sigma akan diatur ke nilai sigma yang diberikan.
  • encoder_attention_mask (torch.Tensor, opsional) — Mask perhatian teks multiplikatif opsional dengan bentuk (batch_size, text_seq_len).
  • audio_encoder_attention_mask (torch.Tensor, opsional) — Mask perhatian teks multiplikatif opsional dengan bentuk (batch_size, text_seq_len) untuk pemodelan audio.
  • num_frames (int, opsional) — Jumlah frame video laten. Digunakan jika menghitung koordinat video untuk RoPE.
  • height (int, opsional) — Tinggi video laten. Digunakan jika menghitung koordinat video untuk RoPE.
  • width (int, opsional) — Lebar video laten. Digunakan jika menghitung koordinat video untuk RoPE.
  • fps — (float, opsional, default 24.0): Jumlah frame per detik yang diinginkan untuk video yang dihasilkan. Digunakan jika menghitung koordinat video untuk RoPE.
  • audio_num_frames — (int, opsional): Jumlah frame audio laten. Digunakan jika menghitung koordinat audio untuk RoPE.
  • video_coords (torch.Tensor, opsional) — Koordinat video yang akan digunakan saat menghitung rotary positional embeddings (RoPE) dengan bentuk (batch_size, 3, num_video_tokens, 2). Jika tidak diberikan, nilai ini akan dihitung di dalam forward.
  • audio_coords (torch.Tensor, opsional) — Koordinat audio yang akan digunakan saat menghitung rotary positional embeddings (RoPE) dengan bentuk (batch_size, 1, num_audio_tokens, 2). Jika tidak diberikan, nilai ini akan dihitung di dalam forward.
  • isolate_modalities (bool, opsional, default False) — Apakah akan mengisolasi setiap modalitas dengan mematikan cross-attention antar-modalitas (audio-ke-video dan video-ke-audio) untuk semua blok. Gunakan untuk panduan modalitas di LTX-2.3.
  • spatio_temporal_guidance_blocks (list[int], opsional, default None) — Indeks blok transformer tempat menerapkan spatio-temporal guidance (STG), yang memangkas operasi self-attention dengan hanya menggunakan nilai-nilai tersebut alih-alih operasi scaled dot-product attention (SDPA) penuh. Jika None atau kosong, STG tidak akan diterapkan pada blok mana pun.
  • perturbation_mask (torch.Tensor, opsional) — Mask perturbasi untuk STG dengan bentuk (batch_size,) atau (batch_size, 1, 1). Harus bernilai 0 pada elemen batch tempat STG diterapkan dan 1 di tempat lain. Jika STG digunakan tetapi perturbation_mask tidak diberikan, secara default STG (perturbasi) akan diterapkan pada semua elemen batch.
  • use_cross_timestep (bool opsional, default False) — Apakah akan menggunakan sigma dari modality silang (audio adalah modality silang dari video, dan sebaliknya) saat menghitung parameter modulasi cross attention. True adalah perilaku yang lebih baru (mis. LTX-2.3); False adalah perilaku legacy LTX-2.0.
  • attention_kwargs (dict[str, Any], opsional) — Dict opsional berisi argumen kata kunci yang akan diteruskan ke pemroses perhatian.
  • video_self_attention_mask (torch.Tensor, opsional) — Mask self-attention multiplikatif opsional dengan bentuk (batch_size, num_video_tokens, num_video_tokens) yang diterapkan pada self-attention video di setiap blok transformer. Nilai dalam [0, 1] di mana 1 berarti perhatian penuh dan 0 berarti ter-mask. Digunakan, misalnya, oleh pipeline IC-LoRA untuk mengontrol kekuatan perhatian antara token berisik dan token referensi yang ditambahkan. Self-attention audio tidak terpengaruh.
  • video_keyframes_mask (torch.Tensor, opsional) — Penanda per-token opsional dengan bentuk (batch_size, num_video_tokens, 1), bernilai non-nol pada token video yang frame latennya mengodekan satu frame piksel. Token-token tersebut menerima keyframes_abs_pos_embedding. Diabaikan jika model dibangun tanpa use_keyframes_abs_pos_embedding.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan output terstruktur seperti dict bertipe AudioVisualModelOutput atau tuple.

Mengembalikan

AudioVisualModelOutput atau tuple

Jika return_dict adalah True, mengembalikan output terstruktur bertipe AudioVisualModelOutput, selain itu tuple yang dikembalikan di mana elemen pertama adalah urutan patch laten video yang telah didenois dan elemen kedua adalah urutan patch laten audio yang telah didenois.

Forward pass untuk transformer video audiovisual LTX-2.0.

Update on GitHub

←LongCatImageTransformer2DModel LTXVideoTransformer3DModel→