Diffusers 文档

稀疏ControlNet模型

Diffusers

加入 Hugging Face 社区

并获得增强的文档体验

在模型、数据集和 Spaces 上协作

通过加速推理获得更快的示例

切换文档主题

开始使用

SparseControlNet模型

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

类 diffusers.SparseControlNetModel

< source >

( in_channels: int = 4 conditioning_channels: int = 4 flip_sin_to_cos: bool = True freq_shift: int = 0 down_block_types: typing.Tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion') only_cross_attention: typing.Union[bool, typing.Tuple[bool]] = False block_out_channels: typing.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: typing.Optional[int] = 32 norm_eps: float = 1e-05 cross_attention_dim: int = 768 transformer_layers_per_block: typing.Union[int, typing.Tuple[int, ...]] = 1 transformer_layers_per_mid_block: typing.Union[int, typing.Tuple[int], NoneType] = None temporal_transformer_layers_per_block: typing.Union[int, typing.Tuple[int, ...]] = 1 attention_head_dim: typing.Union[int, typing.Tuple[int, ...]] = 8 num_attention_heads: typing.Union[int, typing.Tuple[int, ...], NoneType] = None use_linear_projection: bool = False upcast_attention: bool = False resnet_time_scale_shift: str = 'default' conditioning_embedding_out_channels: typing.Optional[typing.Tuple[int, ...]] = (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], defaults to (320, 640, 1280, 1280)) — 每个块的输出通道元组，默认为 (320, 640, 1280, 1280)。
layers_per_block (int, defaults to 2) — 每个块的层数，默认为 2。
downsample_padding (int, defaults to 1) — 用于下采样的卷积的填充，默认为 1。
mid_block_scale_factor (float, defaults to 1) — 用于中间块的缩放因子，默认为 1。
act_fn (str, defaults to “silu”) — 要使用的激活函数，默认为 “silu”。
norm_num_groups (int, optional, defaults to 32) — 用于归一化的组数，默认为 32。如果为 None，则在后处理中跳过归一化和激活层。
norm_eps (float, defaults to 1e-5) — 用于归一化的 epsilon 值，默认为 1e-5。
cross_attention_dim (int, defaults to 1280) — 交叉注意力特征的维度，默认为 1280。
transformer_layers_per_block (int or Tuple[int], optional, defaults to 1) — BasicTransformerBlock 类型的 Transformer 块的数量。仅与 ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn 相关。默认为 1。
transformer_layers_per_mid_block (int or Tuple[int], optional, defaults to 1) — 中间块中每层要使用的 Transformer 层数，默认为 1。
attention_head_dim (int or Tuple[int], defaults to 8) — 注意力头的维度，默认为 8。
num_attention_heads (int or Tuple[int], optional) — 用于多头注意力的头数。
use_linear_projection (bool, defaults to False) —
upcast_attention (bool, defaults to False) —
resnet_time_scale_shift (str, defaults to "default") — ResNet 块的时间尺度偏移配置（参见 ResnetBlock2D）。从 default 或 scale_shift 中选择。
conditioning_embedding_out_channels (Tuple[int], defaults to (16, 32, 96, 256)) — conditioning_embedding 层中每个块的输出通道元组，默认为 (16, 32, 96, 256)。
global_pool_conditions (bool, defaults to False) — TODO(Patrick) - 未使用的参数，默认为 False。
controlnet_conditioning_channel_order (str, defaults to rgb) —
motion_max_seq_length (int, defaults to 32) — 运动模块中使用的最大序列长度，默认为 32。
motion_num_attention_heads (int or Tuple[int], defaults to 8) — 运动模块的每个注意力层中使用的头数，默认为 8。
concat_conditioning_mask (bool, defaults to True) —
use_simplified_condition_embedding (bool, defaults to True) —

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

forward

< source >

( 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: typing.Optional[typing.Dict[str, typing.Any]] = None conditioning_mask: typing.Optional[torch.Tensor] = None guess_mode: bool = False return_dict: bool = True ) → ControlNetOutput 或 tuple

参数

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

ControlNetOutput 或 tuple

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

SparseControlNetModel 的前向方法。

from_unet

< source >

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

参数

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

从 UNet2DConditionModel 实例化 SparseControlNetModel。

set_attention_slice

< source >

( slice_size: typing.Union[str, int, typing.List[int]] )

参数

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

启用切片注意力计算。

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

set_attn_processor

< source >

( processor: typing.Union[diffusers.models.attention_processor.AttnProcessor, diffusers.models.attention_processor.CustomDiffusionAttnProcessor, diffusers.models.attention_processor.AttnAddedKVProcessor, diffusers.models.attention_processor.AttnAddedKVProcessor2_0, diffusers.models.attention_processor.JointAttnProcessor2_0, diffusers.models.attention_processor.PAGJointAttnProcessor2_0, diffusers.models.attention_processor.PAGCFGJointAttnProcessor2_0, diffusers.models.attention_processor.FusedJointAttnProcessor2_0, diffusers.models.attention_processor.AllegroAttnProcessor2_0, diffusers.models.attention_processor.AuraFlowAttnProcessor2_0, diffusers.models.attention_processor.FusedAuraFlowAttnProcessor2_0, diffusers.models.attention_processor.FluxAttnProcessor2_0, diffusers.models.attention_processor.FluxAttnProcessor2_0_NPU, diffusers.models.attention_processor.FusedFluxAttnProcessor2_0, diffusers.models.attention_processor.FusedFluxAttnProcessor2_0_NPU, diffusers.models.attention_processor.CogVideoXAttnProcessor2_0, diffusers.models.attention_processor.FusedCogVideoXAttnProcessor2_0, diffusers.models.attention_processor.XFormersAttnAddedKVProcessor, diffusers.models.attention_processor.XFormersAttnProcessor, diffusers.models.attention_processor.XLAFlashAttnProcessor2_0, diffusers.models.attention_processor.AttnProcessorNPU, diffusers.models.attention_processor.AttnProcessor2_0, diffusers.models.attention_processor.MochiVaeAttnProcessor2_0, diffusers.models.attention_processor.MochiAttnProcessor2_0, diffusers.models.attention_processor.StableAudioAttnProcessor2_0, diffusers.models.attention_processor.HunyuanAttnProcessor2_0, diffusers.models.attention_processor.FusedHunyuanAttnProcessor2_0, diffusers.models.attention_processor.PAGHunyuanAttnProcessor2_0, diffusers.models.attention_processor.PAGCFGHunyuanAttnProcessor2_0, diffusers.models.attention_processor.LuminaAttnProcessor2_0, diffusers.models.attention_processor.FusedAttnProcessor2_0, diffusers.models.attention_processor.CustomDiffusionXFormersAttnProcessor, diffusers.models.attention_processor.CustomDiffusionAttnProcessor2_0, diffusers.models.attention_processor.SlicedAttnProcessor, diffusers.models.attention_processor.SlicedAttnAddedKVProcessor, diffusers.models.attention_processor.SanaLinearAttnProcessor2_0, diffusers.models.attention_processor.PAGCFGSanaLinearAttnProcessor2_0, diffusers.models.attention_processor.PAGIdentitySanaLinearAttnProcessor2_0, diffusers.models.attention_processor.SanaMultiscaleLinearAttention, diffusers.models.attention_processor.SanaMultiscaleAttnProcessor2_0, diffusers.models.attention_processor.SanaMultiscaleAttentionProjection, diffusers.models.attention_processor.IPAdapterAttnProcessor, diffusers.models.attention_processor.IPAdapterAttnProcessor2_0, diffusers.models.attention_processor.IPAdapterXFormersAttnProcessor, diffusers.models.attention_processor.SD3IPAdapterJointAttnProcessor2_0, diffusers.models.attention_processor.PAGIdentitySelfAttnProcessor2_0, diffusers.models.attention_processor.PAGCFGIdentitySelfAttnProcessor2_0, diffusers.models.attention_processor.LoRAAttnProcessor, diffusers.models.attention_processor.LoRAAttnProcessor2_0, diffusers.models.attention_processor.LoRAXFormersAttnProcessor, diffusers.models.attention_processor.LoRAAttnAddedKVProcessor]]] )

参数

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

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

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

set_default_attn_processor

< source >

( )

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

SparseControlNetOutput

class diffusers.models.controlnet_sparsectrl.SparseControlNetOutput

< source >

( *args **kwargs )

< > Update on GitHub

←SD3ControlNetModel ControlNetUnionModel→