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.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LTX2VideoTransformer3DModel

Một mô hình Diffusion Transformer cho dữ liệu 3D từ LTX đã được giới thiệu bởi Lightricks.

Mô hình có thể được tải bằng đoạn mã sau.

from diffusers import LTX2VideoTransformer3DModel

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

LTX2VideoTransformer3DModel

lớp 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 )

Tham số

  • in_channels (int, mặc định là 128) — Số lượng kênh trong đầu vào.
  • out_channels (int, mặc định là 128) — Số lượng kênh trong đầu ra.
  • patch_size (int, mặc định là 1) — Kích thước của các patch không gian được sử dụng trong lớp nhúng patch.
  • patch_size_t (int, mặc định là 1) — Kích thước của các patch thời gian (temporal patches) được sử dụng trong lớp nhúng patch (patch embedding layer).
  • num_attention_heads (int, mặc định là 32) — Số lượng đầu (heads) được sử dụng cho cơ chế chú ý đa đầu (multi-head attention).
  • attention_head_dim (int, mặc định là 64) — Số lượng kênh trong mỗi head.
  • cross_attention_dim (int, mặc định là 2048 ) — Số lượng kênh cho các đầu chú ý chéo (cross attention).
  • num_layers (int, mặc định là 28) — Số lượng lớp khối Transformer cần sử dụng.
  • activation_fn (str, mặc định là "gelu-approximate") — Hàm kích hoạt được sử dụng trong mạng truyền thẳng.
  • qk_norm (str, mặc định là "rms_norm_across_heads") — Lớp chuẩn hóa cần sử dụng.
  • ff_bias (bool, mặc định là True) — Xác định xem các lớp tuyến tính của lớp feed-forward video có bao gồm số hạng bias hay không. Đặt là False cho LTX-2.5.
  • audio_ff_bias (bool, mặc định là True) — Xác định xem các lớp tuyến tính của lớp feed-forward âm thanh có bao gồm số hạng bias hay không.
  • use_prompt_adaln_single (bool, mặc định là True) — Xác định việc điều biến Key/Value của cross-attention cho prompt có phụ thuộc vào timestep hay không. Khi False, hệ thống sẽ sử dụng một bảng cố định cho từng lớp thay thế, cho phép các giá trị Key/Value của cross-attention được lưu cache xuyên suốt các bước khử nhiễu cho một prompt nhất định.
  • use_keyframes_abs_pos_embedding (bool, mặc định là False) — Xác định có lưu trữ một embedding vị trí tuyệt đối đã học có dạng (1, inner_dim) cho các token keyframe được tạo ra hay không (LTX-2.5). Khi True, các token được chọn bởi video_keyframes_mask sẽ nhận embedding này. Tham số này là tùy chọn; nếu bỏ qua, đường dẫn forward đã distilled sẽ không thay đổi.

Một mô hình Transformer cho dữ liệu dạng video được sử dụng trong 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

