# Latent-апскейлер

Модель Stable Diffusion latent upscaler была создана [Katherine Crowson](https://github.com/crowsonkb/k-diffusion) в сотрудничестве с [Stability AI](https://stability.ai/). Она используется для повышения разрешения выходного изображения в 2 раза (см. этот демонстрационный [notebook](https://colab.research.google.com/drive/1o1qYJcFeywzCIdkfKJy7cTpgZTCM2EI4) для примера оригинальной реализации).

> [!TIP]
> Обязательно ознакомьтесь с разделом [Советы](overview#tips) по Stable Diffusion, чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также как эффективно переиспользовать компоненты конвейера!
>
> Если вы хотите использовать одну из официальных контрольных точек для задачи, изучите организации [CompVis](https://huggingface.co/CompVis) и [Stability AI](https://huggingface.co/stabilityai) на Hub!

## StableDiffusionLatentUpscalePipeline[[diffusers.StableDiffusionLatentUpscalePipeline]]

#### diffusers.StableDiffusionLatentUpscalePipeline[[diffusers.StableDiffusionLatentUpscalePipeline]]

```python
diffusers.StableDiffusionLatentUpscalePipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, scheduler: EulerDiscreteScheduler)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_latent_upscale.py#L84)

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

vae ([AutoencoderKL](/docs/diffusers/main/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTextModel)) : замороженный текстовый энкодер ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)).

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.

unet ([UNet2DConditionModel](/docs/diffusers/main/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : `UNet2DConditionModel` для удаления шума из закодированных латентов изображения.

scheduler ([SchedulerMixin](/docs/diffusers/main/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : [EulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/euler#diffusers.EulerDiscreteScheduler), используемый в сочетании с `unet` для удаления шума из закодированных латентов изображения.

Пайплайн для увеличения разрешения выходного изображения Stable Diffusion в 2 раза.

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

Пайплайн также наследует следующие методы загрузки:
- [from_single_file()](/docs/diffusers/main/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`

#### __call__[[diffusers.StableDiffusionLatentUpscalePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, num_inference_steps: int = 75, guidance_scale: float = 9.0, negative_prompt: str | list[str] | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int = 1)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_latent_upscale.py#L396)

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

prompt (`str` или `list[str]`) : Промпт или промпты для управления увеличением изображения.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` или `list[np.ndarray]`) : `Image` или тензор, представляющий пакет изображений для увеличения. Если это тензор, он может быть либо латентным выходом модели Stable Diffusion, либо тензором изображения в диапазоне `[-1, 1]`. Он считается `latent`, если `image.shape[1]` равно `4`; в противном случае он считается представлением изображения и кодируется с помощью энкодера `vae` этого пайплайна.

num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

guidance_scale (`float`, *optional*, по умолчанию 7.5) : Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым `prompt`, за счёт снижения качества изображения. Guidance scale активируется, когда `guidance_scale > 1`.

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, определяющие, что следует исключить из генерируемого изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющая (`guidance_scale < 1`).

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

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не задано, тензор латентов генерируется путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не предоставлены, текстовые эмбеддинги генерируются из входного аргумента `prompt`.

negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не предоставлены, `negative_prompt_embeds` генерируются из входного аргумента `negative_prompt`.

pooled_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не предоставлены, пул-эмбеддинги текста генерируются из входного аргумента `prompt`.

negative_pooled_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных (взвешивание промптов). Если не предоставлены, пул-эмбеддинги `negative_prompt_embeds` генерируются из входного аргумента `negative_prompt`.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода сгенерированного изображения. Выберите между `PIL.Image` и `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли [StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) вместо обычного кортежа.

callback (`Callable`, *необязательный*) : функция, вызываемая каждые `callback_steps` шагов во время инференса. Функция вызывается со следующими аргументами: `callback(step: int, timestep: int, latents: torch.Tensor)`.

callback_steps (`int`, *optional*, по умолчанию 1) : Частота вызова функции `callback`. Если не указано, callback вызывается на каждом шаге.

**Возвращает:** [StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) или `tuple`

Если `return_dict` равно `True`, возвращается [StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список с сгенерированными изображениями.

Функция вызова конвейера для генерации.

Примеры:
```py
>>> from diffusers import StableDiffusionLatentUpscalePipeline, StableDiffusionPipeline
>>> import torch

>>> pipeline = StableDiffusionPipeline.from_pretrained(
...     "CompVis/stable-diffusion-v1-4", torch_dtype=torch.float16
... )
>>> pipeline.to("cuda")

>>> model_id = "stabilityai/sd-x2-latent-upscaler"
>>> upscaler = StableDiffusionLatentUpscalePipeline.from_pretrained(model_id, torch_dtype=torch.float16)
>>> upscaler.to("cuda")

>>> prompt = "a photo of an astronaut high resolution, unreal engine, ultra realistic"
>>> generator = torch.manual_seed(33)

>>> low_res_latents = pipeline(prompt, generator=generator, output_type="latent").images

>>> with torch.no_grad():
...     image = pipeline.decode_latents(low_res_latents)
>>> image = pipeline.numpy_to_pil(image)[0]

>>> image.save("../images/a1.png")

>>> upscaled_image = upscaler(
...     prompt=prompt,
...     image=low_res_latents,
...     num_inference_steps=20,
...     guidance_scale=0,
...     generator=generator,
... ).images[0]

>>> upscaled_image.save("../images/a2.png")
```

#### enable_sequential_cpu_offload[[diffusers.StableDiffusionLatentUpscalePipeline.enable_sequential_cpu_offload]]

```python
enable_sequential_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```

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

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

gpu_id (`int`, *optional*) : Идентификатор ускорителя, который будет использоваться при выводе. Если не указан, по умолчанию используется 0.

device (`torch.Device` или `str`, *необязательный*, по умолчанию None) : Тип устройства PyTorch для ускорителя, который будет использоваться при выводе. Если не указан, доступный ускоритель будет обнаружен и использован автоматически.

Выгружает все модели на CPU с помощью 🤗 Accelerate, что значительно снижает потребление памяти. При вызове state dicts всех компонентов `torch.nn.Module` (кроме тех, что находятся в `self._exclude_from_cpu_offload`) сохраняются на CPU, затем перемещаются на `torch.device('meta')` и загружаются на accelerator только тогда, когда у конкретного подмодуля вызывается его метод `forward`. Выгрузка происходит на уровне подмодулей. Экономия памяти выше, чем при использовании `enable_model_cpu_offload`, но производительность ниже.

#### enable_attention_slicing[[diffusers.StableDiffusionLatentUpscalePipeline.enable_attention_slicing]]

```python
enable_attention_slicing(slice_size: str | int = 'auto')
```

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

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

slice_size (`str` или `int`, *необязательный*, по умолчанию `"auto"`) : Если указано `"auto"`, вход для головок внимания делится пополам, и внимание вычисляется в два этапа. Если указано `"max"`, для экономии максимального объёма памяти выполняется по одному срезу за раз. Если указано число, используется столько срезов, сколько получается от `attention_head_dim // slice_size`. В этом случае `attention_head_dim` должно быть кратным `slice_size`.

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

> [!WARNING] > ⚠️ Не включайте нарезку внимания, если вы уже используете `scaled_dot_product_attention` (SDPA)
из PyTorch > 2.0 или xFormers. Эти вычисления внимания уже очень экономны по памяти, поэтому вам не нужно включать > эту функцию. Если вы включите нарезку внимания (attention slicing) с SDPA или xFormers, это может привести к серьезному замедлению!

Примеры:

```py
>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]
```

#### disable_attention_slicing[[diffusers.StableDiffusionLatentUpscalePipeline.disable_attention_slicing]]

```python
disable_attention_slicing()
```

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

Отключает вычисление внимания с нарезкой. Если `enable_attention_slicing` был вызван ранее, внимание вычисляется за один шаг.

#### enable_xformers_memory_efficient_attention[[diffusers.StableDiffusionLatentUpscalePipeline.enable_xformers_memory_efficient_attention]]

```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```

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

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

attention_op (`Callable`, *необязательный*) : Переопределяет оператор по умолчанию `None` для использования в качестве аргумента `op` функции [`memory_efficient_attention()`](https://facebookresearch.github.io/xformers/components/ops.html#xformers.ops.memory_efficient_attention) xFormers.

Включить энергоэффективное внимание от [xFormers](https://facebookresearch.github.io/xformers/). При включении этого параметра следует ожидать снижение потребления памяти GPU и возможное ускорение во время инференса. Ускорение во время обучения не гарантируется.

> [!WARNING] > ⚠️ Если включены и memory efficient attention, и sliced attention, memory efficient
attention имеет > приоритет.

Примеры:

```py
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)
```

#### disable_xformers_memory_efficient_attention[[diffusers.StableDiffusionLatentUpscalePipeline.disable_xformers_memory_efficient_attention]]

```python
disable_xformers_memory_efficient_attention()
```

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

Отключить энергоэффективное внимание из [xFormers](https://facebookresearch.github.io/xformers/).

#### encode_prompt[[diffusers.StableDiffusionLatentUpscalePipeline.encode_prompt]]

```python
encode_prompt(prompt, device, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_diffusion_latent_upscale.py#L166)

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

prompt (`str` или `list(int)`) : промпт для кодирования

device : (`torch.device`): устройство torch

do_classifier_free_guidance (`bool`) : использовать ли классификаторное свободное наведение (classifier free guidance)

negative_prompt (`str` или `list[str]`) : Промпт или промпты, которые не должны направлять генерацию изображения. Игнорируется, если направление не используется (то есть игнорируется, если `guidance_scale` меньше `1`).

prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.

pooled_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, пул-эмбеддинги текста будут сгенерированы из аргумента `prompt`.

negative_pooled_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промптов. Если не предоставлены, пул-эмбеддинги negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.

Кодирует промпт в скрытые состояния текстового энкодера.

## StableDiffusionPipelineOutput[[diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput]]

#### diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput[[diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput]]

```python
diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray, nsfw_content_detected: list[bool] | None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_output.py#L10)

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

images (`list[PIL.Image.Image]` или `np.ndarray`) : список денойзированных изображений PIL длиной `batch_size` или массив NumPy формы `(batch_size, height, width, num_channels)`.

nsfw_content_detected (`list[bool]`) : список, указывающий, содержит ли соответствующее сгенерированное изображение контент, нежелательный для просмотра на рабочем месте (nsfw), или `None`, если проверка безопасности не могла быть выполнена.

Класс вывода для пайплайнов Stable Diffusion.