Hugging Face 的 LOGO

Diffusers 文件

SparseControlNetModel

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

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

< >

( 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 模型權重。所有適用的配置選項也會被複制。

從 UNet2DConditionModel 例項化一個 SparseControlNetModel。

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

引數

  • processor (AttentionProcessor 的 dict 或僅 AttentionProcessor) — 例項化的處理器類或處理器類的字典，將設定為**所有** Attention 層的處理器。

    如果 processor 是一個字典，鍵需要定義到相應交叉注意力處理器的路徑。在設定可訓練的注意力處理器時，強烈建議這樣做。

設定用於計算注意力的注意力處理器。

set_default_attn_processor

< >

( )

停用自定義注意力處理器並設定預設注意力實現。

SparseControlNetOutput

class diffusers.models.controlnet_sparsectrl.SparseControlNetOutput

< >

( *args **kwargs )

< > 在 GitHub 上更新

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