diffusers/main/ko/api/models/ltx2_video_transformer3d.md

LTX2VideoTransformer3DModel

LTX에서 3D 데이터를 위한 Diffusion Transformer 모델이 Lightricks에 의해 소개되었습니다.

다음 코드 스니펫으로 모델을 로드할 수 있습니다.

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

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

소스

매개변수:

in_channels (int, 기본값 128) : 입력의 채널 수.

out_channels (int, 기본값 128) : 출력의 채널 수.

patch_size (int, 기본값 1) : 패치 임베딩 레이어에서 사용할 공간 패치의 크기입니다.

patch_size_t (int, 기본값 1) : 패치 임베딩 레이어에서 사용할 시간적 패치의 크기입니다.

num_attention_heads (int, 기본값 32) : multi-head attention에 사용할 헤드 수입니다.

attention_head_dim (int, 기본값 64) : 각 헤드(head)의 채널 수.

cross_attention_dim (int, 기본값 2048 ) : cross attention heads의 채널 수입니다.

num_layers (int, 기본값 28) : 사용할 Transformer 블록의 레이어 수입니다.

activation_fn (str, 기본값 "gelu-approximate") : feed-forward에서 사용할 활성화 함수입니다.

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) : 생성된 keyframe 토큰에 대해 학습된 (1, inner_dim) 절대 위치 임베딩을 저장할지 여부(LTX-2.5). True인 경우, video_keyframes_mask에 의해 선택된 토큰이 이 임베딩을 받습니다. 이 인수는 선택 사항이며, 생략하면 증류된(forward) 경로가 변경되지 않습니다.

LTX에서 사용되는 비디오 유사 데이터용 Transformer 모델입니다.

forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

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)

소스

매개변수:

hidden_states (torch.Tensor) : (batch_size, num_video_tokens, in_channels) 모양의 입력 패치화 비디오 잠재 변수(latents).

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) 형태의 입력 timestep입니다. 이는 이미 self.config.timestep_scale_multiplier로 스케일링되어 있어야 합니다.

audio_timestep (torch.Tensor, 선택 사항) : 오디오 modulation 파라미터를 위한 입력 timestep으로, 형태는 (batch_size,) 또는 (batch_size, num_audio_tokens)입니다. 이는 I2V pipeline과 같은 특정 pipeline에서만 사용됩니다.

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, 선택 사항) : 오디오 모델링을 위한 shape가 (batch_size, text_seq_len)인 선택적 곱셈 텍스트 어텐션 마스크입니다.

num_frames (int, 선택 사항) : 잠재적(latent) 비디오 프레임의 수입니다. RoPE를 위한 비디오 좌표를 계산할 때 사용됩니다.

height (int, 선택 사항) : 잠재 영상(latent video)의 높이입니다. RoPE를 위한 영상 좌표를 계산할 때 사용됩니다.

width (int, 선택 사항) : 잠재 비디오의 너비입니다. RoPE를 위해 비디오 좌표를 계산할 때 사용됩니다.

fps : (float, 선택 사항, 기본값 24.0): 생성된 비디오의 원하는 초당 프레임 수입니다. RoPE를 위해 비디오 좌표를 계산하는 경우 사용됩니다.

audio_num_frames : (int, 선택 사항): 잠재 오디오 프레임의 수입니다. RoPE를 위한 오디오 좌표를 계산할 때 사용됩니다.

video_coords (torch.Tensor, 선택 사항) : (batch_size, 3, num_video_tokens, 2) 모양의 회전 위치 임베딩(RoPE)을 계산할 때 사용할 비디오 좌표입니다. 제공되지 않으면 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는 전체 scaled dot-product attention(SDPA) 연산 대신 값만 사용하여 self-attention 연산을 단축합니다. None이거나 비어 있으면 어떤 블록에도 STG가 적용되지 않습니다.

perturbation_mask (torch.Tensor, 선택 사항) : (batch_size,) 또는 (batch_size, 1, 1) 모양의 STG용 Perturbation mask입니다. STG를 적용해야 하는 배치 요소에서는 0, 그 외에는 1이어야 합니다. STG를 사용 중이지만 perturbation_mask가 제공되지 않으면, 기본적으로 모든 배치 요소에 STG(교란)를 적용합니다.

use_cross_timestep (bool optional, 기본값 False) : 크로스 어텐션 모듈레이션 매개변수를 계산할 때 크로스 모달리티(오디오는 비디오의 크로스 모달리티이며, 그 반대도 성립) 시그마를 사용할지 여부입니다. True는 더 새로운(예: LTX-2.3) 동작이며, False는 기존 LTX-2.0 동작입니다.

attention_kwargs (dict[str, Any], 선택 사항) : attention processor에 전달할 키워드 인수의 선택적 dict입니다.

video_self_attention_mask (torch.Tensor, 선택 사항) : 각 transformer 블록의 비디오 self-attention에 적용되는, (batch_size, num_video_tokens, num_video_tokens) 형태의 선택적 곱셈 self-attention 마스크입니다. [0, 1] 범위의 값으로, 1은 완전한 attention을, 0은 masking을 의미합니다. 예를 들어 IC-LoRA 파이프라인에서 노이즈 토큰과 추가된 참조 토큰 간의 attention 강도를 제어하는 데 사용됩니다. 오디오 self-attention에는 영향을 미치지 않습니다.

video_keyframes_mask (torch.Tensor, 선택 사항) : (batch_size, num_video_tokens, 1) 모양의 선택적 토큰별 마커입니다. 하나의 픽셀 프레임을 인코딩하는 잠재 프레임에 해당하는 비디오 토큰에서 0이 아닌 값을 가집니다. 이러한 토큰은 keyframes_abs_pos_embedding을 받습니다. 모델이 use_keyframes_abs_pos_embedding 없이 빌드된 경우 무시됩니다.

return_dict (bool, 선택 사항, 기본값 True) : AudioVisualModelOutput 유형의 dict 유사 구조화 출력인지, 튜플인지 여부를 결정합니다.

반환값: AudioVisualModelOutput 또는 tuple

return_dict가 True인 경우 AudioVisualModelOutput 유형의 구조화된 출력을 반환하고, 그렇지 않으면 첫 번째 요소가 노이즈가 제거된 비디오 잠재 변수 패치 시퀀스, 두 번째 요소가 노이즈가 제거된 오디오 잠재 변수 패치 시퀀스인 tuple을 반환합니다.

LTX-2.0 오디오비주얼 비디오 트랜스포머의 포워드 패스.