Hugging Face's logo

Diffusers documentation

SparseControlNetModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

clase diffusers.SparseControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 768transformer_layers_per_block: int | tuple[int, ...] = 1transformer_layers_per_mid_block: int | tuple[int] | None = Nonetemporal_transformer_layers_per_block: int | tuple[int, ...] = 1attention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falsecontrolnet_conditioning_channel_order: str = 'rgb'motion_max_seq_length: int = 32motion_num_attention_heads: int = 8concat_conditioning_mask: bool = Trueuse_simplified_condition_embedding: bool = True )

Parámetros

  • in_channels (int, por defecto 4) — El número de canales en la muestra de entrada.
  • conditioning_channels (int, valor predeterminado 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 reducción de muestreo.
  • 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) — La epsilon a utilizar para la normalización.
  • cross_attention_dim (int, por defecto 1280) — La dimensión de las características de 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 transformer que se usarán en cada capa del bloque intermedio.
  • attention_head_dim (int o tuple[int], valor predeterminado: 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 módulo de movimiento.
  • 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

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0timestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneconditioning_mask: typing.Optional[torch.Tensor] = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.ControlNetOutput or tuple

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 el valor es 1, la máscara se conserva; en caso contrario, si es 0, se descarta. La máscara se convierte en un sesgo que suma 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) — Indica si se debe devolver 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

< >

( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )

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

< >

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

Parámetros

  • slice_size (str o int o list(int), opcional, valor predeterminado "auto") — Cuando es "auto", la entrada a las cabezas de atención se divide 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 usan 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 varias etapas. Esto es útil para ahorrar algo de memoria a cambio de una pequeña disminución en la velocidad.

set_default_attn_processor

< >

( )

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

SparseControlNetOutput

clase diffusers.models.controlnets.SparseControlNetOutput

< >

( down_block_res_samples: tuple[torch.Tensor]mid_block_res_sample: Tensor )

Parámetros

  • down_block_res_samples (tuple[torch.Tensor]) — Una tupla de activaciones de muestreo descendente a diferentes resoluciones para cada bloque de muestreo descendente. Cada tensor debe tener la forma (batch_size, channel * resolution, height //resolution, width // resolution). La salida se puede utilizar para condicionar las activaciones de muestreo descendente 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.

Update on GitHub

←SD3ControlNetModel AceStepTransformer1DModel→