Diffusers documentation
LTX2VideoTransformer3DModel
LTX2VideoTransformer3DModel
LTX によって、3Dデータ向けの Diffusion Transformer モデルが紹介されました。
モデルは、以下のコードスニペットで読み込むことができます。
from diffusers import LTX2VideoTransformer3DModel
transformer = LTX2VideoTransformer3DModel.from_pretrained("Lightricks/LTX-2", subfolder="transformer", dtype=torch.bfloat16).to("cuda") # or "mps", "xpu", "cpu"LTX2VideoTransformer3DModel
class diffusers.LTX2VideoTransformer3DModel
< source >( 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 )
パラメータ
- in_channels (
int, デフォルトは128) — 入力におけるチャネル数です。 - out_channels (
int、デフォルトは128) — 出力のチャネル数。 - patch_size (
int、デフォルトは1) — パッチ埋め込み層で使用する空間パッチのサイズです。 - patch_size_t (
int, デフォルトは1) — パッチ埋め込み層で使用する時間パッチのサイズです。 - 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) — 動画フィードフォワード層の線形層にバイアス項を含むかどうか。FalseがLTX-2.5です。 - audio_ff_bias (
bool、デフォルトはTrue) — オーディオのフィードフォワード層の線形層にバイアス項が含まれるかどうかを示します。 - use_prompt_adaln_single (
bool、デフォルトはTrue) — プロンプトのクロスアテンションにおける Key/Value のモジュレーションがタイムステップに依存するかどうかを指定します。Falseの場合、代わりにレイヤーごとの固定テーブルを使用し、与えられたプロンプトに対して、デノイジングステップ間でクロスアテンションの Key/Value 値をキャッシュ可能にします。 - use_keyframes_abs_pos_embedding (
bool、デフォルトはFalse) — 生成されたキーフレームトークンに対して、学習された(1, inner_dim)の絶対位置埋め込みを保存するかどうかを指定します (LTX-2.5)。Trueの場合、video_keyframes_maskによって選択されたトークンにこの埋め込みが適用されます。この引数は任意です。省略した場合、蒸留されたフォワードパスは変更されません。
LTXで使用する、動画のようなデータ向けのTransformerモデル。
forward
< source >( 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
パラメータ
- 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) — クロスアテンションのモジュレーションパラメータを計算する際に、クロスモダリティ（動画のクロスモダリティは音声、その逆も同様）のシグマを使用するかどうかを指定します。Trueは新しい（例: LTX-2.3）動作であり、Falseは従来の LTX-2.0 の動作です。 - attention_kwargs (
dict[str, Any]、省略可) — attention プロセッサに渡すキーワード引数の任意の dict です。 - video_self_attention_mask (
torch.Tensor, 省略可) — 各 Transformer ブロックの video self-attention に適用される、形状(batch_size, num_video_tokens, num_video_tokens)の任意の乗算型 self-attention マスクです。[0, 1]の範囲の値を持ち、1は完全な attention を、0はマスク（attention の無効化）を意味します。IC-LoRA パイプラインなどで、ノイズ付きトークンと追加された参照トークンの間の attention 強度を制御するために使用されます。Audio self-attention には影響しません。 - video_keyframes_mask (
torch.Tensor, 任意) —(batch_size, num_video_tokens, 1)の形状を持つ、トークンごとの任意のマーカです。1 ピクセルフレームをエンコードする潜在フレームを持つ動画トークンに対して非ゼロになります。これらのトークンにはkeyframes_abs_pos_embeddingが適用されます。モデルがuse_keyframes_abs_pos_embeddingなしで構築された場合は無視されます。 - return_dict (
bool、任意、デフォルトはTrue) —AudioVisualModelOutput型の辞書のような構造化された出力を返すか、タプルを返すかを指定します。
戻り値
AudioVisualModelOutput または tuple
return_dict が True の場合、AudioVisualModelOutput 型の構造化された出力を返し、それ以外の場合は tuple が返されます。このとき、最初の要素はノイズ除去された動画の潜在パッチシーケンス、2番目の要素はノイズ除去された音声の潜在パッチシーケンスです。
LTX-2.0 音声・映像トランスフォーマーのフォワードパス。