LTX2VideoDiffusionDecoderModel

Диффузионный декодер видео, представленный в LTX-2.5 от Lightricks. Стадии neighborhood-attention повышают разрешение латентного представления до контекстного объёма, а финальная стадия снимает шум с пикселей, используя этот контекст в качестве условия.

Это декодер, а не автоэнкодер: кодирование остаётся за AutoencoderKLLTX2Video, чьё латентное пространство здесь используется без изменений, поэтому латенты взаимозаменяемы между свёрточным декодером и этим. Поскольку сам по себе это диффузионная модель, она управляется LTX2VideoDiffusionDecodePipeline, а не передаётся как vae пайплайна: запустите любой пайплайн LTX-2 с output_type="latent", а затем декодируйте.

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 — необязательный компонент конвейера декодирования: он используется только для получения латентных статистик, когда denormalize=True, а декодер хранит их самостоятельно, поэтому в сценарии, где выполняется только декодирование, не требуется загружать второй автоэнкодер.

Бэкенды внимания

Окно neighborhood-attention представлено в виде BlockMask, поэтому декодер по умолчанию работает на бэкенде внимания flex и не требует дополнительных зависимостей. PyTorch не компилирует flex_attention, если вы явно не запросите этого, а без компиляции материализуется полная матрица скоростей, что непрактично для последовательностей полной разрешающей способности. Для таких случаев необходимо либо скомпилировать декодер, либо переключиться на ядра NATTEN, которые также используются в исходной реализации. Процессор загружает NATTEN из Hub (shi-labs/natten) через пакет kernels, поэтому требуется pip install kernels, а не локальная сборка NATTEN:

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Загрузка кода для скачивания ядра с Hub, поэтому процессор вызывает ошибку, если удалённый код глобально отключён с помощью DIFFUSERS_DISABLE_REMOTE_CODE=true.

Каждый модуль внимания в декодере представляет собой одно и то же neighborhood attention (различия между этапами, такие как размер ядра, задаются на уровне модуля, а не процессора), поэтому set_attn_processor заменяет их все одним общим экземпляром.

Переключение бэкенда (decoder.set_attention_backend(...)) на что-либо, кроме flex, приводит к ошибке: ни один другой бэкенд не принимает BlockMask. Вместо этого используйте процессор NATTEN, описанный выше.

Плиточная обработка

decoder.enable_tiling() выполняет декодирование в перекрывающихся тайлах, которые затем смешиваются обратно, ограничивая пиковое потребление памяти размером тайла, а не размером видео. Дешёвые начальные этапы апсемплинга по-прежнему обрабатывают полный латентный вектор — только последний этап апсемплинга и этап диффузии, которые определяют потребление памяти при декодировании, выполняются для каждого тайла — поэтому тайлинг изменяет результат только вблизи границ тайлов. Поскольку на этапе диффузии шум удаляется для каждого тайла отдельно, декодирование с тайлингом не воспроизводит результат без тайлинга точно; размеры тайла и перекрытия по умолчанию соответствуют эталонной реализации. Внимательность к окрестности отклоняет любую сетку, меньшую, чем её ядро, поэтому оставшийся хвостовой тайл объединяется с соседним, а не декодируется самостоятельно.

LTX2VideoDiffusionDecoderModel