# ControlNetUnionModel

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

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

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

## Загрузка

По умолчанию [ControlNetUnionModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel) следует загружать с помощью [from_pretrained()](/docs/diffusers/v0.43.0/ru/api/models/overview#diffusers.ModelMixin.from_pretrained).

```py
from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel

controlnet = ControlNetUnionModel.from_pretrained("xinsir/controlnet-union-sdxl-1.0")
pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet)
```

## ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

#### diffusers.ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

```python
diffusers.ControlNetUnionModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 1280, transformer_layers_per_block: int | tuple[int, ...] = 1, encoder_hid_dim: int | None = None, encoder_hid_dim_type: str | None = None, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, class_embed_type: str | None = None, addition_embed_type: str | None = None, addition_time_embed_dim: int | None = None, num_class_embeds: int | None = None, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', projection_class_embeddings_input_dim: int | None = None, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (48, 96, 192, 384), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64, num_control_type: int = 6, num_trans_channel: int = 320, num_trans_head: int = 8, num_trans_layer: int = 1, num_proj_channel: int = 320)
```

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

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

in_channels (`int`, по умолчанию 4) : Количество каналов во входном образце.

flip_sin_to_cos (`bool`, по умолчанию `True`) : Нужно ли заменить sin на cos во временном эмбеддинге.

freq_shift (`int`, по умолчанию 0) : Сдвиг частоты, применяемый к временному эмбеддингу.

down_block_types (`tuple[str]`, по умолчанию `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Кортеж блоков downsampling, которые следует использовать.

only_cross_attention (`bool | tuple[bool]`, по умолчанию `False`) --

block_out_channels (`tuple[int]`, по умолчанию `(320, 640, 1280, 1280)`) : Кортеж количества выходных каналов для каждого блока.

layers_per_block (`int`, по умолчанию 2) : Количество слоёв в каждом блоке.

downsample_padding (`int`, по умолчанию 1) : Отступ (padding), используемый для свёртки при уменьшении разрешения.

mid_block_scale_factor (`float`, по умолчанию 1) : Коэффициент масштабирования для среднего блока.

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

norm_num_groups (`int`, *optional*, по умолчанию 32) : Количество групп, используемых для нормализации. Если значение равно None, слои нормализации и активации пропускаются на этапе постобработки.

norm_eps (`float`, по умолчанию 1e-5) : Эпсилон, используемый для нормализации.

cross_attention_dim (`int`, по умолчанию 1280) : Размерность признаков кросс-внимания.

transformer_layers_per_block (`int` или `tuple[int]`, *необязательный*, по умолчанию 1) : Количество блоков трансформера типа `BasicTransformerBlock`. Актуально только для `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

encoder_hid_dim (`int`, *optional*, по умолчанию None) : Если `encoder_hid_dim_type` определено, `encoder_hidden_states` будет проецировано из размерности `encoder_hid_dim` в `cross_attention_dim`.

encoder_hid_dim_type (`str`, *необязательный*, по умолчанию `None`) : Если указано, `encoder_hidden_states` и, возможно, другие эмбеддинги проецируются в эмбеддинги текста размерности `cross_attention` в соответствии с `encoder_hid_dim_type`.

attention_head_dim (`int | tuple[int]`, по умолчанию 8) : Размерность головок внимания.

use_linear_projection (`bool`, по умолчанию `False`) --

class_embed_type (`str`, *необязательный*, по умолчанию `None`) : Тип классовой эмбеддинга, который в итоге суммируется с временными эмбеддингами. Выберите одно из значений: None, `"timestep"`, `"identity"`, `"projection"` или `"simple_projection"`.

addition_embed_type (`str`, *необязательный*, по умолчанию `None`) : Настройка необязательного эмбеддинга, который будет складываться с временными эмбеддингами. Выберите `None` или "text". Значение "text" использует слой `TextTimeEmbedding`.

num_class_embeds (`int`, *optional*, по умолчанию 0) : Входное измерение обучаемой матрицы эмбеддингов, которая проецируется в `time_embed_dim` при выполнении классовой обусловленности с `class_embed_type`, равным `None`.

upcast_attention (`bool`, по умолчанию `False`) --

resnet_time_scale_shift (`str`, по умолчанию `"default"`) : Настройка сдвига масштаба времени для блоков ResNet (см. `ResnetBlock2D`). Выберите `default` или `scale_shift`.

projection_class_embeddings_input_dim (`int`, *необязательный*, по умолчанию `None`) : размерность входа `class_labels`, когда `class_embed_type="projection"`. Обязателен, когда `class_embed_type="projection"`.

controlnet_conditioning_channel_order (`str`, по умолчанию `"rgb"`) : Порядок каналов условного изображения. Если порядок `bgr`, он будет преобразован в `rgb`.

conditioning_embedding_out_channels (`tuple[int]`, *optional*, по умолчанию `(48, 96, 192, 384)`) : Кортеж количества выходных каналов для каждого блока в слое `conditioning_embedding`.

global_pool_conditions (`bool`, по умолчанию `False`) --

Модель ControlNetUnion.

#### forward[[diffusers.ControlNetUnionModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: list[torch.Tensor], control_type: Tensor, control_type_idx: list[int], conditioning_scale: float | list[float] = 1.0, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, from_multi: bool = False, guess_mode: bool = False, return_dict: bool = True)
```

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

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

sample (`torch.Tensor`) : Шумовой входной тензор.

timestep (`torch.Tensor | float | int`) : Количество шагов для денойзинга входных данных.

encoder_hidden_states (`torch.Tensor`) : Скрытые состояния энкодера.

controlnet_cond (`list[torch.Tensor]`) : Условные входные тензоры.

control_type (`torch.Tensor`) : тензор формы `(batch, num_control_type)` со значениями `0` или `1` в зависимости от того, используется ли данный тип управления.

control_type_idx (`list[int]`) : Индексы `control_type`.

conditioning_scale (`float`, по умолчанию `1.0`) : Коэффициент масштабирования для выходов ControlNet.

class_labels (`torch.Tensor`, *необязательный*, по умолчанию `None`) : Необязательные классы меток для условного формирования. Их эмбеддинги будут сложены с эмбеддингами временного шага.

timestep_cond (`torch.Tensor`, *необязательный*, по умолчанию `None`) : Дополнительные условные эмбеддинги для временного шага. Если предоставлены, эмбеддинги будут сложены с timestep_embedding, переданным через слой `self.time_embedding`, чтобы получить итоговые эмбеддинги временного шага.

attention_mask (`torch.Tensor`, *необязательный*, по умолчанию `None`) : маска внимания формы `(batch, key_tokens)` применяется к `encoder_hidden_states`. Если значение равно `1`, маска сохраняется, иначе, если равно `0`, она отбрасывается. Маска преобразуется в смещение (bias), которое добавляет большие отрицательные значения к оценкам внимания, соответствующим токенам, подлежащим отбрасыванию.

added_cond_kwargs (`dict`) : Дополнительные условия для UNet в Stable Diffusion XL.

cross_attention_kwargs (`dict[str]`, *необязательный*, по умолчанию `None`) : Словарь kwargs, который при указании передается в `AttnProcessor`.

from_multi (`bool`, по умолчанию `False`) : Использовать стандартное масштабирование при вызове из `MultiControlNetUnionModel`.

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

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

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

Если `return_dict` равно `True`, возвращается `~models.controlnet.ControlNetOutput`, иначе возвращается кортеж, первым элементом которого является тензор сэмпла.

Метод forward модели [ControlNetUnionModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel).

#### from_unet[[diffusers.ControlNetUnionModel.from_unet]]

```python
from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True)
```

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

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

unet (`UNet2DConditionModel`) : веса модели UNet, которые нужно скопировать в [ControlNetUnionModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel). Все применимые параметры конфигурации также копируются.

Создайте экземпляр [ControlNetUnionModel](/docs/diffusers/v0.43.0/ru/api/models/controlnet_union#diffusers.ControlNetUnionModel) из [UNet2DConditionModel](/docs/diffusers/v0.43.0/ru/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.ControlNetUnionModel.set_attention_slice]]

```python
set_attention_slice(slice_size: str | int | list[int])
```

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

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

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

Включить вычисление внимания с нарезкой.

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

#### set_default_attn_processor[[diffusers.ControlNetUnionModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

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

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