Hugging Face's logo

Diffusers 文档

稀疏ControlNet模型

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

SparseControlNetModel

SparseControlNetModel 是 ControlNet 为 AnimateDiff 的一个实现。

ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 Adding Conditional Control to Text-to-Image Diffusion Models 中引入。

SparseCtrl 版本的 ControlNet 由 Yuwei Guo、Ceyuan Yang、Anyi Rao、Maneesh Agrawala、Dahua Lin 和 Bo Dai 在 SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models 中引入，用于在文本到视频扩散模型中实现受控生成。

该论文的摘要是

近年来，文本到视频 (T2V) 的发展，即使用给定的文本提示生成视频，取得了显著的进步。然而，仅依赖文本提示通常会导致由于空间不确定性而造成的模糊帧构图。因此，研究界利用密集结构信号，例如，逐帧深度/边缘序列，来增强可控性，但这相应地增加了推理的负担。在这项工作中，我们提出了 SparseCtrl，以使用时间上稀疏的信号实现灵活的结构控制，仅需一个或几个输入，如图 1 所示。它结合了一个额外的条件编码器来处理这些稀疏信号，同时保持预训练的 T2V 模型不变。所提出的方法与各种模态兼容，包括草图、深度图和 RGB 图像，为视频生成提供了更实用的控制，并促进了故事板、深度渲染、关键帧动画和插值等应用。大量的实验证明了 SparseCtrl 在原始和个性化 T2V 生成器上的泛化能力。代码和模型将在 this https URL 公开提供。

加载 SparseControlNetModel 的示例

import torch
from diffusers import SparseControlNetModel

# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", torch_dtype=torch.float16)

# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", torch_dtype=torch.float16)

# For loading fp16 variant, pass `variant="fp16"` as an additional parameter

SparseControlNetModel

class diffusers.SparseControlNetModel

< >

