diffusers/main/id/api/models/ltx2_diffusion_decoder.md

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 decoder 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 dari 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 berada di modul, bukan di 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 alih-alih didekode secara mandiri.

LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

diffusers.LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

diffusers.LTX2VideoDiffusionDecoderModel(out_channels: int = 3, latent_channels: int = 128, patch_size: int = 4, scaling_factor: float = 1.0, decoder_head_dim: int = 64, decoder_stage_channels: tuple[int, ...] = (2048, 1024, 512, 512, 256), decoder_stage_depths: tuple[int, ...] = (4, 6, 4, 2, 8), decoder_stage_kernels: tuple[tuple[int, int, int], ...] = ((3, 7, 7), (3, 7, 7), (3, 5, 5), (3, 5, 5)), decoder_upsample_strides: tuple[tuple[int, int, int], ...] = ((1, 2, 2), (2, 1, 1), (2, 2, 2), (2, 2, 2)), decoder_upsample_channel_reductions: tuple[int, ...] = (2, 2, 1, 2), decoder_stage5_kernel: tuple[int, int, int] = (11, 11, 11), decoder_t_emb_dim: int = 384, decoder_timestep_scale_multiplier: float = 1000.0, decoder_model_output_type: str = 'x0', decoder_num_inference_steps: int = 1, spatial_compression_ratio: int = 32, temporal_compression_ratio: int = 8)

Sumber

Dekoder video difusi LTX-2, yang diperkenalkan dalam LTX-2.5.

Ini adalah decoder, bukan autoencoder: tidak memiliki encoder dan tidak dapat menghasilkan latents. Encoding tetap berada di AutoencoderKLLTX2Video, yang ruang latennya dikonsumsi tanpa perubahan oleh decoder ini, sehingga latents dapat dipertukarkan antara decoder konvolusional dan decoder ini.

Ini juga merupakan model difusi, bukan decoder deterministik — model ini melakukan denoising pada piksel yang dikondisikan pada volume konteks yang dibangun dari latents — itulah mengapa model ini dijalankan oleh LTX2VideoDiffusionDecodePipeline alih-alih diteruskan sebagai vae dari sebuah pipeline.

Statistik laten dibawa di sini sebagai buffer sehingga pipeline decode dapat menormalisasi ulang tanpa memuat autoencoder kedua hanya untuk dua vektor.

Model ini mewarisi dari ModelMixin. Periksa dokumentasi kelas induk untuk metode generiknya yang diimplementasikan untuk semua model (seperti mengunduh atau menyimpan).

decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)

Sumber

Decode sebuah batch latents.

z diharapkan sudah dinormalisasi (pipeline menerapkan latents_mean / latents_std), sesuai dengan AutoencoderKLLTX2Video. Decoder ini melakukan denoising, jadi berikan generator untuk reproduktibilitas.

enable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.enable_tiling]]

enable_tiling(tile_sample_min_height: int | None = None, tile_sample_min_width: int | None = None, tile_sample_min_num_frames: int | None = None, tile_sample_stride_height: int | None = None, tile_sample_stride_width: int | None = None, tile_sample_stride_num_frames: int | None = None)

Sumber

Parameter:

tile_sample_min_height (int, opsional) : Tinggi satu tile yang didekode, dalam piksel.

tile_sample_min_width (int, opsional) : Lebar satu tile yang didekode, dalam piksel.

tile_sample_min_num_frames (int, opsional) : Jumlah frame dari satu tile yang didekode.

tile_sample_stride_height (int, opsional) : Jarak dalam piksel antara bagian atas dua ubin vertikal yang berurutan; selisihnya dengan tile_sample_min_height adalah tumpang tindih yang dicampur.

tile_sample_stride_width (int, opsional) : Jarak dalam piksel antara tepi kiri dua ubin horizontal yang berurutan.

tile_sample_stride_num_frames (int, opsional) : Jarak dalam frame antara awal dua ubin temporal yang berurutan.

Aktifkan decoding bertile. Tahapan upsampling deterministik sebelum tahap terakhir selalu memproses latent penuh (mereka berjalan pada resolusi rendah dan murah); tahap terakhir dan blok difusi tahap-5 — yang mendominasi memori decoding — berjalan pada tile yang tumpang tindih dengan sambungan yang dicampur secara linear.

disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

disable_tiling()

Sumber

Nonaktifkan decoding bertile, kembali ke decoding seluruh video dalam satu kali proses.

forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

forward(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)

Sumber

Parameter:

z (torch.Tensor) : Latents dengan bentuk (B, C, F, H, W), yang diharapkan sudah dinormalisasi (pipeline menerapkan latents_mean / latents_std), sesuai dengan AutoencoderKLLTX2Video.

generator (torch.Generator, opsional) : Decoder ini melakukan denoising, jadi berikan generator untuk membuat proses decoding dapat direproduksi.

num_inference_steps (int, opsional) : Jumlah langkah denoising. Bawaan ke nilai konfigurasi decoder_num_inference_steps dari decoder.

return_dict (bool, opsional, defaultnya True) : Apakah akan mengembalikan DecoderOutput alih-alih tuple biasa.

Mengembalikan: DecoderOutput atau tuple

tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

tiled_decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None)

Sumber

Decode batch latents dengan tahap deterministik terakhir dan tahap difusi yang berjalan per tile.

Tiles berada di grid yang memasuki tahap deterministik terakhir, di mana satu sel memetakan ke blok piksel output yang tetap; ukuran tile_sample_* dikonversi ke grid tersebut, sehingga seharusnya merupakan kelipatan dari ukuran sel (8 px secara spasial dan 2 frame secara temporal untuk konfigurasi produksi). Tile temporal mengikuti pemetaan frame kausal: tile yang berisi t=0 membuang frame awal duplikat dari upsample temporal, dan hanya tile yang berisi akhir video yang membawa padding border NATTEN.