Diffusers documentation
LTX2VideoTransformer3DModel
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
< 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) — 비디오 피드포워드 레이어의 선형 레이어에 바이어 항을 포함할지 여부입니다. LTX-2.5의 경우False입니다. - audio_ff_bias (
bool, 기본값True) — 오디오 피드포워드 레이어의 선형 레이어에 바이어스 항을 포함할지 여부. - use_prompt_adaln_single (
bool, 기본값True) — 프롬프트의 cross-attention Key/Value modulation이 timestep에 의존하는지 여부입니다.False인 경우, 대신 고정된 per-layer 테이블을 사용하여 주어진 프롬프트에 대해 denoising steps 간에 cross-attention Key/Value 값을 캐시할 수 있습니다. - use_keyframes_abs_pos_embedding (
bool, 기본값False) — 생성된 keyframe 토큰에 대해 학습된(1, inner_dim)절대 위치 임베딩을 저장할지 여부입니다 (LTX-2.5).True인 경우,video_keyframes_mask에 의해 선택된 토큰이 이 임베딩을 받습니다. 이 인수는 선택 사항이며, 생략하면 증류된(forward) 경로가 변경되지 않습니다.
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)모양의 입력 패치화 비디오 잠재 변수(latents). - audio_hidden_states (
torch.Tensor) —(batch_size, num_audio_tokens, audio_in_channels)모양의 입력 패치화 오디오 잠재 변수(latents). - 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 params에 사용되는 shape이(batch_size,)또는(batch_size, num_audio_tokens)인 입력 timestep입니다. 이는 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, 선택 사항) — 오디오 모델링을 위한(batch_size, text_seq_len)형태의 선택적 곱셈 텍스트 어텐션 마스크입니다. - num_frames (
int, 선택 사항) — 잠재적 비디오 프레임의 수입니다. RoPE를 위한 비디오 좌표를 계산할 때 사용됩니다. - height (
int, 선택 사항) — 잠재 영상(latent video)의 높이입니다. RoPE를 위해 영상 좌표를 계산할 때 사용됩니다. - width (
int, 선택 사항) — 잠재 영상(latent video)의 너비입니다. 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는 전체 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선택 사항, 기본값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에 적용되는 shape이(batch_size, num_video_tokens, num_video_tokens)인 선택적 곱셈 self-attention 마스크입니다.[0, 1]범위의 값으로,1은 완전한 attention을,0은 masked를 의미합니다. 예를 들어 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 유사 구조화 출력인지, 아니면 tuple인지 여부를 결정합니다.
반환값
AudioVisualModelOutput 또는 tuple
return_dict가 True인 경우 AudioVisualModelOutput 유형의 구조화된 출력을 반환하고, 그렇지 않으면 첫 번째 요소가 노이즈가 제거된 비디오 잠재 변수 패치 시퀀스이고 두 번째 요소가 노이즈가 제거된 오디오 잠재 변수 패치 시퀀스인 tuple을 반환합니다.
LTX-2.0 오디오비주얼 비디오 트랜스포머의 포워드 패스.