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 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 đó giải mã.

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 thêm 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 (tiles) sau đó trộn 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ỉ 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, kết quả giải mã theo ô không tái tạo chính xác kết quả không theo ô; 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ã riêng lẻ.

LTX2VideoDiffusionDecoderModel