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

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, 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 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.

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, đâ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) thông qua gói kernels, vì vậy nó cần pip install kernels thay vì một bản build NATTEN cục bộ:

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

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

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 đả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 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. 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]]

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

Nguồn

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

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

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

disable_tiling()

Nguồn

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

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

Nguồn

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.

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 thay vì một tuple thông thường hay không.

Trả về: DecoderOutput hoặc tuple

tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

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

Nguồn

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.