# SD3ControlNetModel

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

Модель ControlNet была представлена в статье [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) авторами Lvmin Zhang, Anyi Rao, Maneesh Agrawala. Она обеспечивает более высокий уровень контроля над генерацией изображений по тексту, позволяя моделировать модель на основе дополнительных входных данных, таких как карты границ, карты глубины, карты сегментации и ключевые точки для определения позы.

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

*Мы представляем ControlNet — архитектуру нейронной сети для добавления пространственного управления условиями к крупным предобученным диффузионным моделям «текст в изображение». ControlNet фиксирует готовые к производству крупные диффузионные модели и повторно использует их глубокие и устойчивые слои кодирования, предобученные на миллиардах изображений, в качестве мощного каркаса для обучения разнообразному набору условных контролей. Нейронная архитектура соединяется с «нулевыми свёртками» (слоями свёртки с нулевой инициализацией), которые постепенно наращивают параметры от нуля и гарантируют, что вредоносный шум не может повлиять на дообучение. Мы тестируем различные условные контроли, например, края, глубину, сегментацию, позу человека и т. д., с Stable Diffusion, используя одно или несколько условий, с промптами или без них. Мы показываем, что обучение ControlNet устойчиво как на малых (<50k), так и на больших (>1m) наборах данных. Обширные результаты демонстрируют, что ControlNet может способствовать более широкому применению для управления диффузионными моделями изображений.*

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

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

```py
from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel

controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)
```

## SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

#### diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

```python
diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, attention_head_dim: int = 64, num_attention_heads: int = 18, joint_attention_dim: int = 4096, caption_projection_dim: int = 1152, pooled_projection_dim: int = 2048, out_channels: int = 16, pos_embed_max_size: int = 96, extra_conditioning_channels: int = 0, dual_attention_layers: tuple[int, ...] = (), qk_norm: str | None = None, pos_embed_type: str | None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)
```

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

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

sample_size (`int`, по умолчанию `128`) : Ширина/высота латентов. Это значение фиксировано во время обучения, поскольку используется для обучения набора позиционных эмбеддингов.

patch_size (`int`, по умолчанию `2`) : Размер патча для разбиения входных данных на небольшие патчи.

in_channels (`int`, по умолчанию `16`) : Количество латентных каналов на входе.

num_layers (`int`, по умолчанию `18`) : Количество используемых блоков трансформера.

attention_head_dim (`int`, по умолчанию `64`) : Количество каналов в каждой голове.

num_attention_heads (`int`, по умолчанию `18`) : Количество головок для использования в механизме внимания с несколькими головками.

joint_attention_dim (`int`, по умолчанию `4096`) : Размерность эмбеддинга, используемая для совместного внимания текста и изображения.

caption_projection_dim (`int`, по умолчанию `1152`) : Размерность встраиваний подписей.

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

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

pos_embed_max_size (`int`, по умолчанию `96`) : Максимальная высота/ширина латентных векторов позиционных эмбеддингов.

extra_conditioning_channels (`int`, по умолчанию `0`) : Количество дополнительных каналов, используемых для условного формирования в patch embedding.

dual_attention_layers (`tuple[int, ...]`, по умолчанию `()`) : Количество блоков трансформера с двойным потоком, которые следует использовать.

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

pos_embed_type (`str`, по умолчанию `"sincos"`) : Тип позиционного кодирования. Выберите между `"sincos"` и `None`.

use_pos_embed (`bool`, по умолчанию `True`) : Использовать ли позиционные эмбеддинги.

force_zeros_for_pooled_projection (`bool`, по умолчанию `True`) : Нужно ли принудительно обнулять пул-проекционные эмбеддинги. Это обрабатывается в пайплайнах путём чтения значения конфигурации модели ControlNet.

Модель ControlNet для [Stable Diffusion 3](https://huggingface.co/papers/2403.03206).

#### enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]

```python
enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)
```

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

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

chunk_size (`int`, *optional*) : Размер блока для полносвязных слоёв. Если не указан, полносвязный слой будет выполняться отдельно для каждого тензора с dim=`dim`.

dim (`int`, *optional*, по умолчанию `0`) : Размерность, по которой вычисления в feed-forward слое должны быть разбиты на блоки. Выберите dim=0 (batch) или dim=1 (длина последовательности).

Устанавливает процессор внимания для использования [feed forward chunking](https://huggingface.co/blog/reformer#2-chunked-feed-forward-layers).

#### forward[[diffusers.SD3ControlNetModel.forward]]

```python
forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

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

hidden_states (`torch.Tensor` формы `(batch size, channel, height, width)`) : Входные `hidden_states`.

controlnet_cond (`torch.Tensor`) : Условный входной тензор формы `(batch_size, sequence_length, hidden_size)`.

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

encoder_hidden_states (`torch.Tensor` формы `(batch size, sequence_len, embed_dims)`) : Условные эмбеддинги (эмбеддинги, вычисленные на основе входных условий, таких как промпты), которые следует использовать.

pooled_projections (`torch.Tensor` формы `(batch_size, projection_dim)`) : Векторы, полученные из эмбеддингов входных условий.

timestep ( `torch.LongTensor`) : Используется для указания шага денойзинга.

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

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

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

Если `return_dict` равно True, возвращается `~models.transformer_2d.Transformer2DModelOutput`, иначе — `tuple`, первым элементом которого является тензор выборки.

Метод forward модели [SD3Transformer2DModel](/docs/diffusers/main/ru/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel).

#### fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

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

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

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

#### unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

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

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

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

## SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

#### diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

```python
diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple[torch.Tensor])
```

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