Diffusers 文档
SparseControlNetModel
并获得增强的文档体验
开始使用
SparseControlNetModel
SparseControlNetModel 是 AnimateDiff 的 ControlNet 实现。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《为文本到图像扩散模型添加条件控制》 中提出。
ControlNet 的 SparseCtrl 版本由 Yuwei Guo、Ceyuan Yang、Anyi Rao、Maneesh Agrawala、Dahua Lin 和 Bo Dai 在 SparseCtrl: 为文本到视频扩散模型添加稀疏控制 中引入,用于在文本到视频扩散模型中实现受控生成。
论文摘要如下:
近年来,文本到视频(T2V),即根据给定文本提示生成视频,取得了显著进展。然而,仅仅依靠文本提示通常会导致由于空间不确定性而产生的模糊帧构图。因此,研究社区利用密集的结构信号(例如每帧深度/边缘序列)来增强可控性,而这些信号的收集相应地增加了推理负担。在这项工作中,我们提出了 SparseCtrl,以实现通过时间稀疏信号进行灵活的结构控制,仅需要一个或几个输入,如图 1 所示。它包含一个额外的条件编码器来处理这些稀疏信号,同时保持预训练的 T2V 模型不变。所提出的方法与各种模态兼容,包括草图、深度图和 RGB 图像,为视频生成提供更实用的控制,并促进故事板、深度渲染、关键帧动画和插值等应用。大量的实验证明了 SparseCtrl 在原始和个性化 T2V 生成器上的泛化能力。代码和模型将在 此 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: 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]
, 默认为(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 中所述。
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: 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]
) — 去噪输入的时间步数。 - 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
, 可选, 默认为None
) — 可选的用于条件化的类别标签。它们的嵌入将与时间步嵌入求和。 - timestep_cond (
torch.Tensor
, 可选, 默认为None
) — 时间步长的额外条件嵌入。如果提供,这些嵌入将与通过self.time_embedding
层的时间步长嵌入相加,以获得最终的时间步长嵌入。 - attention_mask (
torch.Tensor
, 可选, 默认为None
) — 应用于encoder_hidden_states
的注意力掩码,形状为(batch, key_tokens)
。如果为1
则保留掩码,否则如果为0
则丢弃。掩码将被转换为偏置,这将为对应“丢弃”token 的注意力分数添加大的负值。 - added_cond_kwargs (
dict
) — Stable Diffusion XL UNet 的附加条件。 - cross_attention_kwargs (
dict[str]
, 可选, 默认为None
) — 如果指定,将传递给AttnProcessor
的 kwargs 字典。 - guess_mode (
bool
, 默认为False
) — 在此模式下,即使您删除所有提示,ControlNet 编码器也会尽力识别输入内容。建议guidance_scale
在 3.0 到 5.0 之间。 - return_dict (
bool
, 默认为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 模型权重。所有适用的配置选项也会被复制。
set_attention_slice
< source >( slice_size: typing.Union[str, int, typing.List[int]] )
启用分片注意力计算。
启用此选项后,注意力模块会将输入张量分片以分步计算注意力。这对于节省内存非常有用,但会稍微降低速度。
设置注意力处理器
< 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]]] )
设置用于计算注意力的注意力处理器。
禁用自定义注意力处理器并设置默认注意力实现。