Hugging Face's logo

Diffusers documentation

ControlNetModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNetModel

O modelo ControlNet foi introduzido em Adding Conditional Control to Text-to-Image Diffusion Models por Lvmin Zhang, Anyi Rao e Maneesh Agrawala. Ele oferece um maior grau de controle sobre a geração de imagens a partir de texto ao condicionar o modelo em entradas adicionais, como mapas de bordas, mapas de profundidade, mapas de segmentação e pontos-chave para detecção de pose.

O resumo do artigo é:

Apresentamos o ControlNet, uma arquitetura de rede neural para adicionar controles de condicionamento espacial a grandes modelos de difusão de texto para imagem pré-treinados. O ControlNet trava os grandes modelos de difusão prontos para produção e reutiliza suas camadas de codificação profundas e robustas, pré-treinadas com bilhões de imagens, como uma base forte para aprender um conjunto diversificado de controles condicionais. A arquitetura neural é conectada por “convoluções zero” (camadas de convolução inicializadas em zero) que crescem progressivamente os parâmetros a partir de zero e garantem que nenhum ruído prejudicial possa afetar o ajuste fino. Testamos vários controles de condicionamento, por exemplo, bordas, profundidade, segmentação, pose humana, etc., com o Stable Diffusion, usando condições únicas ou múltiplas, com ou sem prompts. Mostramos que o treinamento dos ControlNets é robusto com conjuntos de dados pequenos (<50k) e grandes (>1m). Resultados extensos mostram que o ControlNet pode facilitar aplicações mais amplas para controlar modelos de difusão de imagem.

Carregando do formato original

Por padrão, o ControlNetModel deve ser carregado com from_pretrained(), mas também pode ser carregado a partir do formato original usando FromOriginalModelMixin.from_single_file da seguinte forma:

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)

Carregando do Control LoRA

O Control-LoRA foi introduzido pela Stability AI em stabilityai/control-lora ao adicionar fine-tuning eficiente de parâmetros de baixa ordem ao ControlNet. Essa abordagem oferece um método mais eficiente e compacto para levar o controle do modelo a uma variedade mais ampla de GPUs de consumo.

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

classe diffusers.ControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')mid_block_type: str | None = 'UNetMidBlock2DCrossAttn'only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (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 )

