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

SparseControlNetModel

SparseControlNetModel es una implementación de ControlNet para AnimateDiff.

ControlNet se introdujo en Adding Conditional Control to Text-to-Image Diffusion Models 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 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.

Ejemplo para cargar 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)

Fuente

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.

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)

Fuente

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.

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)

Fuente

Parámetros:

unet (UNet2DConditionModel) : Los pesos del modelo UNet que se copiarán al SparseControlNetModel. Todas las opciones de configuración también se copian cuando sea aplicable.

Instancia un SparseControlNetModel a partir de UNet2DConditionModel.

set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

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

Fuente

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

set_default_attn_processor()

Fuente

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

diffusers.models.controlnets.SparseControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)

Fuente

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.