# LTX2VideoDiffusionDecoderModel

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

Это декодер, а не автоэнкодер: кодирование остаётся за [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), чьё латентное пространство используется здесь без изменений, поэтому латенты взаимозаменяемы между свёрточным декодером и этим. Поскольку сам по себе это диффузионная модель, она управляется [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline), а не передаётся как `vae` пайплайна: запустите любой пайплайн LTX-2 с `output_type="latent"`, а затем декодируйте.

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

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

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

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L700)

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

Это декодер, а не автоэнкодер: у него нет энкодера, и он не может генерировать латенты. Кодирование остаётся за [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), пространство латентов которого этот декодер использует без изменений, поэтому латенты взаимозаменяемы между свёрточным декодером и этим.

Это также диффузионная модель, а не детерминированный декодер — она выполняет денуазинг пикселей с условием на контекстный объём, построенный из латентов, — именно поэтому она управляется через [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline), а не передаётся как `vae` пайплайна.

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

Эта модель наследуется от [ModelMixin](/docs/diffusers/v0.43.0/ru/api/models/overview#diffusers.ModelMixin). См. документацию суперкласса для его универсальных методов, реализованных для всех моделей (например, загрузка или сохранение).

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L988)

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

Ожидается, что `z` уже денормализован (пайплайн применяет `latents_mean` / `latents_std`), что соответствует [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video). Этот декодер выполняет шумоподавление, поэтому для воспроизводимости передайте `generator`.

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L787)

**Параметры:**

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

```python
disable_tiling()
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L824)

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

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L1017)

**Параметры:**

z (`torch.Tensor`) : Латенты формы `(B, C, F, H, W)`, ожидаемо уже денормализованные (пайплайн применяет `latents_mean` / `latents_std`), соответствующие [AutoencoderKLLTX2Video](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video).

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

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

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Нужно ли возвращать [DecoderOutput](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) вместо обычного кортежа.

**Возвращает:** [DecoderOutput](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) или `tuple`

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/ltx2_diffusion_decoder.py#L855)

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

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