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

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

Sumber

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 akan digunakan di lapisan patch embedding.

num_attention_heads (int, defaultnya 32) : Jumlah kepala yang digunakan untuk multi-head attention.

attention_head_dim (int, defaultnya 64) : Jumlah channel di setiap head.

cross_attention_dim (int, defaultnya 2048 ) : Jumlah channel untuk cross attention heads.

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, defaultnya "rms_norm_across_heads") : Lapisan normalisasi yang akan digunakan.

ff_bias (bool, defaultnya True) : Apakah lapisan linear pada lapisan feed-forward video termasuk 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, defaultnya True) : Apakah modulasi Key/Value cross-attention dari prompt bergantung pada timestep. Ketika False, ia menggunakan tabel per-layer yang tetap, sehingga nilai Key/Value cross-attention dapat di-cache di antara langkah-langkah denoising untuk prompt tertentu.

use_keyframes_abs_pos_embedding (bool, defaultnya False) : Apakah akan menyimpan embedding posisi absolut yang dipelajari berukuran (1, inner_dim) untuk token keyframe yang dihasilkan (LTX-2.5). Jika True, token yang dipilih oleh video_keyframes_mask akan menerima embedding ini. Argumen ini bersifat opsional; jika diabaikan, jalur forward yang terdistilasi tidak akan berubah.

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

Sumber

Parameter:

hidden_states (torch.Tensor) : Laten video patchified input dengan bentuk (batch_size, num_video_tokens, in_channels).

audio_hidden_states (torch.Tensor) : Laten 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 pipeline tertentu seperti pipeline I2V.

sigma (torch.Tensor, opsional) : Input timestep yang telah diskalakan dengan bentuk (batch_size,). Digunakan untuk modulasi cross attention prompt video pada model seperti LTX-2.3.

audio_sigma (torch.Tensor, opsional) : Input scaled timestep 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 diset 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, defaultnya 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, defaultnya False) : Apakah akan mengisolasi setiap modalitas dengan mematikan cross attention lintas-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, defaultnya None) : Indeks blok transformer tempat panduan spasio-temporal (STG) diterapkan, 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, defaultnya False) : Apakah akan menggunakan sigma cross modality (audio adalah cross modality dari video, dan sebaliknya) saat menghitung parameter modulasi cross attention. True adalah perilaku yang lebih baru (misalnya 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, defaultnya True) : Apakah akan mengembalikan output terstruktur seperti dict dari tipe AudioVisualModelOutput atau tuple.

Mengembalikan: AudioVisualModelOutput atau tuple

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

Forward pass untuk transformer video audiovisual LTX-2.0.