diffusers/v0.43.0/pt/api/models/controlnet_sparsectrl.md

SparseControlNetModel

SparseControlNetModel é uma implementação do ControlNet para AnimateDiff.

ControlNet foi introduzido em Adding Conditional Control to Text-to-Image Diffusion Models 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 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.

Exemplo de carregamento do SparseControlNetModel

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

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

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.

forward[[diffusers.SparseControlNetModel.forward]]

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

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.

from_unet[[diffusers.SparseControlNetModel.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 SparseControlNetModel. Todas as opções de configuração também são copiadas, quando aplicável.

Instanciar um SparseControlNetModel a partir de UNet2DConditionModel.

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

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

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

diffusers.models.controlnets.SparseControlNetOutput(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 SparseControlNetModel.