# ControlNetModel

El modelo ControlNet se presentó en [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) de Lvmin Zhang, Anyi Rao y Maneesh Agrawala. Ofrece un mayor grado de control sobre la generación de imágenes a partir de texto al condicionar el modelo con entradas adicionales, como mapas de bordes, mapas de profundidad, mapas de segmentación y puntos clave para la detección de pose.

El resumen del artículo es:

*Presentamos ControlNet, una arquitectura de red neuronal para añadir controles de condicionamiento espacial a grandes modelos de difusión de texto a imagen preentrenados. ControlNet bloquea los grandes modelos de difusión listos para producción y reutiliza sus capas de codificación profundas y robustas, preentrenadas con miles de millones de imágenes, como una base sólida para aprender un conjunto diverso de controles condicionales. La arquitectura neuronal se conecta mediante "convoluciones cero" (capas de convolución inicializadas en cero) que hacen crecer progresivamente los parámetros desde cero y garantizan que ningún ruido perjudicial pueda afectar el ajuste fino. Probamos varios controles de condicionamiento, por ejemplo, bordes, profundidad, segmentación, pose humana, etc., con Stable Diffusion, utilizando una o varias condiciones, con o sin indicaciones. Mostramos que el entrenamiento de ControlNets es robusto con conjuntos de datos pequeños (<50k) y grandes (>1m). Resultados extensos muestran que ControlNet puede facilitar aplicaciones más amplias para controlar los modelos de difusión de imágenes.*

## Carga desde el formato original

