Diffusers documentation
SparseControlNetModel
SparseControlNetModel
SparseControlNetModel 是 AnimateDiff 的 ControlNet 实现。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 Adding Conditional Control to Text-to-Image Diffusion Models 中提出。
ControlNet 的 SparseCtrl 版本由 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", 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 parameterSparseControlNetModel
class diffusers.SparseControlNetModel
< source >( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (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 )
参数
- 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（
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 模块中使用的最大序列长度。 - motion_num_attention_heads (
int或tuple[int]，默认为8) — 运动模块中每个注意力层使用的注意力头数量。 - concat_conditioning_mask（
bool，默认为True） — - use_simplified_condition_embedding（
bool，默认为True） —
如SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models中所述的 SparseControlNet 模型。
forward
< source >( 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
参数
- sample (
torch.Tensor) — 带噪声的输入张量。 - timestep (
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 输出的缩放因子。 - timestep_cond (
torch.Tensor，可选，默认为None) — 用于时间步的额外条件嵌入。如果提供，这些嵌入将与通过self.time_embedding层传入的 timestep_embedding 相加，以得到最终的时间步嵌入。 - attention_mask (
torch.Tensor，可选，默认为None) — 形状为(batch, key_tokens)的注意力掩码将应用于encoder_hidden_states。如果值为1，则保留该掩码；如果值为0，则将其丢弃。掩码会被转换为偏置，向对应于“丢弃”标记的注意力分数添加较大的负值。 - conditioning_mask (
torch.Tensor，可选，默认为None) — 可选的掩码，用于指示controlnet_cond中哪些帧是有效的条件帧。 - cross_attention_kwargs (
dict[str]，可选，默认为None) — 一个 kwargs 字典，如果指定，将传递给AttnProcessor。 - guess_mode（
bool，默认为False） — 在此模式下，即使您移除了所有提示词，ControlNet 编码器也会尽力识别输入内容。建议将guidance_scale设置在 3.0 到 5.0 之间。 - return_dict (
bool，默认为True) — 是否返回~models.controlnet.ControlNetOutput而不是普通元组。
返回值
~models.controlnet.ControlNetOutput 或 tuple
如果 return_dict 为 True，则返回 ~models.controlnet.ControlNetOutput，否则返回一个元组，其中第一个元素为样本张量。
SparseControlNetModel 的前向方法。
from_unet
< source >( 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 )
参数
- unet (
UNet2DConditionModel) — 要复制到 SparseControlNetModel 的 UNet 模型权重。所有适用的配置选项也会一并复制。
set_attention_slice
< source >( slice_size: str | int | list[int] )
启用切片注意力计算。
启用此选项后，注意力模块会将输入张量切分为多个切片，分步计算注意力。这有助于节省部分内存，但会略微降低速度。
禁用自定义注意力处理器并设置默认的注意力实现。
SparseControlNetOutput
class diffusers.models.controlnets.SparseControlNetOutput
< source >( down_block_res_samples: tuplemid_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 的中间块激活值进行条件化。