Buckets:
# ControlNet
ControlNet был представлен в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala.
С помощью модели ControlNet можно передать дополнительное управляющее изображение для настройки и управления генерацией в Stable Diffusion. Например, если вы предоставите карту глубины, модель ControlNet сгенерирует изображение, сохраняющее пространственную информацию из карты глубины. Это более гибкий и точный способ управления процессом генерации изображений.
Аннотация из статьи:
*Мы представляем ControlNet — архитектуру нейронной сети для добавления пространственного управления условиями к крупным предобученным диффузионным моделям «текст в изображение». ControlNet фиксирует готовые к производству крупные диффузионные модели и повторно использует их глубокие и устойчивые слои кодирования, предобученные на миллиардах изображений, в качестве мощного каркаса для обучения разнообразному набору условных контролей. Нейронная архитектура соединяется с «нулевыми свёртками» (слоями свёртки с нулевой инициализацией), которые постепенно наращивают параметры от нуля и гарантируют, что вредоносный шум не может повлиять на дообучение. Мы тестируем различные условные контроли, например, края, глубину, сегментацию, позу человека и т. д., с Stable Diffusion, используя одно или несколько условий, с промптами или без них. Мы показываем, что обучение ControlNet устойчиво как на малых (<50k), так и на больших (>1m) наборах данных. Обширные результаты демонстрируют, что ControlNet может способствовать более широкому применению для управления диффузионными моделями изображений.*
Эта модель была добавлена пользователем [takuma104](https://huggingface.co/takuma104). ❤️
Исходный код можно найти в репозитории [lllyasviel/ControlNet](https://github.com/lllyasviel/ControlNet), а официальные контрольные точки ControlNet — на профиле [lllyasviel](https://huggingface.co/lllyasviel) в Hub.
> [!TIP]
> Обязательно ознакомьтесь с [руководством по планировщикам](../../using-diffusers/schedulers), чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом [повторное использование компонентов в разных конвейерах](../../using-diffusers/loading#reusing-models-in-multiple-pipelines), чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.
## StableDiffusionControlNetPipeline[[diffusers.StableDiffusionControlNetPipeline]]
#### diffusers.StableDiffusionControlNetPipeline[[diffusers.StableDiffusionControlNetPipeline]]
```python
diffusers.StableDiffusionControlNetPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L162)
**Параметры:**
vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/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/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.
unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : `UNet2DConditionModel` для удаления шума из закодированных латентов изображения.
controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet#diffusers.ControlNetModel) или `list[ControlNetModel]`) : Обеспечивает дополнительное условие для `unet` в процессе денойзинга. Если вы зададите несколько ControlNet в виде списка, выходы каждого ControlNet будут сложены вместе, чтобы создать одно объединённое дополнительное условие.
scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : планировщик, используемый в сочетании с `unet` для удаления шума из закодированных латентов изображения. Может быть одним из [DDIMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) или [PNDMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/pndm#diffusers.PNDMScheduler).
safety_checker (`StableDiffusionSafetyChecker`) : модуль классификации, оценивающий, могут ли сгенерированные изображения считаться оскорбительными или вредными. Подробности о потенциальных рисках модели см. в [карточке модели](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5).
feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : экземпляр `CLIPImageProcessor` для извлечения признаков из сгенерированных изображений; используется в качестве входных данных для `safety_checker`.
Пайплайн для генерации изображений по тексту с использованием Stable Diffusion и управления через ControlNet.
Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.
Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/v0.43.0/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/v0.43.0/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/v0.43.0/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров
#### __call__[[diffusers.StableDiffusionControlNetPipeline.__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, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 7.5, negative_prompt: 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, 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, 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/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L907)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.
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]]` or `list[list[PIL.Image.Image]]`): Вводное условие ControlNet для предоставления руководящих сигналов `unet` при генерации. Если тип указан как `torch.Tensor`, он передается в ControlNet без изменений. В качестве изображения также допускается `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения должны передаваться в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в пакет для ввода в один ControlNet. Если `prompt` является списком, и для одного ControlNet передан список изображений, каждое изображение будет сопоставлено с каждым промптом из списка `prompt`. То же самое относится и к нескольким ControlNet, где можно передать список списков изображений для пакетирования по каждому промпту и каждому ControlNet.
height (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях.
width (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Ширина генерируемого изображения в пикселях.
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`.
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`).
num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.
eta (`float`, *необязательный*, по умолчанию 0.0) : Соответствует параметру eta (η) из статьи [DDIM](https://huggingface.co/papers/2010.02502). Применяется только к [DDIMScheduler](/docs/diffusers/v0.43.0/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`.
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/v0.43.0/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 прекращает применяться.
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/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) или `tuple`
Если `return_dict` равно `True`, возвращается [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список сгенерированных изображений, а второй — список значений `bool`, указывающих, содержит ли соответствующее сгенерированное изображение контент, нежелательный для просмотра на рабочем месте (nsfw).
Функция вызова конвейера для генерации.
Примеры:
```py
>>> # !pip install opencv-python transformers accelerate
>>> from diffusers import StableDiffusionControlNetPipeline, ControlNetModel, UniPCMultistepScheduler
>>> from diffusers.utils import load_image
>>> import numpy as np
>>> import torch
>>> import cv2
>>> from PIL import Image
>>> # download an image
>>> image = load_image(
... "https://hf.co/datasets/huggingface/documentation-images/resolve/main/diffusers/input_image_vermeer.png"
... )
>>> image = np.array(image)
>>> # get canny image
>>> image = cv2.Canny(image, 100, 200)
>>> image = image[:, :, None]
>>> image = np.concatenate([image, image, image], axis=2)
>>> canny_image = Image.fromarray(image)
>>> # load control net and stable diffusion v1-5
>>> controlnet = ControlNetModel.from_pretrained("lllyasviel/sd-controlnet-canny", torch_dtype=torch.float16)
>>> pipe = StableDiffusionControlNetPipeline.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> # speed up diffusion process with faster scheduler and memory optimization
>>> pipe.scheduler = UniPCMultistepScheduler.from_config(pipe.scheduler.config)
>>> # remove following line if xformers is not installed
>>> pipe.enable_xformers_memory_efficient_attention()
>>> pipe.enable_model_cpu_offload()
>>> # generate image
>>> generator = torch.manual_seed(0)
>>> image = pipe(
... "futuristic-looking woman", num_inference_steps=20, generator=generator, image=canny_image
... ).images[0]
```
#### enable_attention_slicing[[diffusers.StableDiffusionControlNetPipeline.enable_attention_slicing]]
```python
enable_attention_slicing(slice_size: str | int = 'auto')
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetPipeline.disable_attention_slicing]]
```python
disable_attention_slicing()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2067)
Отключает вычисление внимания с нарезкой. Если `enable_attention_slicing` был вызван ранее, внимание вычисляется за один шаг.
#### enable_xformers_memory_efficient_attention[[diffusers.StableDiffusionControlNetPipeline.enable_xformers_memory_efficient_attention]]
```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetPipeline.disable_xformers_memory_efficient_attention]]
```python
disable_xformers_memory_efficient_attention()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2006)
Отключить энергоэффективное внимание из [xFormers](https://facebookresearch.github.io/xformers/).
#### load_textual_inversion[[diffusers.StableDiffusionControlNetPipeline.load_textual_inversion]]
```python
load_textual_inversion(pretrained_model_name_or_path: str | list[str] | dict[str, torch.Tensor] | list[dict[str, torch.Tensor]], token: str | list[str] | None = None, tokenizer: 'PreTrainedTokenizer' | None = None, text_encoder: 'PreTrainedModel' | None = None, **kwargs)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L271)
**Параметры:**
pretrained_model_name_or_path (`str` или `os.PathLike` или `list[str or os.PathLike]` или `Dict` или `list[Dict]`) : Может быть одним из следующих вариантов или списком таких вариантов: - Строка, *model id* (например, `sd-concepts-library/low-poly-hd-logos-icons`) предобученной модели, размещенной на Hub. - Путь к *каталогу* (например, `./my_text_inversion_directory/`), содержащему веса textual inversion. - Путь к *файлу* (например, `./my_text_inversions.pt`), содержащему веса textual inversion. - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).
token (`str` или `list[str]`, *необязательный*) : Переопределяет токен, используемый для весов текстовой инверсии. Если `pretrained_model_name_or_path` является списком, то `token` также должен быть списком той же длины.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel), *необязательный*) : Замороженный текстовый энкодер ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). Если не указан, функция использует self.tokenizer.
tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer), *необязательный*) : `CLIPTokenizer` для токенизации текста. Если не указан, функция использует self.tokenizer.
weight_name (`str`, *необязательный*) : Имя файла с кастомными весами. Это следует использовать, когда: - Сохранённый файл текстовой инверсии в формате 🤗 Diffusers был сохранён под конкретным именем весов, например `text_inv.bin`. - Сохранённый файл текстовой инверсии в формате Automatic1111.
cache_dir (`str | os.PathLike`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.
force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.
proxies (`dict[str, str]`, *необязательный*) : Словарь прокси-серверов для использования по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.
local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.
hf_token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).
revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.
subfolder (`str`, *необязательный*, по умолчанию `""`) : Путь к подпапке, в которой находится файл модели в составе более крупного репозитория моделей на Hub или локально.
mirror (`str`, *необязательный*) : Зеркальный источник для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.
Загрузите эмбеддинги Textual Inversion в текстовый энкодер [StableDiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline) (поддерживаются форматы 🤗 Diffusers и Automatic1111).
Пример:
Для загрузки вектора встраивания Textual Inversion в формате 🤗 Diffusers:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("sd-concepts-library/cat-toy")
prompt = "A <cat-toy> backpack"
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("cat-backpack.png")
```
Чтобы загрузить вектор встраивания Textual Inversion в формате Automatic1111, сначала скачайте вектор (например, с [civitAI](https://civitai.com/models/3036?modelVersionId=9857)), а затем загрузите его
локально:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("./charturnerv2.pt", token="charturnerv2")
prompt = "charturnerv2, multiple views of the same character in the same outfit, a character turnaround of a woman wearing a black jacket and red shirt, best quality, intricate details."
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("character.png")
```
#### encode_prompt[[diffusers.StableDiffusionControlNetPipeline.encode_prompt]]
```python
encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L298)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования
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`).
prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.
negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.
lora_scale (`float`, *необязательный*) : Масштаб LoRA, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.
clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.
Кодирует промпт в скрытые состояния текстового энкодера.
#### get_guidance_scale_embedding[[diffusers.StableDiffusionControlNetPipeline.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/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L850)
**Параметры:**
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
## StableDiffusionControlNetImg2ImgPipeline[[diffusers.StableDiffusionControlNetImg2ImgPipeline]]
#### diffusers.StableDiffusionControlNetImg2ImgPipeline[[diffusers.StableDiffusionControlNetImg2ImgPipeline]]
```python
diffusers.StableDiffusionControlNetImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_img2img.py#L140)
**Параметры:**
vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/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/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.
unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : `UNet2DConditionModel` для удаления шума из закодированных латентов изображения.
controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet#diffusers.ControlNetModel) или `list[ControlNetModel]`) : Обеспечивает дополнительное условие для `unet` в процессе денойзинга. Если вы зададите несколько ControlNet в виде списка, выходы каждого ControlNet будут сложены вместе, чтобы создать одно объединённое дополнительное условие.
scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : планировщик, используемый в сочетании с `unet` для удаления шума из закодированных латентов изображения. Может быть одним из [DDIMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) или [PNDMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/pndm#diffusers.PNDMScheduler).
safety_checker (`StableDiffusionSafetyChecker`) : модуль классификации, оценивающий, могут ли сгенерированные изображения считаться оскорбительными или вредными. Подробности о потенциальных рисках модели см. в [карточке модели](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5).
feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : экземпляр `CLIPImageProcessor` для извлечения признаков из сгенерированных изображений; используется в качестве входных данных для `safety_checker`.
Пайплайн для генерации изображений по изображению с использованием Stable Diffusion и управления через ControlNet.
Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.
Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/v0.43.0/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/v0.43.0/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/v0.43.0/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров
#### __call__[[diffusers.StableDiffusionControlNetImg2ImgPipeline.__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, control_image: 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 = 7.5, negative_prompt: 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, 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, 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/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_img2img.py#L905)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.
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 (`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]]` or `list[list[PIL.Image.Image]]`): Вводное условие ControlNet, задающее направление для `unet` при генерации. Если тип указан как `torch.Tensor`, значение передаётся в ControlNet без изменений. В качестве изображения также допускается `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения необходимо передавать в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в батч для входа в один ControlNet.
height (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях.
width (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Ширина генерируемого изображения в пикселях.
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) : Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым `prompt`, за счёт снижения качества изображения. Guidance scale активируется, когда `guidance_scale > 1`.
negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, определяющие, что следует исключить из генерируемого изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющая (`guidance_scale < 1`).
num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.
eta (`float`, *необязательный*, по умолчанию 0.0) : Соответствует параметру eta (η) из статьи [DDIM](https://huggingface.co/papers/2010.02502). Применяется только к [DDIMScheduler](/docs/diffusers/v0.43.0/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`.
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/v0.43.0/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 прекращает применяться.
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/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) или `tuple`
Если `return_dict` равно `True`, возвращается [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список сгенерированных изображений, а второй — список значений `bool`, указывающих, содержит ли соответствующее сгенерированное изображение контент, нежелательный для просмотра на рабочем месте (nsfw).
Функция вызова конвейера для генерации.
Примеры:
```py
>>> # !pip install opencv-python transformers accelerate
>>> from diffusers import StableDiffusionControlNetImg2ImgPipeline, ControlNetModel, UniPCMultistepScheduler
>>> from diffusers.utils import load_image
>>> import numpy as np
>>> import torch
>>> import cv2
>>> from PIL import Image
>>> # download an image
>>> image = load_image(
... "https://hf.co/datasets/huggingface/documentation-images/resolve/main/diffusers/input_image_vermeer.png"
... )
>>> np_image = np.array(image)
>>> # get canny image
>>> np_image = cv2.Canny(np_image, 100, 200)
>>> np_image = np_image[:, :, None]
>>> np_image = np.concatenate([np_image, np_image, np_image], axis=2)
>>> canny_image = Image.fromarray(np_image)
>>> # load control net and stable diffusion v1-5
>>> controlnet = ControlNetModel.from_pretrained("lllyasviel/sd-controlnet-canny", torch_dtype=torch.float16)
>>> pipe = StableDiffusionControlNetImg2ImgPipeline.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> # speed up diffusion process with faster scheduler and memory optimization
>>> pipe.scheduler = UniPCMultistepScheduler.from_config(pipe.scheduler.config)
>>> pipe.enable_model_cpu_offload()
>>> # generate image
>>> generator = torch.manual_seed(0)
>>> image = pipe(
... "futuristic-looking woman",
... num_inference_steps=20,
... generator=generator,
... image=image,
... control_image=canny_image,
... ).images[0]
```
#### enable_attention_slicing[[diffusers.StableDiffusionControlNetImg2ImgPipeline.enable_attention_slicing]]
```python
enable_attention_slicing(slice_size: str | int = 'auto')
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetImg2ImgPipeline.disable_attention_slicing]]
```python
disable_attention_slicing()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2067)
Отключает вычисление внимания с нарезкой. Если `enable_attention_slicing` был вызван ранее, внимание вычисляется за один шаг.
#### enable_xformers_memory_efficient_attention[[diffusers.StableDiffusionControlNetImg2ImgPipeline.enable_xformers_memory_efficient_attention]]
```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetImg2ImgPipeline.disable_xformers_memory_efficient_attention]]
```python
disable_xformers_memory_efficient_attention()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2006)
Отключить энергоэффективное внимание из [xFormers](https://facebookresearch.github.io/xformers/).
#### load_textual_inversion[[diffusers.StableDiffusionControlNetImg2ImgPipeline.load_textual_inversion]]
```python
load_textual_inversion(pretrained_model_name_or_path: str | list[str] | dict[str, torch.Tensor] | list[dict[str, torch.Tensor]], token: str | list[str] | None = None, tokenizer: 'PreTrainedTokenizer' | None = None, text_encoder: 'PreTrainedModel' | None = None, **kwargs)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L271)
**Параметры:**
pretrained_model_name_or_path (`str` или `os.PathLike` или `list[str or os.PathLike]` или `Dict` или `list[Dict]`) : Может быть одним из следующих вариантов или списком таких вариантов: - Строка, *model id* (например, `sd-concepts-library/low-poly-hd-logos-icons`) предобученной модели, размещенной на Hub. - Путь к *каталогу* (например, `./my_text_inversion_directory/`), содержащему веса textual inversion. - Путь к *файлу* (например, `./my_text_inversions.pt`), содержащему веса textual inversion. - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).
token (`str` или `list[str]`, *необязательный*) : Переопределяет токен, используемый для весов текстовой инверсии. Если `pretrained_model_name_or_path` является списком, то `token` также должен быть списком той же длины.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel), *необязательный*) : Замороженный текстовый энкодер ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). Если не указан, функция использует self.tokenizer.
tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer), *необязательный*) : `CLIPTokenizer` для токенизации текста. Если не указан, функция использует self.tokenizer.
weight_name (`str`, *необязательный*) : Имя файла с кастомными весами. Это следует использовать, когда: - Сохранённый файл текстовой инверсии в формате 🤗 Diffusers был сохранён под конкретным именем весов, например `text_inv.bin`. - Сохранённый файл текстовой инверсии в формате Automatic1111.
cache_dir (`str | os.PathLike`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.
force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.
proxies (`dict[str, str]`, *необязательный*) : Словарь прокси-серверов для использования по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.
local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.
hf_token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).
revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.
subfolder (`str`, *необязательный*, по умолчанию `""`) : Путь к подпапке, в которой находится файл модели в составе более крупного репозитория моделей на Hub или локально.
mirror (`str`, *необязательный*) : Зеркальный источник для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.
Загрузите эмбеддинги Textual Inversion в текстовый энкодер [StableDiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline) (поддерживаются форматы 🤗 Diffusers и Automatic1111).
Пример:
Для загрузки вектора встраивания Textual Inversion в формате 🤗 Diffusers:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("sd-concepts-library/cat-toy")
prompt = "A <cat-toy> backpack"
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("cat-backpack.png")
```
Чтобы загрузить вектор встраивания Textual Inversion в формате Automatic1111, сначала скачайте вектор (например, с [civitAI](https://civitai.com/models/3036?modelVersionId=9857)), а затем загрузите его
локально:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("./charturnerv2.pt", token="charturnerv2")
prompt = "charturnerv2, multiple views of the same character in the same outfit, a character turnaround of a woman wearing a black jacket and red shirt, best quality, intricate details."
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("character.png")
```
#### encode_prompt[[diffusers.StableDiffusionControlNetImg2ImgPipeline.encode_prompt]]
```python
encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_img2img.py#L276)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования
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`).
prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.
negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.
lora_scale (`float`, *необязательный*) : Масштаб LoRA, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.
clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.
Кодирует промпт в скрытые состояния текстового энкодера.
## StableDiffusionControlNetInpaintPipeline[[diffusers.StableDiffusionControlNetInpaintPipeline]]
#### diffusers.StableDiffusionControlNetInpaintPipeline[[diffusers.StableDiffusionControlNetInpaintPipeline]]
```python
diffusers.StableDiffusionControlNetInpaintPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_inpaint.py#L128)
**Параметры:**
vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/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/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.
unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : `UNet2DConditionModel` для удаления шума из закодированных латентов изображения.
controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet#diffusers.ControlNetModel) или `list[ControlNetModel]`) : Обеспечивает дополнительное условие для `unet` в процессе денойзинга. Если вы зададите несколько ControlNet в виде списка, выходы каждого ControlNet будут сложены вместе, чтобы создать одно объединённое дополнительное условие.
scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : планировщик, используемый в сочетании с `unet` для удаления шума из закодированных латентов изображения. Может быть одним из [DDIMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) или [PNDMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/pndm#diffusers.PNDMScheduler).
safety_checker (`StableDiffusionSafetyChecker`) : модуль классификации, оценивающий, могут ли сгенерированные изображения считаться оскорбительными или вредными. Подробности о потенциальных рисках модели см. в [карточке модели](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5).
feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : экземпляр `CLIPImageProcessor` для извлечения признаков из сгенерированных изображений; используется в качестве входных данных для `safety_checker`.
Пайплайн для инпейнтинга изображений с использованием Stable Diffusion и управления через ControlNet.
Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.
Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/v0.43.0/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/v0.43.0/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/v0.43.0/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров
> [!TIP] > Этот конвейер можно использовать с контрольными точками, специально дообученными для inpainting >
([stable-diffusion-v1-5/stable-diffusion-inpainting](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-inpainting))
> а также контрольные точки Stable Diffusion для генерации изображений по тексту по умолчанию >
([stable-diffusion-v1-5/stable-diffusion-v1-5](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5)).
> По умолчанию контрольные точки Stable Diffusion для генерации изображений по тексту могут быть предпочтительнее для ControlNet, прошедших дообучение
на > них, например [lllyasviel/control_v11p_sd15_inpaint](https://huggingface.co/lllyasviel/control_v11p_sd15_inpaint).
#### __call__[[diffusers.StableDiffusionControlNetInpaintPipeline.__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, 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]] = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None, strength: float = 1.0, num_inference_steps: int = 50, guidance_scale: float = 7.5, negative_prompt: 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, 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.5, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, 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/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_inpaint.py#L994)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.
image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, : `list[PIL.Image.Image]`, or `list[np.ndarray]`): `Image`, массив NumPy или тензор, представляющие пакет изображений, который будет использоваться в качестве начальной точки. Для массива NumPy и тензора PyTorch ожидаемый диапазон значений составляет `[0, 1]`. Если это тензор или список тензоров, ожидаемая форма должна быть `(B, C, H, W)` или `(C, H, W)`. Если это массив NumPy или список массивов, ожидаемая форма должна быть `(B, H, W, C)` или `(H, W, C)`. Также можно передавать латенты изображений в качестве `image`, но при прямой передаче латентов они не кодируются повторно.
mask_image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, : `list[PIL.Image.Image]`, или `list[np.ndarray]`): `Image`, массив NumPy или тензор, представляющие пакет изображений для маскирования `image`. Белые пиксели в маске перекрашиваются, а чёрные сохраняются. Если `mask_image` — это изображение PIL, оно преобразуется в одноцветный (яркостной) канал перед использованием. Если это массив NumPy или тензор PyTorch, он должен содержать один цветовой канал (L) вместо трёх, поэтому ожидаемая форма для тензора PyTorch — `(B, 1, H, W)`, `(B, H, W)`, `(1, H, W)`, `(H, W)`. А для массива NumPy — `(B, H, W, 1)`, `(B, H, W)`, `(H, W, 1)` или `(H, W)`.
control_image (`torch.Tensor`, `PIL.Image.Image`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, : `list[list[torch.Tensor]]` или `list[list[PIL.Image.Image]]`): входное условие ControlNet, задающее направление для `unet` при генерации. Если тип указан как `torch.Tensor`, значение передаётся в ControlNet без изменений. В качестве изображения также принимается `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения необходимо передавать в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в батч для входа в один ControlNet.
height (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях.
width (`int`, *необязательный*, по умолчанию `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*, по умолчанию 1.0) : Определяет степень трансформации исходного `image`. Значение должно быть в диапазоне от 0 до 1. `image` используется как отправная точка, и чем выше `strength`, тем больше шума добавляется. Количество шагов денойзинга зависит от количества шума, добавленного изначально. Когда `strength` равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в `num_inference_steps`. Значение 1 фактически игнорирует `image`.
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`).
num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.
eta (`float`, *необязательный*, по умолчанию 0.0) : Соответствует параметру eta (η) из статьи [DDIM](https://huggingface.co/papers/2010.02502). Применяется только к [DDIMScheduler](/docs/diffusers/v0.43.0/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`.
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/v0.43.0/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]`, *необязательный*, по умолчанию 0.5) : Выходные данные 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 прекращает применяться.
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/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) или `tuple`
Если `return_dict` равно `True`, возвращается [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список сгенерированных изображений, а второй — список значений `bool`, указывающих, содержит ли соответствующее сгенерированное изображение контент, нежелательный для просмотра на рабочем месте (nsfw).
Функция вызова конвейера для генерации.
Примеры:
```py
>>> # !pip install transformers accelerate
>>> from diffusers import StableDiffusionControlNetInpaintPipeline, ControlNetModel, DDIMScheduler
>>> from diffusers.utils import load_image
>>> import numpy as np
>>> import torch
>>> init_image = load_image(
... "https://huggingface.co/datasets/diffusers/test-arrays/resolve/main/stable_diffusion_inpaint/boy.png"
... )
>>> init_image = init_image.resize((512, 512))
>>> generator = torch.Generator(device="cpu").manual_seed(1)
>>> mask_image = load_image(
... "https://huggingface.co/datasets/diffusers/test-arrays/resolve/main/stable_diffusion_inpaint/boy_mask.png"
... )
>>> mask_image = mask_image.resize((512, 512))
>>> def make_canny_condition(image):
... image = np.array(image)
... image = cv2.Canny(image, 100, 200)
... image = image[:, :, None]
... image = np.concatenate([image, image, image], axis=2)
... image = Image.fromarray(image)
... return image
>>> control_image = make_canny_condition(init_image)
>>> controlnet = ControlNetModel.from_pretrained(
... "lllyasviel/control_v11p_sd15_inpaint", torch_dtype=torch.float16
... )
>>> pipe = StableDiffusionControlNetInpaintPipeline.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.scheduler = DDIMScheduler.from_config(pipe.scheduler.config)
>>> pipe.enable_model_cpu_offload()
>>> # generate image
>>> image = pipe(
... "a handsome man with ray-ban sunglasses",
... num_inference_steps=20,
... generator=generator,
... eta=1.0,
... image=init_image,
... mask_image=mask_image,
... control_image=control_image,
... ).images[0]
```
#### enable_attention_slicing[[diffusers.StableDiffusionControlNetInpaintPipeline.enable_attention_slicing]]
```python
enable_attention_slicing(slice_size: str | int = 'auto')
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetInpaintPipeline.disable_attention_slicing]]
```python
disable_attention_slicing()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2067)
Отключает вычисление внимания с нарезкой. Если `enable_attention_slicing` был вызван ранее, внимание вычисляется за один шаг.
#### enable_xformers_memory_efficient_attention[[diffusers.StableDiffusionControlNetInpaintPipeline.enable_xformers_memory_efficient_attention]]
```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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.StableDiffusionControlNetInpaintPipeline.disable_xformers_memory_efficient_attention]]
```python
disable_xformers_memory_efficient_attention()
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2006)
Отключить энергоэффективное внимание из [xFormers](https://facebookresearch.github.io/xformers/).
#### load_textual_inversion[[diffusers.StableDiffusionControlNetInpaintPipeline.load_textual_inversion]]
```python
load_textual_inversion(pretrained_model_name_or_path: str | list[str] | dict[str, torch.Tensor] | list[dict[str, torch.Tensor]], token: str | list[str] | None = None, tokenizer: 'PreTrainedTokenizer' | None = None, text_encoder: 'PreTrainedModel' | None = None, **kwargs)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L271)
**Параметры:**
pretrained_model_name_or_path (`str` или `os.PathLike` или `list[str or os.PathLike]` или `Dict` или `list[Dict]`) : Может быть одним из следующих вариантов или списком таких вариантов: - Строка, *model id* (например, `sd-concepts-library/low-poly-hd-logos-icons`) предобученной модели, размещенной на Hub. - Путь к *каталогу* (например, `./my_text_inversion_directory/`), содержащему веса textual inversion. - Путь к *файлу* (например, `./my_text_inversions.pt`), содержащему веса textual inversion. - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).
token (`str` или `list[str]`, *необязательный*) : Переопределяет токен, используемый для весов текстовой инверсии. Если `pretrained_model_name_or_path` является списком, то `token` также должен быть списком той же длины.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel), *необязательный*) : Замороженный текстовый энкодер ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). Если не указан, функция использует self.tokenizer.
tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer), *необязательный*) : `CLIPTokenizer` для токенизации текста. Если не указан, функция использует self.tokenizer.
weight_name (`str`, *необязательный*) : Имя файла с кастомными весами. Это следует использовать, когда: - Сохранённый файл текстовой инверсии в формате 🤗 Diffusers был сохранён под конкретным именем весов, например `text_inv.bin`. - Сохранённый файл текстовой инверсии в формате Automatic1111.
cache_dir (`str | os.PathLike`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.
force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.
proxies (`dict[str, str]`, *необязательный*) : Словарь прокси-серверов для использования по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.
local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.
hf_token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).
revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.
subfolder (`str`, *необязательный*, по умолчанию `""`) : Путь к подпапке, в которой находится файл модели в составе более крупного репозитория моделей на Hub или локально.
mirror (`str`, *необязательный*) : Зеркальный источник для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.
Загрузите эмбеддинги Textual Inversion в текстовый энкодер [StableDiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline) (поддерживаются форматы 🤗 Diffusers и Automatic1111).
Пример:
Для загрузки вектора встраивания Textual Inversion в формате 🤗 Diffusers:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("sd-concepts-library/cat-toy")
prompt = "A <cat-toy> backpack"
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("cat-backpack.png")
```
Чтобы загрузить вектор встраивания Textual Inversion в формате Automatic1111, сначала скачайте вектор (например, с [civitAI](https://civitai.com/models/3036?modelVersionId=9857)), а затем загрузите его
локально:
```py
from diffusers import StableDiffusionPipeline
import torch
model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")
pipe.load_textual_inversion("./charturnerv2.pt", token="charturnerv2")
prompt = "charturnerv2, multiple views of the same character in the same outfit, a character turnaround of a woman wearing a black jacket and red shirt, best quality, intricate details."
image = pipe(prompt, num_inference_steps=50).images[0]
image.save("character.png")
```
#### encode_prompt[[diffusers.StableDiffusionControlNetInpaintPipeline.encode_prompt]]
```python
encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet_inpaint.py#L282)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования
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`).
prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.
negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.
lora_scale (`float`, *необязательный*) : Масштаб LoRA, который будет применён ко всем слоям LoRA текстового энкодера, если слои LoRA загружены.
clip_skip (`int`, *optional*) : Количество слоев, которые пропускаются в CLIP при вычислении эмбеддингов промпта. Значение 1 означает, что для вычисления эмбеддингов промпта будет использоваться выход предпоследнего слоя.
Кодирует промпт в скрытые состояния текстового энкодера.
## 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/v0.43.0/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.
# ControlNet
ControlNet был представлен в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala.
С помощью модели ControlNet можно передать дополнительное управляющее изображение для настройки и управления генерацией в Stable Diffusion. Например, если вы предоставите карту глубины, модель ControlNet сгенерирует изображение, сохраняющее пространственную информацию из карты глубины. Это более гибкий и точный способ управления процессом генерации изображений.
Аннотация из статьи:
*Мы представляем ControlNet — архитектуру нейронной сети для добавления пространственного управления условиями к крупным предобученным диффузионным моделям «текст в изображение». ControlNet фиксирует готовые к производству крупные диффузионные модели и повторно использует их глубокие и устойчивые слои кодирования, предобученные на миллиардах изображений, в качестве мощного каркаса для обучения разнообразному набору условных контролей. Нейронная архитектура соединяется с «нулевыми свёртками» (слоями свёртки с нулевой инициализацией), которые постепенно наращивают параметры от нуля и гарантируют, что вредоносный шум не может повлиять на дообучение. Мы тестируем различные условные контроли, например, края, глубину, сегментацию, позу человека и т. д., с Stable Diffusion, используя одно или несколько условий, с промптами или без них. Мы показываем, что обучение ControlNet устойчиво как на малых (<50k), так и на больших (>1m) наборах данных. Обширные результаты демонстрируют, что ControlNet может способствовать более широкому применению для управления диффузионными моделями изображений.*
Эта модель была добавлена пользователем [takuma104](https://huggingface.co/takuma104). ❤️
Исходный код можно найти в репозитории [lllyasviel/ControlNet](https://github.com/lllyasviel/ControlNet), а официальные контрольные точки ControlNet — на профиле [lllyasviel](https://huggingface.co/lllyasviel) в Hub.
> [!TIP]
> Обязательно ознакомьтесь с [руководством по планировщикам](../../using-diffusers/schedulers), чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом [повторное использование компонентов в разных конвейерах](../../using-diffusers/loading#reusing-models-in-multiple-pipelines), чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.
## StableDiffusionControlNetPipeline[[diffusers.StableDiffusionControlNetPipeline]]
#### diffusers.StableDiffusionControlNetPipeline[[diffusers.StableDiffusionControlNetPipeline]]
```python
diffusers.StableDiffusionControlNetPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet.ControlNetModel | list[diffusers.models.controlnets.controlnet.ControlNetModel] | tuple[diffusers.models.controlnets.controlnet.ControlNetModel] | diffusers.models.controlnets.multicontrolnet.MultiControlNetModel, scheduler: KarrasDiffusionSchedulers, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection = None, requires_safety_checker: bool = True)
```
[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L162)
**Параметры:**
vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.
text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/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/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.
unet ([UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : `UNet2DConditionModel` для удаления шума из закодированных латентов изображения.
controlnet ([ControlNetModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet#diffusers.ControlNetModel) или `list[ControlNetModel]`) : Обеспечивает дополнительное условие для `unet` в процессе денойзинга. Если вы зададите несколько ControlNet в виде списка, выходы каждого ControlNet будут сложены вместе, чтобы создать одно объединённое дополнительное условие.
scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : планировщик, используемый в сочетании с `unet` для удаления шума из закодированных латентов изображения. Может быть одним из [DDIMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler) или [PNDMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/pndm#diffusers.PNDMScheduler).
safety_checker (`StableDiffusionSafetyChecker`) : модуль классификации, оценивающий, могут ли сгенерированные изображения считаться оскорбительными или вредными. Подробности о потенциальных рисках модели см. в [карточке модели](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5).
feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : экземпляр `CLIPImageProcessor` для извлечения признаков из сгенерированных изображений; используется в качестве входных данных для `safety_checker`.
Пайплайн для генерации изображений по тексту с использованием Stable Diffusion и управления через ControlNet.
Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.
Пайплайн также наследует следующие методы загрузки:
- [load_textual_inversion()](/docs/diffusers/v0.43.0/ru/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion) для загрузки эмбеддингов текстовой инверсии
- [load_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights) для загрузки весов LoRA
- [save_lora_weights()](/docs/diffusers/v0.43.0/ru/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights) для сохранения весов LoRA
- [from_single_file()](/docs/diffusers/v0.43.0/ru/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) для загрузки файлов `.ckpt`
- [load_ip_adapter()](/docs/diffusers/v0.43.0/ru/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter) для загрузки IP-адаптеров
#### __call__[[diffusers.StableDiffusionControlNetPipeline.__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, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 7.5, negative_prompt: 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, 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, 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/v0.43.0/src/diffusers/pipelines/controlnet/pipeline_controlnet.py#L907)
**Параметры:**
prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.
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]]` or `list[list[PIL.Image.Image]]`): Вводное условие ControlNet для предоставления руководящих сигналов `unet` при генерации. Если тип указан как `torch.Tensor`, он передается в ControlNet без изменений. В качестве изображения также допускается `PIL.Image.Image`. Размеры выходного изображения по умолчанию совпадают с размерами `image`. Если переданы высота и/или ширина, `image` масштабируется соответственно. Если в `init` указано несколько ControlNet, изображения должны передаваться в виде списка, чтобы каждый элемент списка мог быть корректно сгруппирован в пакет для ввода в один ControlNet. Если `prompt` является списком, и для одного ControlNet передан список изображений, каждое изображение будет сопоставлено с каждым промптом из списка `prompt`. То же самое относится и к нескольким ControlNet, где можно передать список списков изображений для пакетирования по каждому промпту и каждому ControlNet.
height (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях.
width (`int`, *необязательный*, по умолчанию `self.unet.config.sample_size * self.vae_scale_factor`) : Ширина генерируемого изображения в пикселях.
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`.
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`).
num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.
eta (`float`, *необязательный*, по умолчанию 0.0) : Соответствует параметру eta (η) из статьи [DDIM](https://huggingface.co/papers/2010.02502). Применяется только к [DDIMScheduler](/docs/diffusers/v0.43.0/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`.
ip_adapter_image : (`PipelineImageInput`, *необязательный*): Необязательное входное изображение для работы с IP-адаптерами.
Xet Storage Details
- Size:
- 125 kB
- Xet hash:
- 7ac7631b1b1a5e35fe7c9e927a0ab1f3d7a6effa58926001707a86fe7bb3362e
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.