# LTX2VideoTransformer3DModel

Lightricks 推出了一款用于 3D 数据的 Diffusion Transformer 模型，来自 [LTX](https://huggingface.co/Lightricks/LTX-2)。

可以使用以下代码片段加载该模型。

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1069)

**参数：**

in_channels (`int`，默认为 `128`)：输入中的通道数。

out_channels (`int`，默认为 `128`)：输出中的通道数。

patch_size (`int`，默认为 `1`)：在 patch embedding 层中使用的空间 patch 的大小。

patch_size_t (`int`，默认为 `1`)：在 patch embedding 层中使用的时序 patch 的大小。

num_attention_heads (`int`，默认为 `32`)：用于多头注意力的注意力头数量。

attention_head_dim (`int`，默认为 `64`)：每个头中的通道数。

cross_attention_dim (`int`，默认为 `2048 `)：交叉注意力头的通道数。

num_layers (`int`，默认为 `28`)：要使用的 Transformer 块层数。

activation_fn (`str`，默认为 `"gelu-approximate"`)：前馈网络中使用的激活函数。

qk_norm (`str`，默认为 `"rms_norm_across_heads"`)：要使用的归一化层。

ff_bias (`bool`，默认为 `True`)：视频前馈层的线性层是否包含偏置项。LTX-2.5 为 `False`。

audio_ff_bias (`bool`，默认为 `True`)：音频前馈层的线性层是否包含偏置项。

use_prompt_adaln_single (`bool`，默认为 `True`)：提示词的交叉注意力 Key/Value 调制是否依赖于时间步。当设置为 `False` 时，将使用固定的逐层查找表，从而使得针对给定提示词的交叉注意力 Key/Value 值可以在去噪步骤之间进行缓存。

use_keyframes_abs_pos_embedding (`bool`，默认为 `False`)：是否存储用于生成关键帧 token 的 `(1, inner_dim)` 绝对位置嵌入（LTX-2.5）。当 `True` 时，由 `video_keyframes_mask` 选中的 token 将接收此嵌入。该参数为可选；省略它不会改变蒸馏前向路径。

用于 [LTX](https://huggingface.co/Lightricks/LTX-Video) 中类视频数据的 Transformer 模型。

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1353)

**参数：**

hidden_states (`torch.Tensor`) : 形状为 `(batch_size, num_video_tokens, in_channels)` 的输入分块视频潜变量。

audio_hidden_states (`torch.Tensor`) : 形状为 `(batch_size, num_audio_tokens, audio_in_channels)` 的输入分块音频潜变量。

encoder_hidden_states (`torch.Tensor`) : 输入的视频文本嵌入，形状为 `(batch_size, text_seq_len, self.config.caption_channels)`。

audio_encoder_hidden_states (`torch.Tensor`) : 输入音频文本嵌入，形状为 `(batch_size, text_seq_len, self.config.caption_channels)`。

timestep (`torch.Tensor`) : 形状为 `(batch_size, num_video_tokens)` 的输入时间步。这些值应已按 `self.config.timestep_scale_multiplier` 进行缩放。

audio_timestep (`torch.Tensor`, *可选*) : 输入时间步，形状为 `(batch_size,)` 或 `(batch_size, num_audio_tokens)`，用于音频调制参数。此参数仅由 I2V 流水线等特定流水线使用。

sigma (`torch.Tensor`, *可选*) : 形状为 (batch_size,) 的输入缩放时间步。用于 LTX-2.3 等模型中的视频提示交叉注意力调制。

audio_sigma (`torch.Tensor`, *可选*) : 形状为 (batch_size,) 的输入缩放时间步。用于 LTX-2.3 等模型中的音频提示交叉注意力调制。如果提供了 `sigma` 但未提供 `audio_sigma`，则 `audio_sigma` 将被设置为所提供的 `sigma` 值。

encoder_attention_mask (`torch.Tensor`, *可选*) : 形状为 `(batch_size, text_seq_len)` 的可选乘法文本注意力掩码。