( in_channels: int = 4 conditioning_channels: int = 4 flip_sin_to_cos: bool = True freq_shift: int = 0 down_block_types: Tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion') only_cross_attention: Union = False block_out_channels: Tuple = (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: Optional = 32 norm_eps: float = 1e-05 cross_attention_dim: int = 768 transformer_layers_per_block: Union = 1 transformer_layers_per_mid_block: Union = None temporal_transformer_layers_per_block: Union = 1 attention_head_dim: Union = 8 num_attention_heads: Union = None use_linear_projection: bool = False upcast_attention: bool = False resnet_time_scale_shift: str = 'default' conditioning_embedding_out_channels: Optional = (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 )

参数

  • in_channels (int, 默认为 4) — 输入样本中的通道数。
  • conditioning_channels (int, 默认为 4) — controlnet 条件嵌入模块中的输入通道数。 如果 concat_condition_embedding 为 True，则此处提供的值将递增 1。
  • flip_sin_to_cos (bool, 默认为 True) — 是否在时间嵌入中将 sin 翻转为 cos。
  • freq_shift (int, 默认为 0) — 应用于时间嵌入的频率偏移。
  • down_block_types (tuple[str], 默认为 ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — 要使用的下采样块的元组。
  • only_cross_attention (Union[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, 可选, 默认为 32) — 用于归一化的组数。 如果为 None，则在后处理中跳过归一化和激活层。
  • norm_eps (float, 默认为 1e-5) — 用于归一化的 epsilon 值。
  • cross_attention_dim (int, 默认为 1280) — 交叉注意力特征的维度。
  • transformer_layers_per_block (int 或 Tuple[int], 可选, 默认为 1) — BasicTransformerBlock 类型的 Transformer 块的数量。 仅与 ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn 相关。
  • transformer_layers_per_mid_block (int 或 Tuple[int], 可选, 默认为 1) — 在中间块的每一层中使用的 Transformer 层数。
  • attention_head_dim (int 或 Tuple[int], 默认为 8) — 注意力头的维度。
  • num_attention_heads (int 或 Tuple[int], 可选) — 用于多头注意力的头数。
  • use_linear_projection (bool, 默认为 False) —
  • upcast_attention (bool, 默认为 False) —
  • resnet_time_scale_shift (str, 默认为 "default") — ResNet 块的时间尺度偏移配置 (参见 ResnetBlock2D)。 从 default 或 scale_shift 中选择。
  • conditioning_embedding_out_channels (Tuple[int], 默认为 (16, 32, 96, 256)) — conditioning_embedding 层中每个块的输出通道的元组。
  • global_pool_conditions (bool, 默认为 False) — TODO(Patrick) - 未使用的参数
  • controlnet_conditioning_channel_order (str, 默认为 rgb) —
  • motion_max_seq_length (int, 默认为 32) — 在运动模块中使用的最大序列长度。
  • motion_num_attention_heads (int 或 Tuple[int], 默认为 8) — 在运动模块的每个注意力层中使用的头数。
  • concat_conditioning_mask (bool, 默认为 True) —
  • use_simplified_condition_embedding (bool, 默认为 True) —

SparseControlNet 模型，如 SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models 中所述。

前向

< >

( sample: Tensor timestep: Union encoder_hidden_states: Tensor controlnet_cond: Tensor conditioning_scale: float = 1.0 timestep_cond: Optional = None attention_mask: Optional = None cross_attention_kwargs: Optional = None conditioning_mask: Optional = None guess_mode: bool = False return_dict: bool = True ) → ControlNetOutput or tuple

参数

  • sample (torch.Tensor) — 带噪输入张量。
  • timestep (Union[torch.Tensor, float, int]) — 对输入进行去噪的时间步数。
  • encoder_hidden_states (torch.Tensor) — 编码器隐藏状态。
  • controlnet_cond (torch.Tensor) — 形状为 (batch_size, sequence_length, hidden_size) 的条件输入张量。
  • conditioning_scale (float, 默认为 1.0) — ControlNet 输出的缩放因子。
  • class_labels (torch.Tensor, optional, 默认为 None) — 用于条件控制的可选类别标签。 它们的嵌入将与时间步嵌入相加。
  • timestep_cond (torch.Tensor, optional, 默认为 None) — 时间步的额外条件嵌入。 如果提供，嵌入将与通过 self.time_embedding 层传递的时间步嵌入相加，以获得最终的时间步嵌入。
  • attention_mask (torch.Tensor, optional, 默认为 None) — 形状为 (batch, key_tokens) 的注意力掩码，应用于 encoder_hidden_states。 如果为 1，则保留掩码；否则如果为 0，则丢弃掩码。 掩码将被转换为偏置，这将为对应于“丢弃”标记的注意力分数添加大的负值。
  • added_cond_kwargs (dict) — Stable Diffusion XL UNet 的额外条件。
  • cross_attention_kwargs (dict[str], optional, 默认为 None) — 一个关键字参数字典，如果指定，则会传递给 AttnProcessor。
  • guess_mode (bool, 默认为 False) — 在此模式下，即使您移除所有提示词，ControlNet 编码器也会尽力识别输入的输入内容。 建议使用介于 3.0 和 5.0 之间的 guidance_scale。
  • return_dict (bool, 默认为 True) — 是否返回 ControlNetOutput 而不是普通元组。

返回值

ControlNetOutput 或 tuple

如果 return_dict 为 True，则返回 ControlNetOutput，否则返回一个元组，其中第一个元素是 sample 张量。

SparseControlNetModel 的前向方法。

from_unet

 < >

( unet: UNet2DConditionModel controlnet_conditioning_channel_order: str = 'rgb' conditioning_embedding_out_channels: Optional = (16, 32, 96, 256) load_weights_from_unet: bool = True conditioning_channels: int = 3 )

参数

  • unet (UNet2DConditionModel) — 要复制到 SparseControlNetModel 的 UNet 模型权重。 所有配置选项也会在适用的情况下进行复制。

从 UNet2DConditionModel 实例化 SparseControlNetModel。

set_attention_slice

 < >

( slice_size: Union )

参数

  • slice_size (str 或 int 或 list(int), optional, 默认为 "auto") — 当为 "auto" 时，注意力头的输入将减半，因此注意力分两步计算。 如果为 "max"，则通过一次仅运行一个切片来最大程度地节省内存。 如果提供数字，则使用与 attention_head_dim // slice_size 一样多的切片。 在这种情况下，attention_head_dim 必须是 slice_size 的倍数。

启用切片注意力计算。

启用此选项后，注意力模块会将输入张量分割成切片，以分几个步骤计算注意力。 这对于节省一些内存以换取速度的少量降低非常有用。

set_attn_processor

 < >

( processor: Union )

参数

  • processor (AttentionProcessor 的 dict 或仅 AttentionProcessor) — 实例化的处理器类或处理器类字典，它将被设置为 **所有** Attention 层的处理器。

    如果 processor 是一个 dict，则键需要定义到相应交叉注意力处理器的路径。 强烈建议在设置可训练的注意力处理器时使用此方法。

设置要用于计算注意力的注意力处理器。

set_default_attn_processor

 < >

( )

禁用自定义注意力处理器并设置默认注意力实现。

SparseControlNetOutput

class diffusers.models.controlnet_sparsectrl.SparseControlNetOutput

 < >

( down_block_res_samples: Tuple mid_block_res_sample: Tensor )

参数

  • down_block_res_samples (tuple[torch.Tensor]) — 不同分辨率下采样激活的元组，用于每个下采样块。 每个张量应具有形状 (batch_size, channel * resolution, height //resolution, width // resolution)。 输出可用于调节原始 UNet 的下采样激活。
  • mid_down_block_re_sample (torch.Tensor) — 中间块（最低样本分辨率）的激活。 每个张量应具有形状 (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)。 输出可用于调节原始 UNet 的中间块激活。

SparseControlNetModel 的输出。

< > Update on GitHub

←SD3ControlNetModel 概述→