# 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](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_ltx_2#diffusers.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](/docs/diffusers/v0.43.0/id/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) alih-alih dilewatkan sebagai `vae` dari sebuah pipeline: jalankan pipeline LTX-2 mana pun dengan `output_type="latent"`, lalu lakukan decoding.

```python
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](https://github.com/SHI-Labs/NATTEN), yang juga digunakan oleh implementasi aslinya. Prosesor mengambil NATTEN dari Hub ([`shi-labs/natten`](https://huggingface.co/shi-labs/natten)) melalui paket [`kernels`](https://github.com/huggingface/kernels), sehingga diperlukan `pip install kernels` alih-alih build NATTEN lokal:

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

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L700)

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](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_ltx_2#diffusers.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](/docs/diffusers/v0.43.0/id/api/pipelines/ltx2#diffusers.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](/docs/diffusers/v0.43.0/id/api/models/overview#diffusers.ModelMixin). Periksa dokumentasi kelas induk untuk metode generiknya yang diimplementasikan untuk semua model (seperti mengunduh atau menyimpan).

#### decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L988)

Decode sebuah batch latents.

`z` diharapkan sudah dinormalisasi (pipeline menerapkan `latents_mean` / `latents_std`), sesuai dengan [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video). Decoder ini melakukan denoising, jadi berikan `generator` untuk reproduktibilitas.

#### enable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.enable_tiling]]

```python
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](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L787)

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

```python
disable_tiling()
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L824)

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

#### forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L1017)

**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](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_ltx_2#diffusers.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](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) alih-alih tuple biasa.

**Mengembalikan:** [DecoderOutput](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) atau `tuple`

#### tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L855)

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.