# AutoencoderKL

Модель вариационного автоэнкодера (VAE) с потерей KL была представлена в статье [Auto-Encoding Variational Bayes](https://huggingface.co/papers/1312.6114v11) Дидериком П. Кингмой и Максом Веллингом. В 🤗 Diffusers эта модель используется для кодирования изображений в латентные представления и декодирования латентных представлений в изображения.

Аннотация из статьи:

*Как выполнить эффективный вывод и обучение в направленных вероятностных моделях при наличии непрерывных латентных переменных с неразрешимыми апостериорными распределениями и большими наборами данных? Мы предлагаем стохастический алгоритм вариационного вывода и обучения, масштабируемый на большие наборы данных и, при некоторых мягких условиях дифференцируемости, работающий даже в неразрешимом случае. Наши вклады двояки. Во-первых, мы показываем, что репараметризация вариационной нижней границы даёт оценщик нижней границы, который можно напрямую оптимизировать с помощью стандартных стохастических градиентных методов. Во-вторых, мы показываем, что для независимых одинаково распределённых наборов данных с непрерывными латентными переменными на каждую точку данных вывод апостериорного распределения может быть сделан особенно эффективным путём подгонки модели приблизительного вывода (также называемой моделью распознавания) к неразрешимому апостериорному распределению с использованием предложенного оценщика нижней границы. Теоретические преимущества подтверждаются экспериментальными результатами.*

## Загрузка из исходного формата

По умолчанию [AutoencoderKL](/docs/diffusers/main/ru/api/models/autoencoderkl#diffusers.AutoencoderKL) следует загружать с помощью [from_pretrained()](/docs/diffusers/main/ru/api/models/overview#diffusers.ModelMixin.from_pretrained), но его также можно загрузить из исходного формата, используя `FromOriginalModelMixin.from_single_file`, следующим образом:

```py
from diffusers import AutoencoderKL

url = "https://huggingface.co/stabilityai/sd-vae-ft-mse-original/blob/main/vae-ft-mse-840000-ema-pruned.safetensors"  # can also be a local file
model = AutoencoderKL.from_single_file(url)
```

## AutoencoderKL[[diffusers.AutoencoderKL]]

#### diffusers.AutoencoderKL[[diffusers.AutoencoderKL]]

```python
diffusers.AutoencoderKL(in_channels: int = 3, out_channels: int = 3, down_block_types: tuple = ('DownEncoderBlock2D',), up_block_types: tuple = ('UpDecoderBlock2D',), block_out_channels: tuple = (64,), layers_per_block: int = 1, act_fn: str = 'silu', latent_channels: int = 4, norm_num_groups: int = 32, sample_size: int = 32, scaling_factor: float = 0.18215, shift_factor: float | None = None, latents_mean: tuple[float] | None = None, latents_std: tuple[float] | None = None, force_upcast: bool = True, use_quant_conv: bool = True, use_post_quant_conv: bool = True, mid_block_add_attention: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L36)

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

in_channels (int, *необязательный*, по умолчанию 3) : Количество каналов во входном изображении.

out_channels (int, *optional*, по умолчанию 3) : Количество каналов на выходе.

down_block_types (`tuple[str]`, *необязательный*, по умолчанию `("DownEncoderBlock2D",)`) : кортеж типов блоков даунсемплинга.

up_block_types (`tuple[str]`, *необязательный*, по умолчанию `("UpDecoderBlock2D",)`) : кортеж типов блоков апсемплинга.

block_out_channels (`tuple[int]`, *необязательный*, по умолчанию `(64,)`) : кортеж каналов вывода блоков.

act_fn (`str`, *необязательный*, по умолчанию `"silu"`) : Функция активации, которую следует использовать.

latent_channels (`int`, *необязательный*, по умолчанию 4) : Количество каналов в латентном пространстве.

sample_size (`int`, *необязательный*, по умолчанию `32`) : Размер входной выборки.

scaling_factor (`float`, *optional*, по умолчанию 0.18215) : Компонентное стандартное отклонение обученного латентного пространства, вычисленное на основе первой партии обучающей выборки. Используется для масштабирования латентного пространства до единичной дисперсии при обучении диффузионной модели. Перед передачей в диффузионную модель латенты масштабируются по формуле `z = z * scaling_factor`. При декодировании латенты возвращаются к исходному масштабу по формуле: `z = 1 / scaling_factor * z`. Дополнительные сведения см. в разделах 4.3.2 и D.1 статьи [High-Resolution Image Synthesis with Latent Diffusion Models](https://huggingface.co/papers/2112.10752).

force_upcast (`bool`, *необязательный*, по умолчанию `True`) : Если включено, VAE будет принудительно работать в float32 для пайплайнов с высоким разрешением изображений, таких как SD-XL. VAE можно дообучить или обучить для работы в более низком диапазоне без значительной потери точности, в этом случае `force_upcast` можно установить в `False` — см.: https://huggingface.co/madebyollin/sdxl-vae-fp16-fix

mid_block_add_attention (`bool`, *необязательный*, по умолчанию `True`) : Если включено, mid_block в Encoder и Decoder будет содержать блоки внимания. Если установлено в false, mid_block будет содержать только блоки resnet

Модель VAE с потерей KL для кодирования изображений в латенты и декодирования латентных представлений в изображения.

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

#### decode[[diffusers.AutoencoderKL.decode]]

```python
decode(z: FloatTensor, return_dict: bool = True, generator = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L213)

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

z (`torch.Tensor`) : Входная партия латентных векторов.

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

**Возвращает:** `~models.vae.DecoderOutput` или `tuple`

If return_dict is True, a `~models.vae.DecoderOutput` is returned, otherwise a plain `tuple` is returned.

Декодировать пакет изображений.

#### encode[[diffusers.AutoencoderKL.encode]]

```python
encode(x: Tensor, return_dict: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L170)

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

x (`torch.Tensor`) : Входная партия изображений.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~models.autoencoder_kl.AutoencoderKLOutput` вместо обычного кортежа.

**Возвращает:**

Латентные представления закодированных изображений. Если `return_dict` равно True, возвращается `~models.autoencoder_kl.AutoencoderKLOutput`, в противном случае возвращается обычный `tuple`.

Кодирует пакет изображений в латенты.

#### forward[[diffusers.AutoencoderKL.forward]]

```python
forward(sample: Tensor, sample_posterior: bool = False, return_dict: bool = True, generator: typing.Optional[torch.Generator] = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L413)

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

sample (`torch.Tensor`) : Входящий образец.

sample_posterior (`bool`, *необязательный*, по умолчанию `False`) : Флаг, определяющий, следует ли выполнять выборку из апостериорного распределения.

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

generator (`torch.Generator`, *необязательный*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности выборки.

**Возвращает:** `~models.vae.DecoderOutput` или `tuple`

Если `return_dict` равно True, возвращается `~models.vae.DecoderOutput`, иначе возвращается обычный `tuple`.

#### fuse_qkv_projections[[diffusers.AutoencoderKL.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L450)

Включает объединённые проекции QKV. Для модулей само-внимания все матрицы проекций (т. е. запрос, ключ, значение) объединяются. Для модулей кросс-внимания объединяются матрицы проекций ключа и значения.

> [!WARNING] > Этот API 🧪 экспериментальный.

#### set_default_attn_processor[[diffusers.AutoencoderKL.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L143)

Отключает пользовательские обработчики внимания и устанавливает реализацию внимания по умолчанию.

#### tiled_decode[[diffusers.AutoencoderKL.tiled_decode]]

```python
tiled_decode(z: Tensor, return_dict: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L364)

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

z (`torch.Tensor`) : Входная партия латентных векторов.

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

**Возвращает:** `~models.vae.DecoderOutput` или `tuple`

If return_dict is True, a `~models.vae.DecoderOutput` is returned, otherwise a plain `tuple` is returned.

Декодирование пакета изображений с использованием тайлованного декодера.

#### tiled_encode[[diffusers.AutoencoderKL.tiled_encode]]

```python
tiled_encode(x: Tensor, return_dict: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L302)

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

x (`torch.Tensor`) : Входная партия изображений.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~models.autoencoder_kl.AutoencoderKLOutput` вместо обычного кортежа.

**Возвращает:** `~models.autoencoder_kl.AutoencoderKLOutput` или `tuple`

If return_dict is True, a `~models.autoencoder_kl.AutoencoderKLOutput` is returned, otherwise a plain `tuple` is returned.

Кодирует пакет изображений с использованием тайлованного энкодера.

Когда эта опция включена, VAE разбивает входной тензор на тайлы, чтобы вычислить кодирование за несколько шагов. Это полезно для поддержания постоянного потребления памяти независимо от размера изображения. Итоговый результат тайлового кодирования отличается от нетайлового, поскольку каждый тайл использует отдельный энкодер. Чтобы избежать артефактов на границах тайлов, они перекрываются и смешиваются для формирования плавного вывода. Вы всё ещё можете заметить изменения в выводе размером с тайл, но они должны быть значительно менее заметными.

#### unfuse_qkv_projections[[diffusers.AutoencoderKL.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_kl.py#L472)

Отключает объединенную проекцию QKV, если она включена.

> [!WARNING] > Этот API 🧪 экспериментальный.

## AutoencoderKLOutput[[diffusers.models.modeling_outputs.AutoencoderKLOutput]]

#### diffusers.models.modeling_outputs.AutoencoderKLOutput[[diffusers.models.modeling_outputs.AutoencoderKLOutput]]

```python
diffusers.models.modeling_outputs.AutoencoderKLOutput(latent_dist: DiagonalGaussianDistribution)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L7)

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

latent_dist (`DiagonalGaussianDistribution`) : Закодированные выходные данные `Encoder`, представленные в виде среднего и logvar распределения `DiagonalGaussianDistribution`. `DiagonalGaussianDistribution` позволяет извлекать латентные переменные из этого распределения.

Результат метода кодирования AutoencoderKL.

## DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

#### diffusers.models.autoencoders.vae.DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

```python
diffusers.models.autoencoders.vae.DecoderOutput(sample: Tensor, commit_loss: typing.Optional[torch.FloatTensor] = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/vae.py#L49)

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

sample (`torch.Tensor` формы `(batch_size, num_channels, height, width)`) : Декодированный вывод из последнего слоя модели.

Результат метода декодирования.