Tham số

  • hidden_states (torch.Tensor) — Các latents video dạng patch đầu vào có hình dạng (batch_size, num_video_tokens, in_channels).
  • audio_hidden_states (torch.Tensor) — Các latent âm thanh đã được patchify làm đầu vào, có hình dạng (batch_size, num_audio_tokens, audio_in_channels).
  • encoder_hidden_states (torch.Tensor) — Nhúng văn bản của video đầu vào có hình dạng (batch_size, text_seq_len, self.config.caption_channels).
  • audio_encoder_hidden_states (torch.Tensor) — Nhúng văn bản âm thanh đầu vào có hình dạng (batch_size, text_seq_len, self.config.caption_channels).
  • timestep (torch.Tensor) — Timestep đầu vào có shape (batch_size, num_video_tokens). Các giá trị này đã được nhân với self.config.timestep_scale_multiplier.
  • audio_timestep (torch.Tensor, tuỳ chọn) — Bước thời gian đầu vào có hình dạng (batch_size,) hoặc (batch_size, num_audio_tokens) cho các tham số điều biến âm thanh. Tham số này chỉ được sử dụng bởi một số pipeline nhất định, chẳng hạn như pipeline I2V.
  • sigma (torch.Tensor, tuỳ chọn) — Bước thời gian đầu vào đã được nhân theo hệ số, có hình dạng (batch_size,). Được dùng để điều biến chú ý chéo (cross attention) của prompt video trong các mô hình như LTX-2.3.
  • audio_sigma (torch.Tensor, optional) — Timestep đầu vào đã được scale, có shape (batch_size,). Được sử dụng để điều chế cross attention cho audio prompt trong các mô hình như LTX-2.3. Nếu sigma được cung cấp nhưng audio_sigma thì không, audio_sigma sẽ được đặt bằng giá trị sigma đã cung cấp.
  • encoder_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý văn bản nhân tùy chọn có hình dạng (batch_size, text_seq_len).
  • audio_encoder_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý văn bản nhân tùy chọn có hình dạng (batch_size, text_seq_len) cho mô hình hóa âm thanh.
  • num_frames (int, tùy chọn) — Số lượng khung hình video tiềm ẩn. Được sử dụng khi tính toán tọa độ video cho RoPE.
  • height (int, tùy chọn) — Chiều cao của video tiềm ẩn. Được sử dụng khi tính toán tọa độ video cho RoPE.
  • width (int, tùy chọn) — Chiều rộng của video tiềm ẩn. Được sử dụng khi tính toán tọa độ video cho RoPE.
  • fps — (float, tùy chọn, mặc định là 24.0): Số khung hình mỗi giây mong muốn của video được tạo ra. Được sử dụng khi tính toán tọa độ video cho RoPE.
  • audio_num_frames — (int, tùy chọn): Số lượng khung âm thanh tiềm ẩn. Được sử dụng khi tính toán tọa độ âm thanh cho RoPE.
  • video_coords (torch.Tensor, optional) — Tọa độ video được sử dụng khi tính toán các nhúng vị trí quay (RoPE) có hình dạng (batch_size, 3, num_video_tokens, 2). Nếu không được cung cấp, giá trị này sẽ được tính toán bên trong forward.
  • audio_coords (torch.Tensor, optional) — Tọa độ âm thanh được sử dụng khi tính toán các nhúng vị trí quay (RoPE) có hình dạng (batch_size, 1, num_audio_tokens, 2). Nếu không được cung cấp, giá trị này sẽ được tính toán bên trong forward.
  • isolate_modalities (bool, tùy chọn, mặc định là False) — Có cách ly từng phương thức (modality) bằng cách tắt cross attention giữa các phương thức (từ audio sang video và từ video sang audio) (cho tất cả các khối) hay không. Dùng để hướng dẫn phương thức trong LTX-2.3.
  • spatio_temporal_guidance_blocks (list[int], tùy chọn, mặc định là None) — Các chỉ số khối transformer mà tại đó sẽ áp dụng hướng dẫn không-thời gian (STG), giúp bỏ qua các thao tác tự chú ý bằng cách chỉ sử dụng các giá trị thay vì thao tác chú ý tích có điểm đã chuẩn hóa (SDPA) đầy đủ. Nếu None hoặc rỗng, STG sẽ không được áp dụng cho bất kỳ khối nào.
  • perturbation_mask (torch.Tensor, optional) — Mặt nạ nhiễu (perturbation mask) cho STG có hình dạng (batch_size,) hoặc (batch_size, 1, 1). Giá trị phải là 0 tại các phần tử batch cần áp dụng STG và 1 ở các vị trí còn lại. Nếu STG đang được sử dụng nhưng perturbation_mask không được cung cấp, mặc định sẽ áp dụng STG (nhiễu) cho tất cả các phần tử batch.
  • use_cross_timestep (bool tuỳ chọn, mặc định là False) — Có sử dụng sigma của cross modality (âm thanh là cross modality của video, và ngược lại) khi tính toán các tham số điều biến cross attention hay không. True là hành vi mới hơn (ví dụ LTX-2.3); False là hành vi cũ của LTX-2.0.
  • attention_kwargs (dict[str, Any], tùy chọn) — Dict tùy chọn chứa các tham số dạng từ khóa để truyền cho bộ xử lý attention.
  • video_self_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ tự chú ý nhân tùy chọn có hình dạng (batch_size, num_video_tokens, num_video_tokens) được áp dụng cho tự chú ý video trong mỗi khối transformer. Các giá trị trong [0, 1] trong đó 1 có nghĩa là chú ý đầy đủ và 0 có nghĩa là bị che. Được sử dụng, ví dụ, bởi pipeline IC-LoRA để kiểm soát cường độ chú ý giữa các token nhiễu và các token tham chiếu được thêm vào. Tự chú ý âm thanh không bị ảnh hưởng.
  • video_keyframes_mask (torch.Tensor, tùy chọn) — Dấu hiệu tùy chọn cho từng token có hình dạng (batch_size, num_video_tokens, 1), khác không trên các token video mà khung tiềm ẩn (latent frame) của chúng mã hóa một khung pixel duy nhất. Những token đó sẽ nhận keyframes_abs_pos_embedding. Bỏ qua khi mô hình được xây dựng mà không có use_keyframes_abs_pos_embedding.
  • return_dict (bool, tùy chọn, mặc định là True) — Có nên trả về đầu ra có cấu trúc dạng dict với kiểu AudioVisualModelOutput hay một tuple không.

Trả về

AudioVisualModelOutput hoặc tuple

Nếu return_dict là True, trả về một kết quả có cấu trúc kiểu AudioVisualModelOutput, ngược lại một tuple sẽ được trả về trong đó phần tử đầu tiên là chuỗi patch latent của video đã khử nhiễu và phần tử thứ hai là chuỗi patch latent của âm thanh đã khử nhiễu.

Quá trình truyền thẳng cho biến đổi video âm thanh - hình ảnh LTX-2.0.

Update on GitHub

←LongCatImageTransformer2DModel LTXVideoTransformer3DModel→