# LTX2VideoTransformer3DModel

Một mô hình Diffusion Transformer cho dữ liệu 3D từ [LTX](https://huggingface.co/Lightricks/LTX-2) đã được giới thiệu bởi Lightricks.

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

```python
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]]

```python
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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1069)

**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 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ố 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 tiền tiến (feed-forward) trong 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ữ embedding vị trí tuyệt đối đã học có kích thước `(1, inner_dim)` cho các token keyframe được tạo ra (LTX-2.5) hay không. 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 đã chưng cất sẽ không thay đổi.

Một mô hình Transformer cho dữ liệu dạng video được sử dụng trong [LTX](https://huggingface.co/Lightricks/LTX-Video).

#### forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

```python
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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1353)

**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 latents âm thanh đã được chia thành patch, 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`) : Bước thời gian đầu vào có hình dạng `(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`, *tùy 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`, *tùy chọn*) : Timestep đã được scale đầu vào có shape (batch_size,). Được sử dụng cho điều chế cross attention của video prompt trong các mô hình như LTX-2.3.

audio_sigma (`torch.Tensor`, *optional*) : Timestep đã được scale đầu vào có shape (batch_size,). Được dùng cho điều chế cross attention của 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*) : Độ rộng của video tiềm ẩn. Được sử dụng khi tính toán tọa độ video cho RoPE.

fps : (`float`, *tuỳ 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`, *optional*): 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`, *tùy chọn*) : Các 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`, *tùy chọn*) : Các 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`, *tuỳ chọn*, mặc định là `False`) : Có cách ly từng phương thức bằng cách tắt cross attention liên phương thức (từ âm thanh sang video và từ video sang âm thanh) (cho tất cả các khối) hay không. Dùng cho việc dẫn hướng phương thức trong LTX-2.3.

spatio_temporal_guidance_blocks (`list[int]`, *optional*, mặc định là `None`) : Các chỉ số khối transformer tại đó á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ì toàn bộ thao tác chú ý tích vô hướng có chuẩn hóa (SDPA). 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`, *tùy chọn*) : Mặt nạ nhiễu 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 mà STG cần được áp dụng và 1 ở các vị trí khác. 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` *optional*, mặc định là `False`) : Có sử dụng sigma của liên phương thức (âm thanh là phương thức liên kết của video, và ngược lại) khi tính toán các tham số điều biến chú ý liên kết 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*) : Từ điển tùy chọn chứa các đối số theo tên để truyền cho bộ xử lý chú ý.

video_self_attention_mask (`torch.Tensor`, *optional*) : Mặt nạ self-attention nhân tùy chọn có hình dạng `(batch_size, num_video_tokens, num_video_tokens)` được áp dụng cho self-attention của 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. Self-attention của â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ề kết quả có cấu trúc kiểu `AudioVisualModelOutput`, ngược lại trả về một `tuple` trong đó phần tử đầu tiên là chuỗi patch latent video đã khử nhiễu và phần tử thứ hai là chuỗi patch latent audio đã khử nhiễu.

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