Parâmetros

  • in_channels (int, padrão 4) — O número de canais na amostra de entrada.
  • flip_sin_to_cos (bool, padrão True) — Se deve inverter o sin para cos no embedding de tempo.
  • freq_shift (int, padrão 0) — O deslocamento de frequência a ser aplicado ao embedding de tempo.
  • down_block_types (tuple[str], padrão ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — A tupla de blocos de downsampling a serem usados.
  • only_cross_attention (bool | tuple[bool], padrão False) —
  • block_out_channels (tuple[int], padrão (320, 640, 1280, 1280)) — A tupla de canais de saída para cada bloco.
  • layers_per_block (int, padrão 2) — O número de camadas por bloco.
  • downsample_padding (int, padrão 1) — O padding a ser usado para a convolução de downsampling.
  • mid_block_scale_factor (float, padrão 1) — O fator de escala a ser usado para o bloco intermediário.
  • act_fn (str, padrão “silu”) — A função de ativação a ser utilizada.
  • norm_num_groups (int, opcional, padrão 32) — O número de grupos a serem usados para a normalização. Se for None, as camadas de normalização e ativação são ignoradas no pós-processamento.
  • norm_eps (float, padrão 1e-5) — O epsilon a ser usado para a normalização.
  • cross_attention_dim (int, padrão 1280) — A dimensão dos recursos de atenção cruzada.
  • transformer_layers_per_block (int ou tuple[int], opcional, padrão 1) — O número de blocos de transformador do tipo BasicTransformerBlock. Relevante apenas para ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn.
  • encoder_hid_dim (int, opcional, padrão None) — Se encoder_hid_dim_type estiver definido, encoder_hidden_states será projetado da dimensão encoder_hid_dim para cross_attention_dim.
  • encoder_hid_dim_type (str, opcional, padrão None) — Se fornecido, o encoder_hidden_states e possivelmente outros embeddings são projetados para baixo para embeddings de texto de dimensão cross_attention de acordo com encoder_hid_dim_type.
  • attention_head_dim (int | tuple[int], padrão 8) — A dimensão dos cabeçalhos de atenção.
  • use_linear_projection (bool, padrão False) —
  • class_embed_type (str, opcional, padrão None) — O tipo de incorporação de classe a ser usado, que é somado às incorporações de tempo. Escolha entre None, "timestep", "identity", "projection" ou "simple_projection".
  • addition_embed_type (str, opcional, padrão None) — Configura um embedding opcional que será somado aos embeddings de tempo. Escolha entre None ou “text”. “text” usará a camada TextTimeEmbedding.
  • num_class_embeds (int, opcional, padrão 0) — Dimensão de entrada da matriz de incorporação aprendível a ser projetada para time_embed_dim, ao realizar condicionamento por classe com class_embed_type igual a None.
  • upcast_attention (bool, padrão False) —
  • resnet_time_scale_shift (str, padrão "default") — Configuração de deslocamento de escala de tempo para blocos ResNet (veja ResnetBlock2D). Escolha entre default ou scale_shift.
  • projection_class_embeddings_input_dim (int, opcional, padrão None) — A dimensão da entrada class_labels quando class_embed_type="projection". Obrigatório quando class_embed_type="projection".
  • controlnet_conditioning_channel_order (str, padrão "rgb") — A ordem dos canais da imagem condicional. Será convertida para rgb se for bgr.
  • conditioning_embedding_out_channels (tuple[int], opcional, padrão (16, 32, 96, 256)) — A tupla de canais de saída para cada bloco na camada conditioning_embedding.
  • global_pool_conditions (bool, padrão False) — TODO(Patrick) - parâmetro não utilizado.
  • addition_embed_type_num_heads (int, padrão 64) — O número de cabeças a serem usadas na camada TextTimeEmbedding.

Um modelo 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

Parâmetros

  • sample (torch.Tensor) — O tensor de entrada com ruído.
  • timestep (torch.Tensor | float | int) — O número de timesteps para desruidar uma entrada.
  • encoder_hidden_states (torch.Tensor) — Os estados ocultos do codificador.
  • controlnet_cond (torch.Tensor) — O tensor de entrada condicional com forma (batch_size, sequence_length, hidden_size).
  • conditioning_scale (float, padrão 1.0) — Fator de escala para as saídas do ControlNet.
  • class_labels (torch.Tensor, opcional, padrão None) — Rótulos de classe opcionais para condicionamento. Os embeddings deles serão somados aos embeddings de timestep.
  • timestep_cond (torch.Tensor, opcional, padrão None) — Incorporações condicionais adicionais para o timestep. Se fornecidas, as incorporações serão somadas com o timestep_embedding passado pela camada self.time_embedding para obter as incorporações finais de timestep.
  • attention_mask (torch.Tensor, opcional, padrão None) — Uma máscara de atenção com forma (batch, key_tokens) é aplicada a encoder_hidden_states. Se 1, a máscara é mantida; caso contrário, se 0, ela é descartada. A máscara será convertida em um viés, que adiciona grandes valores negativos às pontuações de atenção correspondentes aos tokens “descartados”.
  • added_cond_kwargs (dict) — Condições adicionais para o UNet do Stable Diffusion XL.
  • cross_attention_kwargs (dict[str], opcional, padrão None) — Um dicionário de kwargs que, se especificado, é passado para o AttnProcessor.
  • guess_mode (bool, padrão False) — Neste modo, o encoder do ControlNet faz o possível para reconhecer o conteúdo da entrada, mesmo que você remova todos os prompts. Recomenda-se um guidance_scale entre 3.0 e 5.0.
  • return_dict (bool, padrão True) — Se deve ou não retornar um ControlNetOutput em vez de uma tupla simples.

Retorna

ControlNetOutput ou tuple

Se return_dict for True, um ControlNetOutput é retornado; caso contrário, uma tupla é retornada, em que o primeiro elemento é o tensor da amostra.

O método forward do 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 )

Parâmetros

  • unet (UNet2DConditionModel) — Os pesos do modelo UNet a serem copiados para o ControlNetModel. Todas as opções de configuração também são copiadas quando aplicável.

Instanciar um ControlNetModel a partir de UNet2DConditionModel.

set_attention_slice

< >

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

Parâmetros

  • slice_size (str ou int ou list(int), opcional, padrão "auto") — Quando "auto", a entrada para as cabeças de atenção é dividida ao meio, de modo que a atenção é calculada em duas etapas. Se "max", a quantidade máxima de memória é economizada executando apenas uma fatia por vez. Se um número for fornecido, usa tantas fatias quanto attention_head_dim // slice_size. Nesse caso, attention_head_dim deve ser um múltiplo de slice_size.

Ative o cálculo de atenção fatiado.

Quando essa opção está habilitada, o módulo de atenção divide o tensor de entrada em fatias para calcular a atenção em várias etapas. Isso é útil para economizar memória em troca de uma pequena diminuição na velocidade.

set_default_attn_processor

< >

( )

Desativa os processadores de atenção personalizados e define a implementação padrão de atenção.

ControlNetOutput

classe diffusers.models.controlnets.ControlNetOutput

< >

( down_block_res_samples: tuplemid_block_res_sample: Tensor )

Parâmetros

  • down_block_res_samples (tuple[torch.Tensor]) — Uma tupla de ativações de downsampling em diferentes resoluções para cada bloco de downsampling. Cada tensor deve ter a forma (batch_size, channel * resolution, height //resolution, width // resolution). A saída pode ser usada para condicionar as ativações de downsampling do UNet original.
  • mid_down_block_re_sample (torch.Tensor) — A ativação do bloco intermediário (a menor resolução de amostragem). Cada tensor deve ter a forma (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution). A saída pode ser usada para condicionar a ativação do bloco intermediário do UNet original.

A saída de ControlNetModel.

Update on GitHub

←AutoModel ControlNetUnionModel→