# ControlNetModel

O modelo ControlNet foi introduzido em [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) 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](/docs/diffusers/main/pt/api/models/controlnet#diffusers.ControlNetModel) deve ser carregado com [from_pretrained()](/docs/diffusers/main/pt/api/models/overview#diffusers.ModelMixin.from_pretrained), mas também pode ser carregado do formato original usando `FromOriginalModelMixin.from_single_file` da seguinte forma:

```py
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](https://huggingface.co/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.

```py
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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L111)

**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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L602)

**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](/docs/diffusers/main/pt/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) em vez de uma tupla simples.

**Retorna:** [ControlNetOutput](/docs/diffusers/main/pt/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **ou** `tuple`

Se `return_dict` for `True`, um [ControlNetOutput](/docs/diffusers/main/pt/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) é retornado; caso contrário, uma tupla é retornada, em que o primeiro elemento é o tensor da amostra.

O método forward do [ControlNetModel](/docs/diffusers/main/pt/api/models/controlnet#diffusers.ControlNetModel).

#### from_unet[[diffusers.ControlNetModel.from_unet]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L444)

**Parâmetros:**

unet (`UNet2DConditionModel`) : Os pesos do modelo UNet a serem copiados para o [ControlNetModel](/docs/diffusers/main/pt/api/models/controlnet#diffusers.ControlNetModel). Todas as opções de configuração também são copiadas, quando aplicável.

Instanciar um [ControlNetModel](/docs/diffusers/main/pt/api/models/controlnet#diffusers.ControlNetModel) a partir de [UNet2DConditionModel](/docs/diffusers/main/pt/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L537)

**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]]

```python
set_default_attn_processor()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L521)

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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L47)

**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](/docs/diffusers/main/pt/api/models/controlnet#diffusers.ControlNetModel).