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

and get access to the augmented documentation experience

to get started

LTX2VideoTransformer3DModel

Um modelo Diffusion Transformer para dados 3D da LTX foi introduzido pela Lightricks.

O modelo pode ser carregado com o seguinte trecho de código.

from diffusers import LTX2VideoTransformer3DModel

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

LTX2VideoTransformer3DModel

classe 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 = (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 )

Parâmetros

  • in_channels (int, padrão 128) — O número de canais na entrada.
  • out_channels (int, padrão 128) — O número de canais na saída.
  • patch_size (int, padrão 1) — O tamanho dos patches espaciais a serem usados na camada de incorporação de patches.
  • patch_size_t (int, padrão 1) — O tamanho dos patches temporais a serem usados na camada de incorporação de patches.
  • num_attention_heads (int, padrão 32) — O número de cabeças a serem usadas para a atenção multi-cabeça.
  • attention_head_dim (int, padrão 64) — O número de canais em cada cabeça.
  • cross_attention_dim (int, padrão 2048 ) — O número de canais para as cabeças de atenção cruzada.
  • num_layers (int, padrão 28) — O número de blocos de camadas de Transformer a serem usados.
  • activation_fn (str, padrão "gelu-approximate") — Função de ativação a ser usada no feed-forward.
  • qk_norm (str, padrão "rms_norm_across_heads") — A camada de normalização a ser usada.
  • ff_bias (bool, padrão True) — Se as camadas lineares da camada feed-forward do vídeo incluem um termo de viés. False para LTX-2.5.
  • audio_ff_bias (bool, padrão True) — Se as camadas lineares da camada feed-forward de áudio incluem um termo de viés.
  • use_prompt_adaln_single (bool, padrão True) — Se a modulação de Key/Value da cross-attention do prompt é dependente do timestep. Quando False, usa uma tabela fixa por camada, tornando os valores de Key/Value da cross-attention cacheáveis entre as etapas de desruidamento para um prompt dado.
  • use_keyframes_abs_pos_embedding (bool, padrão False) — Se deve armazenar um embedding absoluto de posição aprendido (1, inner_dim) para tokens de keyframes gerados (LTX-2.5). Quando True, os tokens selecionados por video_keyframes_mask recebem esse embedding. O argumento é opcional; omiti-lo mantém o caminho de forward destilado inalterado.

Um modelo Transformer para dados semelhantes a vídeo usado no 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