audio_encoder_attention_mask (`torch.Tensor`, *可选*) : 用于音频建模的可选乘法文本注意力掩码，形状为 `(batch_size, text_seq_len)`。

num_frames (`int`, *可选*)：潜在视频帧的数量。在计算用于 RoPE 的视频坐标时使用。

height (`int`，*可选*)：潜在视频的高度。在计算用于 RoPE 的视频坐标时使用。

width (`int`，*可选*)：潜在视频的宽度。在计算用于 RoPE 的视频坐标时使用。

fps : (`float`，*可选*，默认值为 `24.0`)：生成视频所需的每秒帧数。在计算用于 RoPE 的视频坐标时使用。

audio_num_frames : (`int`, *可选*): 潜在音频帧的数量。用于计算 RoPE 的音频坐标。

video_coords (`torch.Tensor`, *可选*) : 用于计算旋转位置嵌入（RoPE）的视频坐标，形状为 `(batch_size, 3, num_video_tokens, 2)`。如果未提供，将在 `forward` 内部进行计算。

audio_coords (`torch.Tensor`, *可选*) : 用于计算旋转位置嵌入（RoPE）的音频坐标，形状为 `(batch_size, 1, num_audio_tokens, 2)`。如果未提供，将在 `forward` 内部进行计算。

isolate_modalities (`bool`，*可选*，默认为 `False`)：是否通过关闭跨模态（音频到视频以及视频到音频）交叉注意力（针对所有块）来隔离每个模态。用于 LTX-2.3 中的模态引导。

spatio_temporal_guidance_blocks (`list[int]`, *可选*，默认为 `None`) : 应用时空引导（STG）的 Transformer 块索引。STG 通过直接使用数值来跳过自注意力操作，而不是执行完整的缩放点积注意力（SDPA）操作。如果为 `None` 或为空，则不会在任何块上应用 STG。

perturbation_mask (`torch.Tensor`, *可选*) : STG 的扰动掩码，形状为 `(batch_size,)` 或 `(batch_size, 1, 1)`。在需要应用 STG 的批次元素处应为 0，其余位置应为 1。如果使用了 STG 但未提供 `perturbation_mask`，则默认对所有批次元素应用 STG（即进行扰动）。

use_cross_timestep (`bool` *可选*，默认为 `False`)：在计算交叉注意力调制参数时，是否使用跨模态（音频是视频的跨模态，反之亦然）sigma。`True` 是较新的行为（例如 LTX-2.3）；`False` 是旧版 LTX-2.0 的行为。

attention_kwargs (`dict[str, Any]`，*可选*)：可选的字典，包含要传递给注意力处理器的关键字参数。

video_self_attention_mask (`torch.Tensor`, *可选*) : 应用于每个 transformer 块中视频自注意力的可选乘法自注意力掩码，形状为 `(batch_size, num_video_tokens, num_video_tokens)`。取值范围为 `[0, 1]`，其中 `1` 表示完全注意，`0` 表示被掩码。例如，IC-LoRA 流水线使用它来控制噪声 token 与附加的参考 token 之间的注意力强度。音频自注意力不受影响。

video_keyframes_mask (`torch.Tensor`, *可选*) : 形状为 `(batch_size, num_video_tokens, 1)` 的可选逐 token 标记，在那些其潜在帧编码单个像素帧的视频 token 上为非零值。这些 token 会接收 `keyframes_abs_pos_embedding`。如果模型构建时未启用 `use_keyframes_abs_pos_embedding`，则此参数会被忽略。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回类型为 `AudioVisualModelOutput` 的类字典结构化输出，还是返回元组。

**返回：** `AudioVisualModelOutput` 或 `tuple`

如果 `return_dict` 为 `True`，则返回类型为 `AudioVisualModelOutput` 的结构化输出；否则返回一个 `tuple`，其中第一个元素是去噪后的视频潜在补丁序列，第二个元素是去噪后的音频潜在补丁序列。

LTX-2.0 音视频视频 Transformer 的前向传播。