# LTX2VideoDiffusionDecoderModel

Bộ giải mã video khuếch tán được giới thiệu trong LTX-2.5 bởi Lightricks. Các giai đoạn chú ý lân cận (neighborhood-attention) sẽ tăng mẫu (upsample) ẩn (latent) thành một thể tích ngữ cảnh (context volume), và giai đoạn cuối cùng sẽ khử nhiễu (denoise) các pixel dựa trên ngữ cảnh đó.

Đây là một decoder, không phải autoencoder: quá trình encoding vẫn thuộc về [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), không gian latent mà thành phần này sử dụng không bị thay đổi, do đó các latent có thể hoán đổi giữa decoder convolutional và decoder này. Vì bản thân nó là một mô hình diffusion, nó được điều khiển bởi [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) thay vì được truyền vào như `vae` của một pipeline: chạy bất kỳ pipeline LTX-2 nào với `output_type="latent"`, sau đó tiến hành decode.

```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` là một thành phần tùy chọn trong pipeline giải mã: nó chỉ được tham khảo để lấy thống kê latent khi `denormalize=True`, và bộ giải mã tự mang theo thống kê của riêng mình, nên một workflow chỉ giải mã không cần phải nạp một autoencoder thứ hai.

## Các backend chú ý

Cửa sổ neighborhood-attention được biểu diễn dưới dạng `BlockMask`, do đó decoder chạy trên backend attention `flex` theo mặc định và không cần phụ thuộc bổ sung. PyTorch không biên dịch `flex_attention` trừ khi bạn yêu cầu, và khi chưa được biên dịch, nó sẽ tạo ra ma trận điểm số đầy đủ — điều này không thực tế với độ dài chuỗi ở độ phân giải đầy đủ. Đối với các trường hợp đó, hãy biên dịch decoder hoặc chuyển sang các kernel của [NATTEN](https://github.com/SHI-Labs/NATTEN), đây cũng là những gì bản triển khai gốc sử dụng. Processor lấy NATTEN từ Hub ([`shi-labs/natten`](https://huggingface.co/shi-labs/natten)) thông qua gói [`kernels`](https://github.com/huggingface/kernels), vì vậy nó cần `pip install kernels` thay vì một bản build NATTEN cục bộ:

```python
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
```

Việc tải mã tải xuống kernel từ Hub, do đó bộ xử lý sẽ gây ra lỗi khi mã từ xa bị vô hiệu hóa toàn cục với `DIFFUSERS_DISABLE_REMOTE_CODE=true`.

Mọi module attention trong decoder đều là cùng một neighborhood attention (các khác biệt theo giai đoạn như kích thước kernel nằm trên module, không phải trên processor), do đó `set_attn_processor` thay thế tất cả chúng bằng một instance dùng chung.

Việc chuyển *backend* (`decoder.set_attention_backend(...)`) sang bất kỳ giá trị nào khác ngoài `flex` sẽ gây ra lỗi: không có backend nào khác chấp nhận `BlockMask`. Hãy sử dụng bộ xử lý NATTEN ở trên thay thế.

## Gom lát

`decoder.enable_tiling()` giải mã theo các ô chồng lấn (overlapping tiles) sau đó trộn chúng lại với nhau, nhờ đó giới hạn bộ nhớ đỉnh theo kích thước ô thay vì kích thước video. Các giai đoạn tăng mẫu sớm, có chi phí thấp, vẫn nhìn thấy toàn bộ latent — chỉ có giai đoạn tăng mẫu cuối cùng và giai đoạn khuếch tán, vốn chiếm phần lớn bộ nhớ giải mã, mới chạy theo từng ô — do đó tiling chỉ làm thay đổi kết quả ở gần biên của các ô. Vì giai đoạn khuếch tán khử nhiễu từng ô riêng biệt, một lần giải mã có tiling sẽ không tái tạo chính xác kết quả không tiling; kích thước ô và mức chồng lấn mặc định khớp với cài đặt của bản tham chiếu. Cơ chế chú ý lân cận (neighborhood attention) từ chối bất kỳ lưới nào nhỏ hơn nhân (kernel) của nó, nên một ô phần dư ở cuối sẽ được gộp vào ô lân cận thay vì được giải mã độc lập.

## 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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L700)

Bộ giải mã video khuếch tán LTX-2, được giới thiệu trong LTX-2.5.

Đây là một decoder, không phải autoencoder: nó không có encoder và không thể tạo ra latents. Việc encoding vẫn do [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video) đảm nhận, không gian latent mà nó tạo ra được sử dụng nguyên vẹn ở đây, do đó latents có thể hoán đổi giữa decoder convolutional và decoder này.

Đây cũng là một mô hình khuếch tán chứ không phải là bộ giải mã tất định — nó khử nhiễu các pixel có điều kiện dựa trên một thể tích ngữ cảnh được xây dựng từ các ẩn (latents) — đó là lý do tại sao nó được điều khiển bởi [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) thay vì được truyền vào như `vae` của một pipeline.

Các thống kê ẩn được giữ ở đây dưới dạng buffer để pipeline giải mã có thể khử chuẩn hóa mà không cần tải một autoencoder thứ hai chỉ cho hai vector.

Mô hình này kế thừa từ [ModelMixin](/docs/diffusers/v0.43.0/vi/api/models/overview#diffusers.ModelMixin). Hãy xem tài liệu của lớp cha để biết các phương thức chung được triển khai cho tất cả các mô hình (chẳng hạn như tải xuống hoặc lưu trữ).

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

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

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

Giải mã một lô latents.

`z` được kỳ vọng đã được chuẩn hóa ngược (pipeline áp dụng `latents_mean` / `latents_std`), khớp với [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video). Bộ giải mã này khử nhiễu, vì vậy hãy truyền `generator` để đảm bảo khả năng tái lập.

#### 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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L787)

**Tham số:**

tile_sample_min_height (`int`, *tuỳ chọn*) : Chiều cao của một ô đã giải mã, tính bằng pixel.

tile_sample_min_width (`int`, *tuỳ chọn*) : Độ rộng của một ô đã giải mã, tính bằng pixel.

tile_sample_min_num_frames (`int`, *tuỳ chọn*) : Số khung hình của một ô đã giải mã.

tile_sample_stride_height (`int`, *optional*) : Khoảng cách tính bằng pixel giữa phần trên của hai gạch dọc liên tiếp; phần chênh lệch so với `tile_sample_min_height` là vùng chồng lấn được trộn.

tile_sample_stride_width (`int`, *optional*) : Khoảng cách tính bằng pixel giữa các cạnh trái của hai gạch ngang liên tiếp.

tile_sample_stride_num_frames (`int`, *optional*) : Khoảng cách tính bằng số khung hình giữa điểm bắt đầu của hai lát cắt thời gian liên tiếp.

Bật giải mã dạng gạch (tiled decoding). Các giai đoạn lấy mẫu lên (upsampling) tất định trước giai đoạn cuối luôn xử lý toàn bộ latent (chúng chạy ở độ phân giải thấp và có chi phí thấp); giai đoạn cuối và các khối khuếch tán (diffusion blocks) của giai đoạn 5 — những thành phần chiếm phần lớn bộ nhớ khi giải mã — sẽ chạy trên các gạch chồng lấn, với các đường nối được trộn tuyến tính.

#### disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

```python
disable_tiling()
```

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

Tắt giải mã dạng gạch, quay lại giải mã toàn bộ video trong một lần duy nhất.

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

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

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

**Tham số:**

z (`torch.Tensor`) : Latents có shape `(B, C, F, H, W)`, được kỳ vọng đã được chuẩn hóa ngược (pipeline áp dụng `latents_mean` / `latents_std`), khớp với [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video).

generator (`torch.Generator`, *tùy chọn*) : Bộ giải mã này khử nhiễu, vì vậy hãy truyền một generator để đảm bảo quá trình giải mã có thể tái lập được.

num_inference_steps (`int`, *optional*) : Số bước khử nhiễu. Mặc định là giá trị cấu hình `decoder_num_inference_steps` của bộ giải mã.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một [DecoderOutput](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) thay vì một tuple thông thường hay không.

**Trả về:** [DecoderOutput](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) hoặc `tuple`

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

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

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

Giải mã một lô latents bằng giai đoạn cuối mang tính tất định và giai đoạn khuếch tán chạy theo từng ô.

Tiles nằm trên lưới đi vào giai đoạn cuối mang tính tất định, trong đó một cell ánh xạ tới một khối pixel đầu ra cố định; các kích thước `tile_sample_*` được chuyển đổi sang lưới đó, do đó chúng nên là bội số của kích thước cell (8 px theo không gian và 2 khung hình theo thời gian cho cấu hình production). Các tile thời gian tuân theo ánh xạ khung hình nhân quả: tile chứa t=0 sẽ loại bỏ khung hình đầu bị nhân đôi do upsample thời gian, và chỉ tile chứa điểm kết thúc của video mới mang padding biên NATTEN.