Hugging Face 的标志

Diffusers 文档

ControlNetModel

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始

ControlNetModel

ControlNet 模型在 Adding Conditional Control to Text-to-Image Diffusion Models 这篇论文中被提出，作者是 Lvmin Zhang, Anyi Rao, Maneesh Agrawala。它通过在模型上添加额外的输入条件，例如边缘图、深度图、分割图和姿势检测的关键点，从而提供对文本到图像生成更高级别的控制。

以下是论文的摘要

我们提出了 ControlNet，一种神经网络架构，用于向大型预训练的文本到图像扩散模型添加空间条件控制。ControlNet 锁定了生产就绪的大型扩散模型，并重用它们通过数十亿图像进行预训练的深度和强大的编码层，作为学习各种条件控制的强大骨干。该神经网络架构与“零卷积”（零初始化的卷积层）连接，这些卷积层逐渐从零增长参数，并确保没有有害噪声会影响微调。我们使用 Stable Diffusion 测试了各种条件控制，例如，边缘、深度、分割、人体姿势等，使用单个或多个条件，有或没有提示。结果表明，ControlNet 的训练对于小型（<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)

ControlNetModel

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], 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) — 用于归一化的组数。如果为 None，则后处理中会跳过归一化和激活层。默认为 32。
  • 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。
  • encoder_hid_dim (int, optional, defaults to None) — 如果定义了 encoder_hid_dim_type，则 encoder_hidden_states 将从 encoder_hid_dim 维度投影到 cross_attention_dim。
  • encoder_hid_dim_type (str, optional, defaults to None) — 如果给定，则 encoder_hidden_states 以及潜在的其他嵌入将根据 encoder_hid_dim_type 向下投影到维度为 cross_attention 的文本嵌入。
  • attention_head_dim (Union[int, Tuple[int]], defaults to 8) — 注意力头的维度。默认为 8。
  • use_linear_projection (bool, defaults to False) —
  • class_embed_type (str, optional, defaults to None) — 要使用的类别嵌入类型，最终与时间步长嵌入求和。从 None, "timestep", "identity", "projection", 或 "simple_projection" 中选择。默认为 None。
  • addition_embed_type (str, optional, defaults to None) — 配置可选的嵌入，它将与时间步长嵌入求和。从 None 或 “text” 中选择。“text” 将使用 TextTimeEmbedding 层。默认为 None。
  • num_class_embeds (int, optional, defaults to 0) — 当使用 class_embed_type 等于 None 执行类别条件控制时，可学习嵌入矩阵的输入维度将被投影到 time_embed_dim。默认为 0。
  • upcast_attention (bool, defaults to False) —
  • resnet_time_scale_shift (str, defaults to "default") — ResNet 块的时间尺度偏移配置（参见 ResnetBlock2D）。从 default 或 scale_shift 中选择。默认为 "default"。
  • projection_class_embeddings_input_dim (int, optional, defaults to None) — 当 class_embed_type="projection" 时，class_labels 输入的维度。当 class_embed_type="projection" 时为必需。默认为 None。
  • controlnet_conditioning_channel_order (str, defaults to "rgb") — 条件图像的通道顺序。如果是 bgr，将转换为 rgb。默认为 "rgb"。
  • conditioning_embedding_out_channels (tuple[int], optional, defaults to (16, 32, 96, 256)) — conditioning_embedding 层中每个块的输出通道元组。默认为 (16, 32, 96, 256)。
  • global_pool_conditions (bool, defaults to False) — TODO(Patrick) - 未使用的参数。
  • addition_embed_type_num_heads (int, defaults to 64) — 用于 TextTimeEmbedding 层的头的数量。默认为 64。

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]) — 用于去噪输入的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) — 用于条件控制的可选类别标签。它们的嵌入将与时间步长嵌入求和。默认为 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，否则返回一个元组，其中第一个元素是 sample 张量。

The ControlNetModel forward 方法。

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 模型权重。所有配置选项也会在适用的情况下复制。

从 UNet2DConditionModel 实例化 ControlNetModel。

set_attention_slice

< >

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

参数

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

启用切片注意力计算。

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

set_attn_processor

< >

( 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]]] )

参数

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

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

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

set_default_attn_processor

< >

( )

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

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 0x7f484d8851e0> 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 )

参数

  • down_block_res_samples (jnp.ndarray) —
  • mid_block_res_sample (jnp.ndarray) —

FlaxControlNetModel 的输出。

replace

 < >

( **updates )

返回一个新对象，将指定的字段替换为新值。

< > 在 GitHub 上更新

←概述 FluxControlNetModel→