LTX2VideoDiffusionDecoderModel

Dekoder video difusi yang diperkenalkan dalam LTX-2.5 oleh Lightricks. Tahapan neighborhood-attention melakukan upsample pada latent menjadi volume konteks, dan tahap akhir melakukan denoising pada piksel yang dikondisikan pada konteks tersebut.

Ini adalah decoder, bukan autoencoder: proses encoding tetap berada di AutoencoderKLLTX2Video, yang ruang latennya dikonsumsi tanpa perubahan oleh komponen ini, sehingga latents dapat dipertukarkan antara decoder konvolusional dan decoder ini. Karena ia sendiri merupakan model difusi, ia digerakkan oleh LTX2VideoDiffusionDecodePipeline alih-alih dilewatkan sebagai vae dari sebuah pipeline: jalankan pipeline LTX-2 mana pun dengan output_type="latent", lalu lakukan decoding.

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 adalah komponen opsional pada pipeline decode: komponen ini hanya dirujuk untuk statistik laten ketika denormalize=True, dan decoder memiliki statistiknya sendiri, sehingga alur kerja yang hanya melakukan decode tidak perlu memuat autoencoder kedua.

Backend perhatian

Jendela neighborhood-attention diekspresikan sebagai BlockMask, sehingga decoder berjalan pada backend perhatian flex secara default dan tidak memerlukan dependensi tambahan. PyTorch tidak mengompilasi flex_attention kecuali Anda memintanya, dan tanpa kompilasi, matriks skor penuh akan dimaterialisasi — yang tidak praktis untuk panjang sekuens resolusi penuh. Untuk kasus tersebut, Anda dapat mengompilasi decoder atau beralih ke kernel NATTEN, yang juga digunakan oleh implementasi aslinya. Prosesor mengambil NATTEN dari Hub (shi-labs/natten) melalui paket kernels, sehingga diperlukan pip install kernels alih-alih build NATTEN lokal:

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Mengambil kode unduhan kernel dari Hub, sehingga prosesor akan memicu error ketika kode jarak jauh dinonaktifkan secara global dengan DIFFUSERS_DISABLE_REMOTE_CODE=true.

Setiap modul perhatian dalam decoder adalah neighborhood attention yang sama (perbedaan antar tahap seperti ukuran kernel ada pada modul, bukan pada processor), sehingga set_attn_processor mengganti semuanya dengan satu instance bersama.

Mengganti backend (decoder.set_attention_backend(...)) menjadi apa pun selain flex akan memicu: tidak ada backend lain yang menerima BlockMask. Gunakan pemroses NATTEN di atas sebagai gantinya.

Penyebangan

decoder.enable_tiling() melakukan dekoding pada ubin yang saling tumpang tindih, lalu menggabungkannya kembali, sehingga membatasi memori puncak berdasarkan ukuran ubin, bukan ukuran video. Tahapan upsampling awal yang murah tetap melihat latent penuh — hanya tahap upsampling terakhir dan tahap difusi, yang mendominasi memori dekoding, yang dijalankan per ubin — sehingga tiling hanya mengubah output di dekat batas ubin. Karena tahap difusi melakukan denoising pada setiap ubin secara terpisah, dekoding bertile tidak mereproduksi hasil tanpa tile secara persis; ukuran ubin dan tumpang tindih bawaan sesuai dengan implementasi referensi. Neighborhood attention menolak grid apa pun yang lebih kecil dari kernelnya, sehingga ubin sisa di akhir digabungkan ke tetangganya, bukan didekode secara mandiri.

LTX2VideoDiffusionDecoderModel