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

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.

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

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

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

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

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)

Источник

Диффузионный декодер видео LTX-2, представленный в LTX-2.5.

Это декодер, а не автоэнкодер: у него нет энкодера, и он не может генерировать латенты. Кодирование остаётся за AutoencoderKLLTX2Video, пространство латентов которого этот декодер использует без изменений, поэтому латенты взаимозаменяемы между свёрточным декодером и этим.

Это также диффузионная модель, а не детерминированный декодер — она выполняет денуазинг пикселей с условием на контекстный объём, построенный из латентов, — именно поэтому она управляется через LTX2VideoDiffusionDecodePipeline, а не передаётся как vae пайплайна.

Статистика латентных переменных передаётся здесь в виде буферов, чтобы конвейер декодирования мог денормализовать данные без загрузки второго автоэнкодера только ради двух векторов.

Эта модель наследуется от ModelMixin. См. документацию суперкласса для его универсальных методов, реализованных для всех моделей (например, загрузка или сохранение).

decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

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

Источник

Декодировать пакет латентов.

Ожидается, что z уже денормализован (пайплайн применяет latents_mean / latents_std), что соответствует AutoencoderKLLTX2Video. Этот декодер выполняет шумоподавление, поэтому для воспроизводимости передайте generator.

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)

Источник

Параметры:

tile_sample_min_height (int, optional) : Высота одного декодированного тайла в пикселях.

tile_sample_min_width (int, optional) : Ширина одного декодированного тайла в пикселях.

tile_sample_min_num_frames (int, необязательный) : Количество кадров одного декодированного тайла.

tile_sample_stride_height (int, optional) : расстояние в пикселях между верхними краями двух последовательных вертикальных тайлов; разница с tile_sample_min_height составляет область перекрытия с плавным смешиванием.

tile_sample_stride_width (int, optional) : Расстояние в пикселях между левыми краями двух последовательных горизонтальных тайлов.

tile_sample_stride_num_frames (int, optional) : Расстояние в кадрах между началом двух последовательных временных тайлов.

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

disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

disable_tiling()

Источник

Отключите тайловое декодирование, чтобы вернуться к декодированию всего видео за один проход.

forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

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

Источник

Параметры:

z (torch.Tensor) : Латенты формы (B, C, F, H, W), ожидаемо уже денормализованные (пайплайн применяет latents_mean / latents_std), соответствующие AutoencoderKLLTX2Video.

generator (torch.Generator, необязательный) : Этот декодер выполняет шумоподавление, поэтому передайте генератор, чтобы сделать декодирование воспроизводимым.

num_inference_steps (int, optional) : Количество шагов денойзинга. По умолчанию используется значение конфигурации decoder_num_inference_steps декодера.

return_dict (bool, необязательный, по умолчанию True) : Нужно ли возвращать DecoderOutput вместо обычного кортежа.

Возвращает: DecoderOutput или tuple

tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

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

Источник

Декодировать пакет латентов с использованием последнего детерминированного этапа и этапа диффузии, выполняемого по тайлам.

Tiles размещаются на сетке, входящей в последний детерминированный этап, где одна ячейка соответствует фиксированному блоку выходных пикселей; размеры tile_sample_* преобразуются в эту сетку, поэтому они должны быть кратны размеру ячейки (8 пикселей пространственно и 2 кадра временно для производной конфигурации). Временные тайлы следуют причинному отображению кадров: тайл, содержащий t=0, отбрасывает дублирующий начальный кадр временного апсемплинга, а только тайл, содержащий конец видео, несёт пограничную отсечку NATTEN.