# SparseControlNetModel

SparseControlNetModel é uma implementação do ControlNet para [AnimateDiff](https://huggingface.co/papers/2307.04725).

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.

A versão SparseCtrl do ControlNet foi introduzida em [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) para alcançar geração controlada em modelos de difusão de texto para vídeo, por Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin e Bo Dai.

O resumo do artigo é:

*O desenvolvimento de text-to-video (T2V), ou seja, a geração de vídeos a partir de um prompt de texto, avançou significativamente nos últimos anos. No entanto, a dependência exclusiva de prompts de texto frequentemente resulta em composição de quadros ambígua devido à incerteza espacial. A comunidade de pesquisa, portanto, utiliza sinais de estrutura densos, por exemplo, sequências de profundidade/bordas por quadro, para aprimorar a controlabilidade, cuja coleta aumenta correspondentemente a carga de inferência. Neste trabalho, apresentamos o SparseCtrl para permitir controle de estrutura flexível com sinais temporalmente esparsos, exigindo apenas uma ou poucas entradas, conforme mostrado na Figura 1. Ele incorpora um codificador de condição adicional para processar esses sinais esparsos, mantendo o modelo T2V pré-treinado intacto. A abordagem proposta é compatível com várias modalidades, incluindo esboços, mapas de profundidade e imagens RGB, fornecendo controle mais prático para a geração de vídeos e promovendo aplicações como storyboarding, renderização de profundidade, animação de quadros-chave e interpolação. Experimentos extensos demonstram a generalização do SparseCtrl em geradores T2V originais e personalizados. Os códigos e modelos estarão publicamente disponíveis em [this https URL](https://guoyww.github.io/projects/SparseCtrl).*

## Exemplo de carregamento do 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)
```

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

**Parâmetros:**

in_channels (`int`, padrão 4) : O número de canais na amostra de entrada.

conditioning_channels (`int`, padrão 4) : O número de canais de entrada no módulo de incorporação condicional do controlnet. Se `concat_condition_embedding` for True, o valor fornecido aqui é incrementado em 1.

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

transformer_layers_per_mid_block (`int` ou `tuple[int]`, *opcional*, padrão 1) : O número de camadas de transformador a serem usadas em cada camada do bloco intermediário.

attention_head_dim (`int` ou `tuple[int]`, padrão 8) : A dimensão dos cabeçalhos de atenção.

num_attention_heads (`int` ou `tuple[int]`, *opcional*) : O número de cabeças a serem usadas para a atenção multi-cabeça.

use_linear_projection (`bool`, padrão é `False`) --

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

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

controlnet_conditioning_channel_order (`str`, padrão `rgb`) --

motion_max_seq_length (`int`, padrão `32`) : O comprimento máximo da sequência a ser usado no módulo de movimento.

motion_num_attention_heads (`int` ou `tuple[int]`, padrão `8`) : O número de cabeças a serem usadas em cada camada de atenção do motion module.

concat_conditioning_mask (`bool`, padrão `True`) --

use_simplified_condition_embedding (`bool`, padrão `True`) --

Um modelo SparseControlNet, conforme descrito em [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)
```

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

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

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

conditioning_mask (`torch.Tensor`, *opcional*, padrão `None`) : Máscara opcional indicando quais quadros em `controlnet_cond` são quadros de condicionamento válidos.

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 `~models.controlnet.ControlNetOutput` em vez de uma tupla simples.

**Retorna:** `~models.controlnet.ControlNetOutput` **ou** `tuple`

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

O método forward do [SparseControlNetModel](/docs/diffusers/v0.43.0/pt/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)
```

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

**Parâmetros:**

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

Instanciar um [SparseControlNetModel](/docs/diffusers/v0.43.0/pt/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) a partir de [UNet2DConditionModel](/docs/diffusers/v0.43.0/pt/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

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

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

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

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

```python
set_default_attn_processor()
```

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

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

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

[Fonte](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]`) : 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 [SparseControlNetModel](/docs/diffusers/v0.43.0/pt/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).