# SparseControlNetModel

SparseControlNetModel es una implementación de ControlNet para [AnimateDiff](https://huggingface.co/papers/2307.04725).

ControlNet se introdujo en [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) por Lvmin Zhang, Anyi Rao y Maneesh Agrawala.

La versión SparseCtrl de ControlNet se presentó en [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) para lograr una generación controlada en modelos de difusión de texto a video, por Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin y Bo Dai.

El resumen del artículo es:

*El desarrollo de la generación de video a partir de texto (T2V), es decir, la creación de videos mediante un prompt de texto dado, ha avanzado significativamente en los últimos años. Sin embargo, depender exclusivamente de prompts de texto a menudo resulta en una composición de fotogramas ambigua debido a la incertidumbre espacial. La comunidad de investigación aprovecha así las señales estructurales densas, por ejemplo, secuencias de profundidad/bordes por fotograma, para mejorar la controlabilidad, lo cual aumenta la carga de inferencia. En este trabajo, presentamos SparseCtrl para habilitar un control estructural flexible con señales temporalmente dispersas, requiriendo solo una o pocas entradas, como se muestra en la Figura 1. Incorpora un codificador de condiciones adicional para procesar estas señales dispersas, manteniendo intacto el modelo T2V preentrenado. El enfoque propuesto es compatible con diversas modalidades, incluyendo bocetos, mapas de profundidad e imágenes RGB, lo que proporciona un control más práctico para la generación de video y promueve aplicaciones como el storyboarding, el renderizado de profundidad, la animación de fotogramas clave y la interpolación. Experimentos extensos demuestran la generalización de SparseCtrl en generadores T2V tanto originales como personalizados. El código y los modelos estarán disponibles públicamente en [esta URL de https](https://guoyww.github.io/projects/SparseCtrl).*

## Ejemplo para cargar SparseControlNetModel

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

#### diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

```python
diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), 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 = 768, transformer_layers_per_block: int | tuple[int, ...] = 1, transformer_layers_per_mid_block: int | tuple[int] | None = None, temporal_transformer_layers_per_block: int | tuple[int, ...] = 1, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)
```

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

**Parámetros:**

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

conditioning_channels (`int`, por defecto 4) : El número de canales de entrada en el módulo de incrustación condicional de controlnet. Si `concat_condition_embedding` es True, el valor proporcionado aquí se incrementa en 1.

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

transformer_layers_per_mid_block (`int` o `tuple[int]`, *opcional*, valor predeterminado 1) : El número de capas de transformador que se usarán en cada capa del bloque central.

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

num_attention_heads (`int` o `tuple[int]`, *opcional*) : El número de cabezas a utilizar para la atención multi-cabeza.

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

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

conditioning_embedding_out_channels (`tuple[int]`, por defecto `(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

controlnet_conditioning_channel_order (`str`, por defecto `rgb`) --

motion_max_seq_length (`int`, por defecto `32`) : La longitud máxima de secuencia a utilizar en el módulo de movimiento.

motion_num_attention_heads (`int` o `tuple[int]`, por defecto `8`) : El número de cabezas a utilizar en cada capa de atención del motion module.

concat_conditioning_mask (`bool`, por defecto `True`) --

use_simplified_condition_embedding (`bool`, por defecto `True`) --

Un modelo SparseControlNet tal como se describe en [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933).

#### forward[[diffusers.SparseControlNetModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, conditioning_mask: typing.Optional[torch.Tensor] = None, guess_mode: bool = False, return_dict: bool = True)
```

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

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

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

conditioning_mask (`torch.Tensor`, *opcional*, valor predeterminado `None`) : Máscara opcional que indica qué fotogramas en `controlnet_cond` son fotogramas de condicionamiento válidos.

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 devuelve un `~models.controlnet.ControlNetOutput` en lugar de una tupla simple.

**Devuelve:** `~models.controlnet.ControlNetOutput` **o** `tuple`

Si `return_dict` es `True`, se devuelve un `~models.controlnet.ControlNetOutput`; en caso contrario, se devuelve una tupla cuyo primer elemento es el tensor de la muestra.

El método forward de [SparseControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

#### from_unet[[diffusers.SparseControlNetModel.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_sparsectrl.py#L388)

**Parámetros:**

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

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

#### set_attention_slice[[diffusers.SparseControlNetModel.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_sparsectrl.py#L469)

**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.SparseControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

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

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

## SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

#### diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

```python
diffusers.models.controlnets.SparseControlNetOutput(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_sparsectrl.py#L44)

**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 [SparseControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).