Por defecto, el [ControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.ControlNetModel) debe cargarse con [from_pretrained()](/docs/diffusers/v0.43.0/es/api/models/overview#diffusers.ModelMixin.from_pretrained), pero también puede cargarse desde el formato original usando `FromOriginalModelMixin.from_single_file` de la siguiente manera:

```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)
```

## Carga desde Control LoRA

Control-LoRA fue introducido por Stability AI en [stabilityai/control-lora](https://huggingface.co/stabilityai/control-lora) mediante la incorporación de un ajuste fino eficiente de parámetros de bajo rango a ControlNet. Este enfoque ofrece un método más eficiente y compacto para llevar el control del modelo a una mayor variedad 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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L111)

**Parámetros:**

in_channels (`int`, por defecto 4) : El número de canales en la muestra de entrada.

flip_sin_to_cos (`bool`, por defecto `True`) : Si se debe cambiar el sin por el cos en la incrustación temporal.

freq_shift (`int`, por defecto 0) : El desplazamiento de frecuencia que se aplica a la incrustación temporal.

down_block_types (`tuple[str]`, por defecto `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : La tupla de bloques de muestreo descendente a utilizar.

only_cross_attention (`bool | tuple[bool]`, por defecto `False`) --

block_out_channels (`tuple[int]`, por defecto `(320, 640, 1280, 1280)`) : La tupla de canales de salida para cada bloque.

layers_per_block (`int`, por defecto 2) : El número de capas por bloque.

downsample_padding (`int`, por defecto 1) : El relleno a utilizar para la convolución de muestreo descendente.

mid_block_scale_factor (`float`, por defecto 1) : El factor de escala a utilizar para el bloque intermedio.

act_fn (`str`, por defecto "silu") : La función de activación a utilizar.

norm_num_groups (`int`, *opcional*, valor predeterminado 32) : El número de grupos a utilizar para la normalización. Si es None, se omiten las capas de normalización y activación en el posprocesamiento.

norm_eps (`float`, por defecto 1e-5) : El epsilon a utilizar para la normalización.

cross_attention_dim (`int`, por defecto 1280) : La dimensión de las características de la atención cruzada.

transformer_layers_per_block (`int` o `tuple[int]`, *opcional*, valor predeterminado 1) : El número de bloques de transformador de tipo `BasicTransformerBlock`. Solo es relevante para `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

encoder_hid_dim (`int`, *opcional*, valor predeterminado None) : Si `encoder_hid_dim_type` está definido, `encoder_hidden_states` se proyectará de la dimensión `encoder_hid_dim` a `cross_attention_dim`.

encoder_hid_dim_type (`str`, *opcional*, valor predeterminado `None`) : Si se proporciona, `encoder_hidden_states` y posiblemente otras incrustaciones se proyectan hacia abajo a incrustaciones de texto de dimensión `cross_attention` según `encoder_hid_dim_type`.

attention_head_dim (`int | tuple[int]`, por defecto 8) : La dimensión de las cabezas de atención.

use_linear_projection (`bool`, por defecto `False`) --

class_embed_type (`str`, *opcional*, valor predeterminado `None`) : El tipo de embedding de clase a utilizar, que finalmente se suma a los embeddings de tiempo. Elija entre None, `"timestep"`, `"identity"`, `"projection"` o `"simple_projection"`.

addition_embed_type (`str`, *opcional*, valor predeterminado `None`) : Configura un embedding opcional que se sumará con los embeddings de tiempo. Elige entre `None` o "text". "text" utilizará la capa `TextTimeEmbedding`.

num_class_embeds (`int`, *opcional*, valor predeterminado 0) : Dimensión de entrada de la matriz de incrustación aprendible que se proyectará a `time_embed_dim` al realizar condicionamiento por clase con `class_embed_type` igual a `None`.

upcast_attention (`bool`, por defecto `False`) --

resnet_time_scale_shift (`str`, por defecto `"default"`) : Configuración de desplazamiento de escala de tiempo para los bloques ResNet (ver `ResnetBlock2D`). Elija entre `default` o `scale_shift`.

projection_class_embeddings_input_dim (`int`, *opcional*, valor predeterminado `None`) : La dimensión de la entrada `class_labels` cuando `class_embed_type="projection"`. Obligatorio cuando `class_embed_type="projection"`.

controlnet_conditioning_channel_order (`str`, por defecto `"rgb"`) : El orden de los canales de la imagen condicional. Se convertirá a `rgb` si es `bgr`.

conditioning_embedding_out_channels (`tuple[int]`, *opcional*, valor predeterminado `(16, 32, 96, 256)`) : La tupla de canales de salida para cada bloque en la capa `conditioning_embedding`.

global_pool_conditions (`bool`, por defecto `False`) : TODO(Patrick) - parámetro sin usar.

addition_embed_type_num_heads (`int`, por defecto 64) : El número de cabezas a utilizar para la capa `TextTimeEmbedding`.

Un modelo de 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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L602)

**Parámetros:**

sample (`torch.Tensor`) : El tensor de entrada con ruido.

timestep (`torch.Tensor | float | int`) : El número de pasos de tiempo para desruidar una entrada.

encoder_hidden_states (`torch.Tensor`) : Los estados ocultos del codificador.

controlnet_cond (`torch.Tensor`) : El tensor de entrada condicional de forma `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, por defecto `1.0`) : El factor de escala para las salidas de ControlNet.

class_labels (`torch.Tensor`, *opcional*, valor predeterminado `None`) : Etiquetas de clase opcionales para la condición. Sus incrustaciones se sumarán con las incrustaciones del paso de tiempo.

timestep_cond (`torch.Tensor`, *opcional*, valor predeterminado `None`) : Incrustaciones condicionales adicionales para el paso de tiempo. Si se proporcionan, las incrustaciones se sumarán con la timestep_embedding pasada a través de la capa `self.time_embedding` para obtener las incrustaciones finales del paso de tiempo.

attention_mask (`torch.Tensor`, *opcional*, valor predeterminado `None`) : Una máscara de atención de forma `(batch, key_tokens)` se aplica a `encoder_hidden_states`. Si es `1`, la máscara se conserva; en caso contrario, si es `0`, se descarta. La máscara se convertirá en un sesgo, que añade valores negativos grandes a las puntuaciones de atención correspondientes a los tokens "descartados".

added_cond_kwargs (`dict`) : Condiciones adicionales para el UNet de Stable Diffusion XL.

cross_attention_kwargs (`dict[str]`, *opcional*, valor predeterminado `None`) : Un diccionario de kwargs que, si se especifica, se pasa al `AttnProcessor`.

guess_mode (`bool`, por defecto `False`) : En este modo, el codificador de ControlNet intenta reconocer el contenido de la entrada lo mejor posible, incluso si eliminas todos los prompts. Se recomienda un `guidance_scale` entre 3.0 y 5.0.

return_dict (`bool`, por defecto `True`) : Si se debe devolver un [ControlNetOutput](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) en lugar de una tupla simple.

**Devuelve:** [ControlNetOutput](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **o** `tuple`

Si `return_dict` es `True`, se devuelve un [ControlNetOutput](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput); en caso contrario, se devuelve una tupla cuyo primer elemento es el tensor de la muestra.

El método forward de [ControlNetModel](/docs/diffusers/v0.43.0/es/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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L444)

**Parámetros:**

unet (`UNet2DConditionModel`) : Los pesos del modelo UNet que se copiarán al [ControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.ControlNetModel). Todas las opciones de configuración también se copian cuando sea aplicable.

Instancia un [ControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.ControlNetModel) a partir de [UNet2DConditionModel](/docs/diffusers/v0.43.0/es/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

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

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

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

**Parámetros:**

slice_size (`str` o `int` o `list(int)`, *opcional*, por defecto `"auto"`) : Cuando es `"auto"`, la entrada a las cabezas de atención se reduce a la mitad, por lo que la atención se calcula en dos pasos. Si es `"max"`, se ahorra la máxima cantidad de memoria ejecutando solo una porción a la vez. Si se proporciona un número, se utilizan tantas porciones como `attention_head_dim // slice_size`. En este caso, `attention_head_dim` debe ser un múltiplo de `slice_size`.

Habilitar el cálculo de atención segmentada.

Cuando esta opción está habilitada, el módulo de atención divide el tensor de entrada en fragmentos para calcular la atención en varios pasos. Esto es útil para ahorrar algo de memoria a cambio de una pequeña disminución en la velocidad.

#### set_default_attn_processor[[diffusers.ControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

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

Desactiva los procesadores de atención personalizados y establece la implementación de atención predeterminada.

## 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)
```

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

**Parámetros:**

down_block_res_samples (`tuple[torch.Tensor]`) : Una tupla de activaciones de downsampling en diferentes resoluciones para cada bloque de downsampling. Cada tensor debe tener la forma `(batch_size, channel * resolution, height //resolution, width // resolution)`. La salida se puede utilizar para condicionar las activaciones de downsampling del UNet original.

mid_down_block_re_sample (`torch.Tensor`) : La activación del bloque intermedio (la resolución de muestra más baja). Cada tensor debe tener la forma `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. La salida se puede utilizar para condicionar la activación del bloque intermedio del UNet original.

La salida de [ControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet#diffusers.ControlNetModel).