Hugging Face 的 LOGO

Diffusers 文件

ControlNet模型

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

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 模型權重。所有適用的配置選項也一併複製。

從 UNet2DConditionModel 例項化 ControlNetModel。

set_attention_slice

< >

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

引數

  • slice_size (str 或 int 或 list(int), 可選, 預設為 "auto") — 當為 "auto" 時，注意力頭部的輸入減半，因此注意力分兩步計算。如果為 "max"，則透過一次只執行一個切片來節省最大記憶體。如果提供一個數字，則使用 attention_head_dim // slice_size 個切片。在這種情況下，attention_head_dim 必須是 slice_size 的倍數。

啟用分片注意力計算。

啟用此選項後，注意力模組會將輸入張量分片以分步計算注意力。這對於節省記憶體非常有用，但會稍微降低速度。

設定注意力處理器

< >

( 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 (AttentionProcessor 的 dict 或僅為 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 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 )

引數

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

FlaxControlNetModel 的輸出。

替換

< >

( **updates )

返回一個新物件，用新值替換指定的欄位。

< > 在 GitHub 上更新

←AutoModel ControlNetUnionModel→
© . This site is unofficial and not affiliated with Hugging Face, Inc.