Diffusers 文档
ControlNet模型
并获得增强的文档体验
开始使用
ControlNetModel
ControlNet模型由Lvmin Zhang、Anyi Rao、Maneesh Agrawala在为文本到图像扩散模型添加条件控制中提出。通过对模型进行额外输入(如边缘图、深度图、分割图和姿态检测的关键点)的条件控制,它能更精确地控制文本到图像生成。
论文摘要如下:
我们提出了 ControlNet,一种神经网络架构,用于为大型预训练文本到图像扩散模型添加空间条件控制。ControlNet 锁定生产级大型扩散模型,并重新利用其经过数十亿图像预训练的深度和鲁棒编码层作为强大的主干,以学习多样化的条件控制集。该神经网络架构通过“零卷积”(零初始化卷积层)连接,这些卷积层参数从零开始逐步增长,确保不会有有害噪声影响微调。我们测试了各种条件控制,例如,边缘、深度、分割、人体姿态等,与 Stable Diffusion 结合使用,可以使用单个或多个条件,带或不带提示。我们表明 ControlNets 的训练对于小型(<50k)和大型(>1m)数据集都具有鲁棒性。广泛的结果表明 ControlNet 可能促进图像扩散模型的更广泛应用。
从原始格式加载
默认情况下,ControlNetModel应使用from_pretrained()加载,但也可以使用FromOriginalModelMixin.from_single_file
从原始格式加载,如下所示:
from diffusers import StableDiffusionControlNetPipeline, ControlNetModel
url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth" # can also be a local path
controlnet = ControlNetModel.from_single_file(url)
url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors" # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)
ControlNet模型
class diffusers.ControlNetModel
< 源 >( in_channels: int = 4 conditioning_channels: int = 3 flip_sin_to_cos: bool = True freq_shift: int = 0 down_block_types: typing.Tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D') mid_block_type: typing.Optional[str] = 'UNetMidBlock2DCrossAttn' 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 = 1280 transformer_layers_per_block: typing.Union[int, typing.Tuple[int, ...]] = 1 encoder_hid_dim: typing.Optional[int] = None encoder_hid_dim_type: typing.Optional[str] = None 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 class_embed_type: typing.Optional[str] = None addition_embed_type: typing.Optional[str] = None addition_time_embed_dim: typing.Optional[int] = None num_class_embeds: typing.Optional[int] = None upcast_attention: bool = False resnet_time_scale_shift: str = 'default' projection_class_embeddings_input_dim: typing.Optional[int] = None controlnet_conditioning_channel_order: str = 'rgb' conditioning_embedding_out_channels: typing.Optional[typing.Tuple[int, ...]] = (16, 32, 96, 256) global_pool_conditions: bool = False addition_embed_type_num_heads: int = 64 )
参数
- in_channels (
int
, 默认为 4) — 输入样本中的通道数。 - 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
相关。 - encoder_hid_dim (
int
, 可选, 默认为 None) — 如果定义了encoder_hid_dim_type
,则encoder_hidden_states
将从encoder_hid_dim
维度投影到cross_attention_dim
。 - encoder_hid_dim_type (
str
, 可选, 默认为None
) — 如果给定,encoder_hidden_states
和可能其他嵌入将根据encoder_hid_dim_type
下投影到维度为cross_attention
的文本嵌入。 - attention_head_dim (
Union[int, Tuple[int]]
, 默认为 8) — 注意力头的维度。 - use_linear_projection (
bool
, 默认为False
) — - class_embed_type (
str
, 可选, 默认为None
) — 要使用的类嵌入类型,最终与时间嵌入求和。可选择 None、"timestep"
、"identity"
、"projection"
或"simple_projection"
。 - addition_embed_type (
str
, 可选, 默认为None
) — 配置一个可选的嵌入,该嵌入将与时间嵌入求和。可选择None
或“text”。“text”将使用TextTimeEmbedding
层。 - num_class_embeds (
int
, 可选, 默认为 0) — 当class_embed_type
等于None
时,可学习嵌入矩阵的输入维度,该矩阵将被投影到time_embed_dim
,用于执行类条件。当class_embed_type="projection"
时必需。 - upcast_attention (
bool
, 默认为False
) — - resnet_time_scale_shift (
str
, 默认为"default"
) — ResNet 块的时间比例偏移配置(参见ResnetBlock2D
)。可选择default
或scale_shift
。 - projection_class_embeddings_input_dim (
int
, 可选, 默认为None
) — 当class_embed_type="projection"
时,class_labels
输入的维度。当class_embed_type="projection"
时必需。 - controlnet_conditioning_channel_order (
str
, 默认为"rgb"
) — 条件图像的通道顺序。如果为bgr
,将转换为rgb
。 - conditioning_embedding_out_channels (
tuple[int]
, 可选, 默认为(16, 32, 96, 256)
) —conditioning_embedding
层中每个块的输出通道元组。 - global_pool_conditions (
bool
, 默认为False
) — TODO(Patrick) - 未使用的参数。 - addition_embed_type_num_heads (
int
, 默认为 64) —TextTimeEmbedding
层中使用的头数。
ControlNet模型。
前向
< 源 >( sample: Tensor timestep: typing.Union[torch.Tensor, float, int] encoder_hidden_states: Tensor controlnet_cond: Tensor conditioning_scale: float = 1.0 class_labels: typing.Optional[torch.Tensor] = None timestep_cond: typing.Optional[torch.Tensor] = None attention_mask: typing.Optional[torch.Tensor] = None added_cond_kwargs: typing.Optional[typing.Dict[str, torch.Tensor]] = None cross_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = 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
) — 形状为(batch, key_tokens)
的注意力掩码应用于encoder_hidden_states
。如果为1
则保留掩码,否则为0
则丢弃。掩码将被转换为偏置,这将为对应“丢弃”令牌的注意力分数添加大的负值。 - added_cond_kwargs (
dict
) — Stable Diffusion XL UNet 的额外条件。 - cross_attention_kwargs (
dict[str]
, 可选, 默认为None
) — 一个 kwargs 字典,如果指定,将传递给AttnProcessor
。 - guess_mode (
bool
, 默认为False
) — 在此模式下,即使您删除所有提示,ControlNet 编码器也会尽力识别输入内容。建议guidance_scale
在 3.0 到 5.0 之间。 - return_dict (
bool
, 默认为True
) — 是否返回 ControlNetOutput 而不是普通元组。
返回
ControlNetOutput 或 tuple
如果 return_dict
为 True
,则返回 ControlNetOutput,否则返回一个元组,其中第一个元素是样本张量。
ControlNetModel 前向方法。
from_unet
< 源 >( 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
) — 要复制到 ControlNetModel 的 UNet 模型权重。所有适用的配置选项也一并复制。
set_attention_slice
< 源 >( slice_size: typing.Union[str, int, typing.List[int]] )
启用分片注意力计算。
启用此选项后,注意力模块会将输入张量分片以分步计算注意力。这对于节省内存非常有用,但会稍微降低速度。
设置注意力处理器
< 源 >( 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, typing.Dict[str, 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]]] )
设置用于计算注意力的注意力处理器。
禁用自定义注意力处理器并设置默认注意力实现。
ControlNetOutput
class diffusers.models.controlnets.ControlNetOutput
< 源 >( down_block_res_samples: typing.Tuple[torch.Tensor] 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 的中间块激活。
ControlNetModel 的输出。
FlaxControlNetModel
class diffusers.FlaxControlNetModel
< 源 >( sample_size: int = 32 in_channels: int = 4 down_block_types: typing.Tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D') 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 attention_head_dim: typing.Union[int, typing.Tuple[int, ...]] = 8 num_attention_heads: typing.Union[int, typing.Tuple[int, ...], NoneType] = None cross_attention_dim: int = 1280 dropout: float = 0.0 use_linear_projection: bool = False dtype: dtype = <class 'jax.numpy.float32'> flip_sin_to_cos: bool = True freq_shift: int = 0 controlnet_conditioning_channel_order: str = 'rgb' conditioning_embedding_out_channels: typing.Tuple[int, ...] = (16, 32, 96, 256) parent: typing.Union[flax.linen.module.Module, flax.core.scope.Scope, flax.linen.module._Sentinel, NoneType] = <flax.linen.module._Sentinel object at 0x7fc460aac610> name: typing.Optional[str] = None )
参数
- sample_size (
int
, 可选) — 输入样本的大小。 - in_channels (
int
, 可选, 默认为 4) — 输入样本中的通道数。 - down_block_types (
Tuple[str]
, 可选, 默认为("FlaxCrossAttnDownBlock2D", "FlaxCrossAttnDownBlock2D", "FlaxCrossAttnDownBlock2D", "FlaxDownBlock2D")
) — 要使用的下采样块元组。 - block_out_channels (
Tuple[int]
, 可选, 默认为(320, 640, 1280, 1280)
) — 每个块的输出通道元组。 - layers_per_block (
int
, 可选, 默认为 2) — 每个块的层数。 - attention_head_dim (
int
或Tuple[int]
, 可选, 默认为 8) — 注意力头的维度。 - num_attention_heads (
int
或Tuple[int]
, 可选) — 注意力头的数量。 - cross_attention_dim (
int
, 可选, 默认为 768) — 交叉注意力特征的维度。 - dropout (
float
, 可选, 默认为 0) — 下、上和瓶颈块的 dropout 概率。 - flip_sin_to_cos (
bool
, 可选, 默认为True
) — 是否在时间嵌入中翻转 sin 到 cos。 - freq_shift (
int
, 可选, 默认为 0) — 应用于时间嵌入的频率偏移。 - controlnet_conditioning_channel_order (
str
, 可选, 默认为rgb
) — 条件图像的通道顺序。如果为bgr
,将转换为rgb
。 - conditioning_embedding_out_channels (
tuple
, 可选, 默认为(16, 32, 96, 256)
) —conditioning_embedding
层中每个块的输出通道元组。
ControlNet模型。
此模型继承自 FlaxModelMixin。请查看超类文档以了解所有模型实现的通用方法(例如下载或保存)。
此模型也是 Flax Linen flax.linen.Module
的子类。请将其作为常规 Flax Linen 模块使用,并参阅 Flax 文档以了解其一般用法和行为相关的所有事宜。
支持以下固有的 JAX 功能
FlaxControlNetOutput
class diffusers.models.controlnets.controlnet_flax.FlaxControlNetOutput
< 源 >( down_block_res_samples: Array mid_block_res_sample: Array )
FlaxControlNetModel 的输出。
返回一个新对象,用新值替换指定的字段。