Diffusers 文件
ControlNetUnionModel
並獲得增強的文件體驗
開始使用
ControlNetUnionModel
ControlNetUnionModel 是 Stable Diffusion XL 的 ControlNet 實現。
ControlNet 模型由 xinsir6 在 ControlNetPlus 中引入。它支援多個條件輸入而無需增加計算量。
我們設計了一種新架構，可以在條件文字到影像生成中支援 10 多種控制型別，並且可以生成視覺效果與 midjourney 媲美的高解析度影像。該網路基於原始 ControlNet 架構，我們提出了兩個新模組：1. 擴充套件原始 ControlNet 以支援使用相同網路引數的不同影像條件。2. 支援多個條件輸入而無需增加計算解除安裝，這對於想要詳細編輯影像的設計師來說尤其重要，不同的條件使用相同的條件編碼器，無需額外的計算或引數。
載入
預設情況下，應使用 ControlNetUnionModel 載入 from_pretrained()。
from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel
controlnet = ControlNetUnionModel.from_pretrained("xinsir/controlnet-union-sdxl-1.0")
pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet)ControlNetUnionModel
class diffusers.ControlNetUnionModel
< 來源 >( 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') 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, ...]] = (48, 96, 192, 384) global_pool_conditions: bool = False addition_embed_type_num_heads: int = 64 num_control_type: int = 6 num_trans_channel: int = 320 num_trans_head: int = 8 num_trans_layer: int = 1 num_proj_channel: int = 320 )
引數
- 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], 可選, 預設為(48, 96, 192, 384)) —conditioning_embedding層中每個塊的輸出通道元組。 - global_pool_conditions (
bool, 預設為False) —
ControlNetUnion 模型。
forward
< 來源 >( sample: Tensor timestep: typing.Union[torch.Tensor, float, int] encoder_hidden_states: Tensor controlnet_cond: typing.List[torch.Tensor] control_type: Tensor control_type_idx: typing.List[int] conditioning_scale: typing.Union[float, typing.List[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 from_multi: bool = False 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 (
List[torch.Tensor]) — 條件輸入張量。 - control_type (
torch.Tensor) — 形狀為(batch, num_control_type)的張量，其值根據是否使用控制型別為0或1。 - control_type_idx (
List[int]) —control_type的索引。 - 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。 - from_multi (
bool, 預設為False) — 當從MultiControlNetUnionModel呼叫時，使用標準縮放。 - guess_mode (
bool, 預設為False) — 在此模式下，ControlNet 編碼器會盡力識別輸入的輸入內容，即使您刪除了所有提示。建議guidance_scale在 3.0 到 5.0 之間。 - return_dict (
bool, 預設為True) — 是否返回ControlNetOutput而不是普通元組。
返回
ControlNetOutput 或 tuple
如果 return_dict 為 True，則返回 ControlNetOutput，否則返回一個元組，其中第一個元素是樣本張量。
ControlNetUnionModel 的 forward 方法。
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 )
引數
- unet (
UNet2DConditionModel) — 要複製到 ControlNetUnionModel 的 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, 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]]] )
設定用於計算注意力的注意力處理器。
停用自定義注意力處理器並設定預設注意力實現。