Hugging Face's logo

Diffusers documentation

SparseControlNetModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

SparseControlNetModel

SparseControlNetModel — это реализация ControlNet для AnimateDiff.

ControlNet был представлен в статье Adding Conditional Control to Text-to-Image Diffusion Models авторами Lvmin Zhang, Anyi Rao и Maneesh Agrawala.

Версия ControlNet SparseCtrl была представлена в статье SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models для достижения контролируемой генерации в диффузионных моделях «текст-в-видео» авторами Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin и Bo Dai.

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

Развитие технологий генерации видео по тексту (T2V), то есть создания видео по заданному текстовому запросу, значительно продвинулось в последние годы. Однако опора исключительно на текстовые запросы часто приводит к неоднозначной композиции кадров из-за пространственной неопределённости. В связи с этим исследовательское сообщество использует плотные структурные сигналы, например, последовательности глубины или контуров для каждого кадра, чтобы повысить управляемость, что, соответственно, увеличивает нагрузку на этап инференса. В данной работе мы представляем SparseCtrl, который обеспечивает гибкое структурное управление с помощью временных разреженных сигналов, требуя лишь одного или нескольких входных данных, как показано на рисунке 1. Он включает дополнительный кодировщик условий для обработки этих разреженных сигналов, при этом предварительно обученная T2V-модель остаётся неизменной. Предложенный подход совместим с различными модальностями, включая эскизы, карты глубины и RGB-изображения, что обеспечивает более практичное управление генерацией видео и способствует применению таких задач, как раскадровка, рендеринг глубины, анимация по ключевым кадрам и интерполяция. Обширные эксперименты демонстрируют обобщающую способность SparseCtrl как для оригинальных, так и для персонализированных T2V-генераторов. Код и модели будут общедоступны по этой ссылке.

Пример загрузки SparseControlNetModel

import torch
from diffusers import SparseControlNetModel

# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)

# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)

# For loading fp16 variant, pass `variant="fp16"` as an additional parameter

SparseControlNetModel

класс diffusers.SparseControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')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 = 768transformer_layers_per_block: int | tuple[int, ...] = 1transformer_layers_per_mid_block: int | tuple[int] | None = Nonetemporal_transformer_layers_per_block: int | tuple[int, ...] = 1attention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falsecontrolnet_conditioning_channel_order: str = 'rgb'motion_max_seq_length: int = 32motion_num_attention_heads: int = 8concat_conditioning_mask: bool = Trueuse_simplified_condition_embedding: bool = True )

Параметры

  • in_channels (int, по умолчанию 4) — Количество каналов во входном образце.
  • conditioning_channels (int, по умолчанию 4) — Количество входных каналов в модуле условного встраивания controlnet. Если concat_condition_embedding равно True, значение, указанное здесь, увеличивается на 1.
  • 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.
  • transformer_layers_per_mid_block (int or tuple[int], необязательный, по умолчанию 1) — Количество трансформерных слоев, используемых в каждом слое среднего блока.
  • attention_head_dim (int или tuple[int], по умолчанию 8) — Размерность головок внимания.
  • num_attention_heads (int или tuple[int], необязательный) — Количество голов, используемых для многоголовного внимания.
  • use_linear_projection (bool, по умолчанию False) —
  • upcast_attention (bool, по умолчанию False) —
  • resnet_time_scale_shift (str, по умолчанию "default") — Конфигурация сдвига масштаба времени для блоков ResNet (см. ResnetBlock2D). Выберите default или scale_shift.
  • conditioning_embedding_out_channels (tuple[int], по умолчанию (16, 32, 96, 256)) — Кортеж количества выходных каналов для каждого блока в слое conditioning_embedding.
  • global_pool_conditions (bool, по умолчанию False) — TODO(Patrick) - неиспользуемый параметр
  • controlnet_conditioning_channel_order (str, по умолчанию rgb) —
  • motion_max_seq_length (int, по умолчанию 32) — Максимальная длина последовательности, используемая в модуле движения.
  • motion_num_attention_heads (int или tuple[int], по умолчанию 8) — Количество голок, используемых в каждом слое внимания модуля движения.
  • concat_conditioning_mask (bool, по умолчанию True) —
  • use_simplified_condition_embedding (bool, по умолчанию True) —

Модель SparseControlNet, описанная в статье SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models.

forward

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0timestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneconditioning_mask: typing.Optional[torch.Tensor] = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.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.
  • 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), которое добавляет большие отрицательные значения к оценкам внимания, соответствующим токенам, помеченным как «отбросить».
  • conditioning_mask (torch.Tensor, необязательный, по умолчанию None) — Необязательная маска, указывающая, какие кадры в controlnet_cond являются валидными кадрами для условного управления.
  • cross_attention_kwargs (dict[str], необязательный, по умолчанию None) — Словарь kwargs, который при указании передается в AttnProcessor.
  • 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 модели SparseControlNetModel.

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, которые нужно скопировать в SparseControlNetModel. Все применимые параметры конфигурации также копируются.

Создайте экземпляр SparseControlNetModel из 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

< >

( )

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

SparseControlNetOutput

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

< >

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

Вывод SparseControlNetModel.

Update on GitHub

←SD3ControlNetModel AceStepTransformer1DModel→