Parâmetros

  • hidden_states (torch.Tensor) — Latentes de vídeo em patches de entrada com forma (batch_size, num_video_tokens, in_channels).
  • audio_hidden_states (torch.Tensor) — Latentes de áudio em patches de entrada com forma (batch_size, num_audio_tokens, audio_in_channels).
  • encoder_hidden_states (torch.Tensor) — Incorporações de texto de vídeo de entrada com forma (batch_size, text_seq_len, self.config.caption_channels).
  • audio_encoder_hidden_states (torch.Tensor) — Inserções de texto de áudio de entrada com forma (batch_size, text_seq_len, self.config.caption_channels).
  • timestep (torch.Tensor) — Timestep de entrada com forma (batch_size, num_video_tokens). Estes devem já ter sido escalados por self.config.timestep_scale_multiplier.
  • audio_timestep (torch.Tensor, opcional) — Timestep de entrada com forma (batch_size,) ou (batch_size, num_audio_tokens) para os parâmetros de modulação de áudio. Isso é usado apenas por determinados pipelines, como o pipeline I2V.
  • sigma (torch.Tensor, opcional) — Passo de tempo de entrada escalado, com forma (batch_size,). Usado para modulação de atenção cruzada do prompt de vídeo em modelos como LTX-2.3.
  • audio_sigma (torch.Tensor, opcional) — Timestep de entrada escalado, com forma (batch_size,). Usado para modulação de atenção cruzada de prompt de áudio em modelos como LTX-2.3. Se sigma for fornecido, mas audio_sigma não, audio_sigma será definido como o valor de sigma fornecido.
  • encoder_attention_mask (torch.Tensor, opcional) — Máscara de atenção de texto multiplicativa opcional com forma (batch_size, text_seq_len).
  • audio_encoder_attention_mask (torch.Tensor, opcional) — Máscara de atenção de texto multiplicativa opcional, de forma (batch_size, text_seq_len), para modelagem de áudio.
  • num_frames (int, opcional) — O número de quadros de vídeo latentes. Usado ao calcular as coordenadas do vídeo para o RoPE.
  • height (int, opcional) — A altura do vídeo latente. Usada ao calcular as coordenadas do vídeo para o RoPE.
  • width (int, opcional) — A largura do vídeo latente. Usada ao calcular as coordenadas do vídeo para o RoPE.
  • fps — (float, opcional, padrão 24.0): Os quadros por segundo desejados do vídeo gerado. Usado ao calcular as coordenadas do vídeo para o RoPE.
  • audio_num_frames — (int, opcional): O número de quadros de áudio latentes. Usado ao calcular as coordenadas de áudio para o RoPE.
  • video_coords (torch.Tensor, opcional) — As coordenadas do vídeo a serem usadas ao calcular os embeddings posicionais rotativos (RoPE) de forma (batch_size, 3, num_video_tokens, 2). Se não fornecidas, serão calculadas dentro de forward.
  • audio_coords (torch.Tensor, opcional) — As coordenadas de áudio a serem usadas ao calcular os embeddings posicionais rotativos (RoPE) de forma (batch_size, 1, num_audio_tokens, 2). Se não fornecidas, serão calculadas dentro de forward.
  • isolate_modalities (bool, opcional, padrão False) — Se deve isolar cada modalidade desativando a atenção cruzada entre modalidades (de áudio para vídeo e de vídeo para áudio) em todos os blocos. Use para orientação de modalidade no LTX-2.3.
  • spatio_temporal_guidance_blocks (list[int], opcional, padrão None) — Os índices dos blocos do transformer nos quais aplicar a orientação espaço-temporal (STG), que simplifica as operações de autoatenção usando diretamente os valores em vez da operação completa de atenção de produto escalar normalizado (SDPA). Se None ou vazio, a STG não será aplicada a nenhum bloco.
  • perturbation_mask (torch.Tensor, opcional) — Máscara de perturbação para STG com forma (batch_size,) ou (batch_size, 1, 1). Deve ser 0 nos elementos do lote onde o STG deve ser aplicado e 1 nos demais. Se o STG estiver sendo usado, mas perturbation_mask não for fornecido, o padrão será aplicar o STG (perturbar) todos os elementos do lote.
  • use_cross_timestep (bool opcional, padrão False) — Se deve usar o sigma da modalidade cruzada (áudio é a modalidade cruzada de vídeo, e vice-versa) ao calcular os parâmetros de modulação da atenção cruzada. True é o comportamento mais recente (ex.: LTX-2.3); False é o comportamento legado do LTX-2.0.
  • attention_kwargs (dict[str, Any], opcional) — Dicionário opcional de argumentos de palavra-chave a serem passados para o processador de atenção.
  • video_self_attention_mask (torch.Tensor, opcional) — Máscara multiplicativa opcional de autoatenção com forma (batch_size, num_video_tokens, num_video_tokens) aplicada à autoatenção de vídeo em cada bloco do transformer. Valores em [0, 1], onde 1 significa atenção total e 0 significa mascarado. Usado, por exemplo, pelo pipeline IC-LoRA para controlar a intensidade da atenção entre tokens ruidosos e tokens de referência anexados. A autoatenção de áudio não é afetada.
  • video_keyframes_mask (torch.Tensor, opcional) — Marcador opcional por token, de forma (batch_size, num_video_tokens, 1), não nulo nos tokens de vídeo cujo frame latente codifica um único frame de pixels. Esses tokens recebem keyframes_abs_pos_embedding. Ignorado quando o modelo foi construído sem use_keyframes_abs_pos_embedding.
  • return_dict (bool, opcional, padrão True) — Se deve retornar uma saída estruturada em formato de dicionário do tipo AudioVisualModelOutput ou uma tupla.

Retorna

AudioVisualModelOutput ou tuple

Se return_dict for True, retorna uma saída estruturada do tipo AudioVisualModelOutput; caso contrário, é retornada uma tuple em que o primeiro elemento é a sequência de patches latentes do vídeo dessonada e o segundo elemento é a sequência de patches latentes do áudio dessonada.

Passada para frente do transformador audiovisual de vídeo LTX-2.0.

Update on GitHub

←LongCatImageTransformer2DModel LTXVideoTransformer3DModel→