LTX2VideoDiffusionDecoderModel

Lightricks의 LTX-2.5에서 도입된 diffusion video decoder입니다. Neighborhood-attention 단계는 latent를 context volume으로 upsample하고, 최종 단계는 해당 context에 조건부으로 픽셀의 노이즈를 제거합니다.

이것은 오토인코더가 아닌 디코더입니다. 인코딩은 AutoencoderKLLTX2Video에 남아 있으며, 이 모델은 해당 모델의 잠재 공간(latent space)을 그대로 소비하므로, 컨볼루션 디코더와 이 디코더 간에 잠재 변수(latents)를 상호 교환할 수 있습니다. 이 모델 자체가 확산 모델(diffusion model)이므로, 파이프라인의 vae로 전달되는 대신 LTX2VideoDiffusionDecodePipeline에 의해 구동됩니다. output_type="latent"로 LTX-2 파이프라인을 실행한 후 디코딩하면 됩니다.

import torch
from diffusers import LTX2Pipeline, LTX2VideoDiffusionDecodePipeline, LTX2VideoDiffusionDecoderModel

pipe = LTX2Pipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
latents = pipe(prompt="a potter shaping a clay vase", output_type="latent").frames

decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
    "Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
).to("cuda")
decode_pipe = LTX2VideoDiffusionDecodePipeline(diffusion_decoder=decoder, scheduler=pipe.scheduler)

# `denormalize=False`: `output_type="latent"` already applied the latent statistics, so applying them
# again here would scale every channel by its std a second time.
# The decoder also draws the noise it denoises, so decoding is only reproducible with a generator.
video = decode_pipe(
    latents, generator=torch.Generator("cuda").manual_seed(0), denormalize=False
).frames[0]

vae는 디코딩 파이프라인의 선택적 구성 요소입니다. denormalize=True인 경우에만 잠재 통계에 대해 참조되며, 디코더는 자체적으로 이를 보유하고 있으므로 디코딩 전용 워크플로에서는 두 번째 오토인코더를 로드할 필요가 없습니다.

Attention 백엔드

neighborhood-attention 윈도우는 BlockMask로 표현되므로, 디코더는 기본적으로 flex attention 백엔드에서 실행되며 추가적인 의존성이 필요하지 않습니다. PyTorch는 명시적으로 요청하지 않는 한 flex_attention을 컴파일하지 않으며, 컴파일되지 않은 상태에서는 전체 score matrix를 materialize합니다. 이는 full-resolution 시퀀스 길이에서는 비현실적입니다. 이러한 경우, 디코더를 컴파일하거나 원래 구현에서도 사용하는 NATTEN의 커널로 전환할 수 있습니다. 프로세서가 kernels 패키지를 통해 Hub(shi-labs/natten)에서 NATTEN을 가져오므로, 로컬 NATTEN 빌드 대신 pip install kernels가 필요합니다:

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Hub에서 커널 다운로드 코드를 가져오므로, DIFFUSERS_DISABLE_REMOTE_CODE=true로 원격 코드가 전역적으로 비활성화된 경우 프로세서가 예외를 발생시킵니다.

디코더의 모든 attention 모듈은 동일한 neighborhood attention입니다(커널 크기 같은 단계별 차이는 프로세서가 아닌 모듈에 존재하므로), set_attn_processor는 이를 하나의 공유 인스턴스로 모두 교체합니다.

flex가 아닌 다른 backend로 변경하면(decoder.set_attention_backend(...)) BlockMask를 다른 어떤 backend도 지원하지 않으므로 예외가 발생합니다. 대신 위의 NATTEN 프로세서를 사용하세요.

타일링

decoder.enable_tiling()는 오버랩되는 타일 단위로 디코딩한 뒤 이를 블렌딩하여 결합하며, 피크 메모리를 비디오 크기가 아닌 타일 크기로 제한합니다. 비용이 낮은 초기 업샘플링 단계는 여전히 전체 latent를 확인하지만, 디코딩 메모리를 지배하는 마지막 업샘플링 단계와 diffusion 단계만 타일별로 실행되므로 타일링은 타일 경계 근처에서만 출력을 변경합니다. diffusion 단계가 각 타일을 개별적으로 디노이즈하기 때문에 타일링된 디코딩은 타일링되지 않은 결과를 정확히 재현하지 않으며, 기본 타일 및 오버랩 크기는 참조 구현과 일치합니다. Neighborhood attention은 커널보다 작은 그리드를 거부하므로, 끝부분의 잔여 타일은 단독으로 디코딩되지 않고 이웃 타일에 병합됩니다.

LTX2VideoDiffusionDecoderModel