# ControlNetUnion

  

ControlNetUnionModel — это реализация ControlNet для Stable Diffusion XL.

Модель ControlNet была представлена в [ControlNetPlus](https://github.com/xinsir6/ControlNetPlus) пользователем xinsir6. Она поддерживает несколько входных условий без увеличения вычислительных затрат.

*Мы разработали новую архитектуру, которая поддерживает более 10 типов управления в условной генерации изображений из текста и способна создавать изображения высокого разрешения, визуально сопоставимые с результатами midjourney. Сеть основана на исходной архитектуре ControlNet; мы предлагаем два новых модуля: 1. Расширение исходного ControlNet для поддержки различных условий изображения с использованием одних и тех же параметров сети. 2. Поддержка ввода нескольких условий без увеличения вычислительной нагрузки, что особенно важно для дизайнеров, желающих детально редактировать изображение. Различные условия используют один и тот же энкодер условий, без добавления дополнительных вычислений или параметров.*

## StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

#### diffusers.StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

```python
diffusers.StableDiffusionXLControlNetUnionPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)
```

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

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

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

text_encoder_2 ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : второй замороженный текстовый энкодер ([laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k)).

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

tokenizer_2 ([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` для удаления шума из закодированных латентов изображения.

controlnet ([ControlNetUnionModel](/docs/diffusers/main/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel)`) : Provides additional conditioning to the `unet` during the denoising process.

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

force_zeros_for_empty_prompt (`bool`, *необязательный*, по умолчанию `"True"`) : следует ли всегда устанавливать эмбеддинги отрицательного промпта в 0. См. также конфигурацию `stabilityai/stable-diffusion-xl-base-1-0`.

add_watermarker (`bool`, *необязательный*) : Использовать ли библиотеку [invisible_watermark](https://github.com/ShieldMnt/invisible-watermark/) для добавления водяных знаков на выходные изображения. Если не указано, по умолчанию устанавливается в `True`, если пакет установлен; в противном случае водяной знак не используется.

Пайплайн для генерации изображений по тексту с использованием Stable Diffusion XL и направлением через ControlNet.

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

Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/main/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/main/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/main/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров

#### __call__[[diffusers.StableDiffusionXLControlNetUnionPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, 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, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут переданы в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`.

control_image (`PipelineImageInput` или `list[PipelineImageInput]`, *необязательный*) : Вводное условие ControlNet для предоставления руководящих сигналов `unet` при генерации. Если тип указан как `torch.Tensor`, он передаётся в ControlNet без изменений. Также в качестве изображения может приниматься `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения должны передаваться в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в пакет для ввода в один ControlNet.

height (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях. Значения ниже 512 пикселей будут работать некорректно для [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) и контрольных точек, которые не были специально дообучены на низких разрешениях.

width (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Ширина генерируемого изображения в пикселях. Значения менее 512 пикселей будут работать некорректно для [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) и контрольных точек, которые не были специально дообучены на низких разрешениях.

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

timesteps (`list[int]`, *optional*) : Пользовательские шаги для процесса денойзинга с планировщиками, поддерживающими аргумент `timesteps` в их методе `set_timesteps`. Если не определено, будет использоваться поведение по умолчанию при передаче `num_inference_steps`. Должны быть в порядке убывания.

sigmas (`list[float]`, *optional*) : Пользовательские сигмы для процесса денойзинга в планировщиках, поддерживающих аргумент `sigmas` в методе `set_timesteps`. Если не задано, будет использовано поведение по умолчанию при передаче `num_inference_steps`.

denoising_end (`float`, *optional*) : When specified, determines the fraction (between 0.0 and 1.0) of the total denoising process to be completed before it is intentionally prematurely terminated. As a result, the returned sample will still retain a substantial amount of noise as determined by the discrete timesteps selected by the scheduler. The denoising_end parameter should ideally be utilized when this pipeline forms a part of a "Mixture of Denoisers" multi-pipeline setup, as elaborated in [**Refining the Image Output**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output)

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

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

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

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

eta (`float`, *необязательный*, по умолчанию 0.0) : Соответствует параметру eta (η) из статьи [DDIM](https://huggingface.co/papers/2010.02502). Применяется только к [DDIMScheduler](/docs/diffusers/main/ru/api/schedulers/ddim#diffusers.DDIMScheduler) и игнорируется другими планировщиками.

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

ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами.

ip_adapter_image_embeds (`list[torch.Tensor]`, *необязательный*) : Предварительно сгенерированные эмбеддинги изображений для IP-Adapter. Должен представлять собой список, длина которого равна количеству IP-адаптеров. Каждый элемент должен быть тензором формы `(batch_size, num_images, emb_dim)`. Если `do_classifier_free_guidance` установлен в `True`, должен содержать отрицательный эмбеддинг изображения. Если не указан, эмбеддинги вычисляются из входного аргумента `ip_adapter_image`.

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) вместо обычного кортежа.

cross_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

controlnet_conditioning_scale (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Выходные данные ControlNet умножаются на `controlnet_conditioning_scale` перед добавлением к остаточному соединению в исходном `unet`. Если в `init` указано несколько ControlNet, соответствующий масштаб можно задать в виде списка.

guess_mode (`bool`, *необязательный*, по умолчанию `False`) : Кодер ControlNet пытается распознать содержимое входного изображения, даже если вы удалите все промпты. Рекомендуется значение `guidance_scale` в диапазоне от 3.0 до 5.0.

control_guidance_start (`float` или `list[float]`, *необязательный*, по умолчанию 0.0) : Доля от общего числа шагов, на которой ControlNet начинает применяться.

control_guidance_end (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Доля от общего числа шагов, на которой ControlNet прекращает применяться.

control_mode (`int` or `list[int]` or `list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in `init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image.

original_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Если `original_size` не совпадает с `target_size`, изображение будет выглядеть как уменьшенное или увеличенное. По умолчанию `original_size` равно `(height, width)`, если не указано иное. Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

crops_coords_top_left (`tuple[int]`, *optional*, по умолчанию (0, 0)) : `crops_coords_top_left` можно использовать для генерации изображения, которое выглядит как «обрезанное» из позиции `crops_coords_top_left` вниз. Как правило, хорошо центрированные изображения получаются при установке `crops_coords_top_left` в (0, 0). Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

target_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : В большинстве случаев `target_size` следует установить в желаемую высоту и ширину генерируемого изображения. Если не указано, по умолчанию будет `(height, width)`. Часть микроусловий SDXL, описанная в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

negative_original_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Используется для негативного условия процесса генерации на основе конкретного разрешения изображения. Является частью микроусловия SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

negative_crops_coords_top_left (`tuple[int]`, *optional*, по умолчанию (0, 0)) : Используется для негативного обусловливания процесса генерации на основе конкретных координат кадрирования. Является частью микрообусловливания SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

negative_target_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Используется для негативного обусловливания процесса генерации на основе целего разрешения изображения. В большинстве случаев должно совпадать с `target_size`. Является частью микрообусловливания SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

callback_on_step_end (`Callable`, `PipelineCallback`, `MultiPipelineCallbacks`, *optional*) : функция или подкласс `PipelineCallback` или `MultiPipelineCallbacks`, вызываемая в конце каждого шага денойзинга во время инференса со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса pipeline.

**Возвращает:** [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
>>> # !pip install controlnet_aux
>>> from controlnet_aux import LineartAnimeDetector
>>> from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel, AutoencoderKL
>>> from diffusers.utils import load_image
>>> import torch

>>> prompt = "A cat"
>>> # download an image
>>> image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
... ).resize((1024, 1024))
>>> # initialize the models and pipeline
>>> controlnet = ControlNetUnionModel.from_pretrained(
...     "xinsir/controlnet-union-sdxl-1.0", torch_dtype=torch.float16
... )
>>> vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
>>> pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0",
...     controlnet=controlnet,
...     vae=vae,
...     torch_dtype=torch.float16,
...     variant="fp16",
... )
>>> pipe.enable_model_cpu_offload()
>>> # prepare image
>>> processor = LineartAnimeDetector.from_pretrained("lllyasviel/Annotators")
>>> controlnet_img = processor(image, output_type="pil")
>>> # generate image
>>> image = pipe(prompt, control_image=[controlnet_img], control_mode=[3], height=1024, width=1024).images[0]
```

#### encode_prompt[[diffusers.StableDiffusionXLControlNetUnionPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = 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, lora_scale: float | None = None, clip_skip: int | None = None)
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`

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

num_images_per_prompt (`int`) : количество изображений, которые должны быть сгенерированы для каждого промпта

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

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

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

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

lora_scale (`float`, *optional*) : масштаб lora, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

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

#### get_guidance_scale_embedding[[diffusers.StableDiffusionXLControlNetUnionPipeline.get_guidance_scale_embedding]]

```python
get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)
```

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

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

w (`torch.Tensor`) : Генерирует векторы эмбеддингов с заданным масштабом руководства (guidance scale) для последующего обогащения эмбеддингов временных шагов.

embedding_dim (`int`, *необязательный*, по умолчанию 512) : Размерность генерируемых эмбеддингов.

dtype (`torch.dtype`, *необязательный*, по умолчанию `torch.float32`) : Тип данных для генерируемых эмбеддингов.

**Возвращает:** `torch.Tensor`

Векторы встраиваний с формой `(len(w), embedding_dim)`.

См. https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298

## StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

#### diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

```python
diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)
```

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

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

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

text_encoder (`CLIPTextModel`) : Замороженный текстовый энкодер. Stable Diffusion использует текстовую часть [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel), а именно вариант [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14).

text_encoder_2 (` CLIPTextModelWithProjection`) : Второй замороженный текстовый энкодер. Stable Diffusion XL использует текстовую и пул-части [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), а именно вариант [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k).

tokenizer (`CLIPTokenizer`) : Токенизатор класса [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`CLIPTokenizer`) : Второй токенизатор класса [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

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

controlnet ([ControlNetUnionModel](/docs/diffusers/main/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel)) : обеспечивает дополнительное управление для unet в процессе денойзинга.

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

requires_aesthetics_score (`bool`, *необязательный*, по умолчанию `"False"`) : Указывает, требуется ли для `unet` передача условия `aesthetic_score` во время инференса. См. также конфигурацию `stabilityai/stable-diffusion-xl-refiner-1-0`.

force_zeros_for_empty_prompt (`bool`, *необязательный*, по умолчанию `"True"`) : Указывает, следует ли принудительно устанавливать эмбеддинги отрицательного промпта в 0. См. также конфигурацию `stabilityai/stable-diffusion-xl-base-1-0`.

add_watermarker (`bool`, *необязательный*) : Использовать ли библиотеку [invisible_watermark](https://github.com/ShieldMnt/invisible-watermark/) для добавления водяных знаков на выходные изображения. Если значение не задано, по умолчанию используется True, если пакет установлен, в противном случае водяной знак не добавляется.

feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPImageProcessor)) : экземпляр `CLIPImageProcessor` для извлечения признаков из сгенерированных изображений; используется в качестве входных данных для `safety_checker`.

Пайплайн для генерации изображений по изображению с использованием Stable Diffusion XL и управления через ControlNet.

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

Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/main/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [load_ip_adapter()](/docs/diffusers/main/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров

#### __call__[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, strength: float = 0.8, num_inference_steps: int = 50, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, 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, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 0.8, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него.

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, `list[np.ndarray]`, : `list[list[torch.Tensor]]`, `list[list[np.ndarray]]` или `list[list[PIL.Image.Image]]`): начальное изображение будет использоваться как отправная точка для процесса генерации изображений. Также можно передавать латенты изображений в качестве `image`; при прямой передаче латентов они не будут кодироваться повторно.

control_image (`PipelineImageInput` или `list[PipelineImageInput]`, *необязательный*) : Вводное условие ControlNet для предоставления руководящих сигналов `unet` при генерации. Если тип указан как `torch.Tensor`, он передаётся в ControlNet без изменений. Также в качестве изображения может приниматься `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения должны передаваться в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в пакет для ввода в один ControlNet.

height (`int`, *optional*, по умолчанию — размер control_image) : Высота генерируемого изображения в пикселях. Значения ниже 512 пикселей будут работать некорректно для [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) и контрольных точек, которые не были специально дообучены на низких разрешениях.

width (`int`, *необязательный*, по умолчанию — размер control_image) : Ширина генерируемого изображения в пикселях. Значения менее 512 пикселей будут работать некорректно для [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) и контрольных точек, которые не были специально дообучены на низких разрешениях.

strength (`float`, *optional*, по умолчанию 0.8) : Определяет степень трансформации исходного `image`. Значение должно быть в диапазоне от 0 до 1. `image` используется как отправная точка, и чем выше `strength`, тем больше шума добавляется. Количество шагов денойзинга зависит от количества шума, добавленного изначально. Когда `strength` равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в `num_inference_steps`. Значение 1 фактически игнорирует `image`.

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

guidance_scale (`float`, *optional*, по умолчанию 7.5) : Масштаб руководства, как определено в [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://huggingface.co/papers/2205.11487). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

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

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

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

eta (`float`, *optional*, по умолчанию 0.0) : Соответствует параметру eta (η) в статье DDIM: https://huggingface.co/papers/2010.02502. Применяется только к [schedulers.DDIMScheduler](/docs/diffusers/main/ru/api/schedulers/ddim#diffusers.DDIMScheduler), для остальных игнорируется.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](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`.

ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами.

ip_adapter_image_embeds (`list[torch.Tensor]`, *необязательный*) : Предварительно сгенерированные эмбеддинги изображений для IP-Adapter. Должен представлять собой список, длина которого равна количеству IP-адаптеров. Каждый элемент должен быть тензором формы `(batch_size, num_images, emb_dim)`. Если `do_classifier_free_guidance` установлен в `True`, должен содержать отрицательный эмбеддинг изображения. Если не указан, эмбеддинги вычисляются из входного аргумента `ip_adapter_image`.

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

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

cross_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

controlnet_conditioning_scale (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Выходные данные ControlNet умножаются на `controlnet_conditioning_scale` перед добавлением к остаточному соединению в исходном `unet`. Если в `init` указано несколько ControlNet, соответствующий масштаб можно задать в виде списка.

guess_mode (`bool`, *необязательный*, по умолчанию `False`) : В этом режиме энкодер ControlNet будет стараться распознать содержимое входного изображения даже при удалении всех промптов. Рекомендуется значение `guidance_scale` от 3.0 до 5.0.

control_guidance_start (`float` или `list[float]`, *необязательный*, по умолчанию 0.0) : Доля от общего числа шагов, на которой ControlNet начинает применяться.

control_guidance_end (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Доля от общего числа шагов, на которой ControlNet прекращает применяться.

control_mode (`int` or `list[int]` or `list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in `init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image

original_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Если `original_size` не совпадает с `target_size`, изображение будет выглядеть как уменьшенное или увеличенное. По умолчанию `original_size` равно `(height, width)`, если не указано иное. Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

crops_coords_top_left (`tuple[int]`, *optional*, по умолчанию (0, 0)) : `crops_coords_top_left` можно использовать для генерации изображения, которое выглядит как «обрезанное» из позиции `crops_coords_top_left` вниз. Как правило, хорошо центрированные изображения получаются при установке `crops_coords_top_left` в (0, 0). Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

target_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : В большинстве случаев `target_size` следует установить в желаемую высоту и ширину генерируемого изображения. Если не указано, по умолчанию будет `(height, width)`. Часть микроусловий SDXL, описанная в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

negative_original_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Используется для негативного условия процесса генерации на основе конкретного разрешения изображения. Является частью микроусловия SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

negative_crops_coords_top_left (`tuple[int]`, *optional*, по умолчанию (0, 0)) : Используется для негативного обусловливания процесса генерации на основе конкретных координат кадрирования. Является частью микрообусловливания SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

negative_target_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Используется для негативного обусловливания процесса генерации на основе целего разрешения изображения. В большинстве случаев должно совпадать с `target_size`. Является частью микрообусловливания SDXL, описанной в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Для получения дополнительной информации см. этот тред: https://github.com/huggingface/diffusers/issues/4208.

aesthetic_score (`float`, *необязательный*, по умолчанию 6.0) : Используется для имитации эстетической оценки сгенерированного изображения путём влияния на положительное текстовое условие. Является частью микроусловий SDXL, как описано в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

negative_aesthetic_score (`float`, *optional*, по умолчанию 2.5) : Часть микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Может использоваться для имитации эстетической оценки сгенерированного изображения путём влияния на отрицательное текстовое условие.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

callback_on_step_end (`Callable`, `PipelineCallback`, `MultiPipelineCallbacks`, *optional*) : функция или подкласс `PipelineCallback` или `MultiPipelineCallbacks`, вызываемая в конце каждого шага денойзинга во время инференса со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса pipeline.

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

[StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), если `return_dict` равно True, иначе `tuple` с выходными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```py
# !pip install controlnet_aux
from diffusers import (
    StableDiffusionXLControlNetUnionImg2ImgPipeline,
    ControlNetUnionModel,
    AutoencoderKL,
)
from diffusers.utils import load_image
import torch
from PIL import Image
import numpy as np

prompt = "A cat"
# download an image
image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
)
# initialize the models and pipeline
controlnet = ControlNetUnionModel.from_pretrained(
    "brad-twinkl/controlnet-union-sdxl-1.0-promax", torch_dtype=torch.float16
)
vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
pipe = StableDiffusionXLControlNetUnionImg2ImgPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    controlnet=controlnet,
    vae=vae,
    torch_dtype=torch.float16,
    variant="fp16",
).to("cuda")
# `enable_model_cpu_offload` is not recommended due to multiple generations
height = image.height
width = image.width
ratio = np.sqrt(1024.0 * 1024.0 / (width * height))
# 3 * 3 upscale correspond to 16 * 3 multiply, 2 * 2 correspond to 16 * 2 multiply and so on.
scale_image_factor = 3
base_factor = 16
factor = scale_image_factor * base_factor
W, H = int(width * ratio) // factor * factor, int(height * ratio) // factor * factor
image = image.resize((W, H))
target_width = W // scale_image_factor
target_height = H // scale_image_factor
images = []
crops_coords_list = [
    (0, 0),
    (0, width // 2),
    (height // 2, 0),
    (width // 2, height // 2),
    0,
    0,
    0,
    0,
    0,
]
for i in range(scale_image_factor):
    for j in range(scale_image_factor):
        left = j * target_width
        top = i * target_height
        right = left + target_width
        bottom = top + target_height
        cropped_image = image.crop((left, top, right, bottom))
        cropped_image = cropped_image.resize((W, H))
        images.append(cropped_image)
# set ControlNetUnion input
result_images = []
for sub_img, crops_coords in zip(images, crops_coords_list):
    new_width, new_height = W, H
    out = pipe(
        prompt=[prompt] * 1,
        image=sub_img,
        control_image=[sub_img],
        control_mode=[6],
        width=new_width,
        height=new_height,
        num_inference_steps=30,
        crops_coords_top_left=(W, H),
        target_size=(W, H),
        original_size=(W * 2, H * 2),
    )
    result_images.append(out.images[0])
new_im = Image.new("RGB", (new_width * scale_image_factor, new_height * scale_image_factor))
new_im.paste(result_images[0], (0, 0))
new_im.paste(result_images[1], (new_width, 0))
new_im.paste(result_images[2], (new_width * 2, 0))
new_im.paste(result_images[3], (0, new_height))
new_im.paste(result_images[4], (new_width, new_height))
new_im.paste(result_images[5], (new_width * 2, new_height))
new_im.paste(result_images[6], (0, new_height * 2))
new_im.paste(result_images[7], (new_width, new_height * 2))
new_im.paste(result_images[8], (new_width * 2, new_height * 2))
```

#### encode_prompt[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = 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, lora_scale: float | None = None, clip_skip: int | None = None)
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`

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

num_images_per_prompt (`int`) : количество изображений, которые должны быть сгенерированы для каждого промпта

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

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

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

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

lora_scale (`float`, *optional*) : масштаб lora, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

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

## StableDiffusionXLControlNetUnionInpaintPipeline[[diffusers.StableDiffusionXLControlNetUnionInpaintPipeline]]

#### diffusers.StableDiffusionXLControlNetUnionInpaintPipeline[[diffusers.StableDiffusionXLControlNetUnionInpaintPipeline]]

```python
diffusers.StableDiffusionXLControlNetUnionInpaintPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: transformers.models.clip.image_processing_pil_clip.CLIPImageProcessorPil | None = None, image_encoder: transformers.models.clip.modeling_clip.CLIPVisionModelWithProjection | None = None)
```

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

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

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

text_encoder (`CLIPTextModel`) : Замороженный текстовый энкодер. Stable Diffusion XL использует текстовую часть [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel), а именно вариант [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14).

text_encoder_2 (` CLIPTextModelWithProjection`) : Второй замороженный текстовый энкодер. Stable Diffusion XL использует текстовую и пул-части [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModelWithProjection), а именно вариант [laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k).

tokenizer (`CLIPTokenizer`) : Токенизатор класса [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`CLIPTokenizer`) : Второй токенизатор класса [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

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

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

Пайплайн для генерации изображений по тексту с использованием Stable Diffusion XL.

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

Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/main/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/main/ru/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/main/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/main/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров

#### __call__[[diffusers.StableDiffusionXLControlNetUnionInpaintPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None, strength: float = 0.9999, num_inference_steps: int = 50, denoising_start: float | None = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, 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, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = 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, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, guidance_rescale: float = 0.0, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него.

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`

image (`PIL.Image.Image`) : `Image` или тензор, представляющий пакет изображений, которые будут подвергнуты inpainting, *т. е.* части изображения будут замаскированы с помощью `mask_image` и перерисованы в соответствии с `prompt`.

mask_image (`PIL.Image.Image`) : `Image` или тензор, представляющий пакет изображений, для маскирования `image`. Белые пиксели в маске будут перерисованы, а чёрные — сохранены. Если `mask_image` — это изображение PIL, оно будет преобразовано в одноцветный канал (яркость) перед использованием. Если это тензор, он должен содержать один цветовой канал (L) вместо трёх, поэтому ожидаемая форма — `(B, H, W, 1)`.

control_image (`PipelineImageInput` или `list[PipelineImageInput]`, *необязательный*) : Вводное условие ControlNet для предоставления руководящих сигналов `unet` при генерации. Если тип указан как `torch.Tensor`, он передаётся в ControlNet без изменений. Также в качестве изображения может приниматься `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения должны передаваться в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в пакет для ввода в один ControlNet.

height (`int`, *optional*, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Высота генерируемого изображения в пикселях.

width (`int`, *optional*, по умолчанию self.unet.config.sample_size * self.vae_scale_factor) : Ширина генерируемого изображения в пикселях.

padding_mask_crop (`int`, *optional*, по умолчанию `None`) : Размер поля (margin) для обрезки, применяемой к изображению и маске. Если `None`, обрезка не применяется к image и mask_image. Если `padding_mask_crop` не равно `None`, сначала находится прямоугольная область с тем же соотношением сторон, что и у изображения, содержащая всю замаскированную область, а затем эта область расширяется на основе `padding_mask_crop`. После этого image и mask_image обрезаются по расширенной области перед изменением размера до исходного размера изображения для инпейнтинга. Это полезно, когда замаскированная область мала, а изображение велико и содержит информацию, не относящуюся к инпейнтингу, например фон.

strength (`float`, *optional*, по умолчанию 0.9999) : Концептуально указывает, насколько сильно трансформировать замаскированную часть исходного `image`. Значение должно быть в диапазоне от 0 до 1. `image` используется как отправная точка: чем больше `strength`, тем больше шума добавляется к изображению. Количество шагов денойзинга зависит от количества шума, добавленного изначально. Если `strength` равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в `num_inference_steps`. Таким образом, значение 1 фактически игнорирует замаскированную часть исходного `image`. Обратите внимание, что если `denoising_start` объявлено как целое число, значение `strength` игнорируется.

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

denoising_start (`float`, *optional*) : Если указано, определяет долю (от 0.0 до 1.0) общего процесса денойзинга, которая пропускается перед его началом. В результате начальная часть процесса денойзинга пропускается, и предполагается, что переданное `image` является частично денойзинженным изображением. Обратите внимание, что при указании этого параметра strength игнорируется. Параметр `denoising_start` особенно полезен при интеграции данного конвейера в многоконвейерную конфигурацию «Mixture of Denoisers», как описано в [**Уточнение вывода изображения**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output).

denoising_end (`float`, *optional*) : When specified, determines the fraction (between 0.0 and 1.0) of the total denoising process to be completed before it is intentionally prematurely terminated. As a result, the returned sample will still retain a substantial amount of noise (ca. final 20% of timesteps still needed) and should be denoised by a successor pipeline that has `denoising_start` set to 0.8 so that it only denoises the final 20% of the scheduler. The denoising_end parameter should ideally be utilized when this pipeline forms a part of a "Mixture of Denoisers" multi-pipeline setup, as elaborated in [**Refining the Image Output**](https://huggingface.co/docs/diffusers/api/pipelines/stable_diffusion/stable_diffusion_xl#refining-the-image-output).

guidance_scale (`float`, *optional*, по умолчанию 7.5) : Масштаб руководства, как определено в [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://huggingface.co/papers/2205.11487). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

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

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

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

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

ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами.

ip_adapter_image_embeds (`list[torch.Tensor]`, *необязательный*) : Предварительно сгенерированные эмбеддинги изображений для IP-Adapter. Должен представлять собой список, длина которого равна количеству IP-адаптеров. Каждый элемент должен быть тензором формы `(batch_size, num_images, emb_dim)`. Если `do_classifier_free_guidance` установлен в `True`, должен содержать отрицательный эмбеддинг изображения. Если не указан, эмбеддинги вычисляются из входного аргумента `ip_adapter_image`.

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

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

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

eta (`float`, *optional*, по умолчанию 0.0) : Соответствует параметру eta (η) в статье DDIM: https://huggingface.co/papers/2010.02502. Применяется только к [schedulers.DDIMScheduler](/docs/diffusers/main/ru/api/schedulers/ddim#diffusers.DDIMScheduler), для остальных игнорируется.

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

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

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

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

cross_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

controlnet_conditioning_scale (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Выходные данные ControlNet умножаются на `controlnet_conditioning_scale` перед добавлением к остаточному соединению в исходном `unet`. Если в `init` указано несколько ControlNet, соответствующий масштаб можно задать в виде списка.

guess_mode (`bool`, *необязательный*, по умолчанию `False`) : Кодер ControlNet пытается распознать содержимое входного изображения, даже если вы удалите все промпты. Рекомендуется значение `guidance_scale` в диапазоне от 3.0 до 5.0.

control_guidance_start (`float` или `list[float]`, *необязательный*, по умолчанию 0.0) : Доля от общего числа шагов, на которой ControlNet начинает применяться.

control_guidance_end (`float` или `list[float]`, *необязательный*, по умолчанию 1.0) : Доля от общего числа шагов, на которой ControlNet прекращает применяться.

control_mode (`int` or `list[int]` or `list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in `init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image.

guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor from [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://arxiv.org/pdf/2305.08891.pdf).

original_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : Если `original_size` не совпадает с `target_size`, изображение будет выглядеть как уменьшенное или увеличенное. По умолчанию `original_size` равно `(width, height)`, если не указано иное. Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

crops_coords_top_left (`tuple[int]`, *optional*, по умолчанию (0, 0)) : `crops_coords_top_left` можно использовать для генерации изображения, которое выглядит как «обрезанное» из позиции `crops_coords_top_left` вниз. Как правило, хорошо центрированные изображения получаются при установке `crops_coords_top_left` в (0, 0). Является частью микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

target_size (`tuple[int]`, *optional*, по умолчанию (1024, 1024)) : В большинстве случаев `target_size` следует установить в желаемую высоту и ширину генерируемого изображения. Если не указано, по умолчанию будет `(width, height)`. Является частью микроусловий SDXL, как описано в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

aesthetic_score (`float`, *необязательный*, по умолчанию 6.0) : Используется для имитации эстетической оценки сгенерированного изображения путём влияния на положительное текстовое условие. Является частью микроусловий SDXL, как описано в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

negative_aesthetic_score (`float`, *optional*, по умолчанию 2.5) : Часть микроусловий SDXL, описанных в разделе 2.2 статьи [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). Может использоваться для имитации эстетической оценки сгенерированного изображения путём влияния на отрицательное текстовое условие.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

callback_on_step_end (`Callable`, `PipelineCallback`, `MultiPipelineCallbacks`, *optional*) : функция или подкласс `PipelineCallback` или `MultiPipelineCallbacks`, вызываемая в конце каждого шага денойзинга во время инференса со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса pipeline.

**Возвращает:** `~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput` или `tuple`

`~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput`, если `return_dict` равно True, иначе `tuple. `tuple. При возврате кортежа первым элементом является список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```py
from diffusers import StableDiffusionXLControlNetUnionInpaintPipeline, ControlNetUnionModel, AutoencoderKL
from diffusers.utils import load_image
import torch
import numpy as np
from PIL import Image

prompt = "A cat"
# download an image
image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/in_paint/overture-creations-5sI6fQgYIuo.png"
).resize((1024, 1024))
mask = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/in_paint/overture-creations-5sI6fQgYIuo_mask.png"
).resize((1024, 1024))
# initialize the models and pipeline
controlnet = ControlNetUnionModel.from_pretrained(
    "brad-twinkl/controlnet-union-sdxl-1.0-promax", torch_dtype=torch.float16
)
vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
pipe = StableDiffusionXLControlNetUnionInpaintPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    controlnet=controlnet,
    vae=vae,
    torch_dtype=torch.float16,
    variant="fp16",
)
pipe.enable_model_cpu_offload()
controlnet_img = image.copy()
controlnet_img_np = np.array(controlnet_img)
mask_np = np.array(mask)
controlnet_img_np[mask_np > 0] = 0
controlnet_img = Image.fromarray(controlnet_img_np)
# generate image
image = pipe(prompt, image=image, mask_image=mask, control_image=[controlnet_img], control_mode=[7]).images[0]
image.save("inpaint.png")
```

#### encode_prompt[[diffusers.StableDiffusionXLControlNetUnionInpaintPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = 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, lora_scale: float | None = None, clip_skip: int | None = None)
```

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

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

prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования

prompt_2 (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые будут отправлены в `tokenizer_2` и `text_encoder_2`. Если не задано, в обоих текстовых кодировщиках используется `prompt`

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

num_images_per_prompt (`int`) : количество изображений, которые должны быть сгенерированы для каждого промпта

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

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

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

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

lora_scale (`float`, *optional*) : масштаб lora, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.

clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.

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