diffusers/main/pt/api/models/controlnet.md

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 com "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 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[[diffusers.ControlNetModel]]

diffusers.ControlNetModel[[diffusers.ControlNetModel]]

diffusers.ControlNetModel(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'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', 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 = (16, 32, 96, 256), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64)

Fonte

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 de 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[[diffusers.ControlNetModel.forward]]

forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: 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, guess_mode: bool = False, return_dict: bool = True)

Fonte

Parâmetros:

sample (torch.Tensor) : O tensor de entrada com ruído.

timestep (torch.Tensor | float | int) : O número de passos de tempo 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) : O fator de escala para as saídas do ControlNet.

class_labels (torch.Tensor, opcional, padrão None) : Rótulos de classe opcionais para condicionamento. Seus embeddings serão somados aos embeddings de timestep.

timestep_cond (torch.Tensor, opcional, padrão None) : Incorporações condicionais adicionais para o passo de tempo. Se fornecidas, as incorporações serão somadas com a timestep_embedding passada pela camada self.time_embedding para obter as incorporações finais do passo de tempo.

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 valores negativos grandes à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[[diffusers.ControlNetModel.from_unet]]

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, conditioning_channels: int = 3)

Fonte

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[[diffusers.ControlNetModel.set_attention_slice]]

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

Fonte

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 é reduzida pela metade, 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 esta 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[[diffusers.ControlNetModel.set_default_attn_processor]]

set_default_attn_processor()

Fonte

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

ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)

Fonte

Parâmetros:

down_block_res_samples (tuple[torch.Tensor]) : Uma tupla de ativações de downsample 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.