Hugging Face's logo

Diffusers documentation

ControlNetModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNetModel

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

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

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

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

По умолчанию ControlNetModel следует загружать с помощью from_pretrained(), но его также можно загрузить из исходного формата, используя FromOriginalModelMixin.from_single_file, следующим образом:

from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth"  # can also be a local path
controlnet = ControlNetModel.from_single_file(url)

url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors"  # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)

Загрузка из Control LoRA

Control-LoRA был представлен Stability AI в stabilityai/control-lora путём добавления параметрически эффективной дообучения с низким рангом к ControlNet. Этот подход предлагает более эффективный и компактный способ обеспечить управление моделью на более широком спектре потребительских GPU.

from diffusers import ControlNetModel, UNet2DConditionModel

lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)

ControlNetModel

класс diffusers.ControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')mid_block_type: str | None = 'UNetMidBlock2DCrossAttn'only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 1280transformer_layers_per_block: int | tuple[int, ...] = 1encoder_hid_dim: int | None = Noneencoder_hid_dim_type: str | None = Noneattention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseclass_embed_type: str | None = Noneaddition_embed_type: str | None = Noneaddition_time_embed_dim: int | None = Nonenum_class_embeds: int | None = Noneupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'projection_class_embeddings_input_dim: int | None = Nonecontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falseaddition_embed_type_num_heads: int = 64 )

Параметры

  • 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")) — Кортеж блоков понижающего дискретизирования, которые следует использовать.
  • 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, необязательный, по умолчанию 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, необязательный, по умолчанию 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, необязательный, по умолчанию 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], необязательный, по умолчанию (16, 32, 96, 256)) — Кортеж количества выходных каналов для каждого блока в слое conditioning_embedding.
  • global_pool_conditions (bool, по умолчанию False) — TODO(Patrick) - неиспользуемый параметр.
  • addition_embed_type_num_heads (int, по умолчанию 64) — Количество головок, используемых в слое TextTimeEmbedding.

Модель ControlNet.

forward

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0class_labels: typing.Optional[torch.Tensor] = Nonetimestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneadded_cond_kwargs: dict[str, torch.Tensor] | None = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ControlNetOutput or tuple

Параметры

  • sample (torch.Tensor) — Шумовой входной тензор.
  • timestep (torch.Tensor | float | int) — Количество шагов для удаления шума из входных данных.
  • encoder_hidden_states (torch.Tensor) — Скрытые состояния энкодера.
  • controlnet_cond (torch.Tensor) — Условный входной тензор формы (batch_size, sequence_length, hidden_size).
  • conditioning_scale (float, по умолчанию 1.0) — Коэффициент масштабирования для выходов ControlNet.
  • class_labels (torch.Tensor, необязательный, по умолчанию None) — Необязательные метки классов для условного формирования. Их эмбеддинги будут сложены с эмбеддингами временного шага.
  • timestep_cond (torch.Tensor, необязательный, по умолчанию None) — Дополнительные условные эмбеддинги для timestep. Если переданы, эмбеддинги будут сложены с timestep_embedding, прошедшим через слой self.time_embedding, чтобы получить итоговые эмбеддинги timestep.
  • 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.
  • guess_mode (bool, по умолчанию False) — В этом режиме энкодер ControlNet прилагает все усилия, чтобы распознать содержимое входных данных, даже если вы удалите все промпты. Рекомендуется значение guidance_scale от 3.0 до 5.0.
  • return_dict (bool, по умолчанию True) — определяет, возвращать ли ControlNetOutput вместо обычного кортежа.

Возвращает

ControlNetOutput или tuple

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

Метод forward модели ControlNetModel.

from_unet

< >

( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )

Параметры

  • unet (UNet2DConditionModel) — Веса модели UNet, которые нужно скопировать в ControlNetModel. Все параметры конфигурации также копируются, где это применимо.

Создайте экземпляр ControlNetModel из UNet2DConditionModel.

set_attention_slice

< >

( slice_size: str | int | list[int] )

Параметры

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

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

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

set_default_attn_processor

< >

( )

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

ControlNetOutput

класс diffusers.models.controlnets.ControlNetOutput

< >

( down_block_res_samples: tuple[torch.Tensor]mid_block_res_sample: Tensor )

Параметры

  • down_block_res_samples (tuple[torch.Tensor]) — Кортеж активаций даунсемплинга для каждого блока даунсемплинга на разных разрешениях. Каждая тензорная величина должна иметь форму (batch_size, channel * resolution, height //resolution, width // resolution). Выходные данные можно использовать для условного формирования активаций даунсемплинга исходной UNet.
  • mid_down_block_re_sample (torch.Tensor) — Активация среднего блока (с наименьшим разрешением выборки). Каждый тензор должен иметь форму (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution). Результат можно использовать для условного воздействия на активацию среднего блока исходной UNet.

Вывод ControlNetModel.

Update on GitHub

←AutoModel ControlNetUnionModel→