diffusers/v0.43.0/zh/api/models/controlnet_union.md

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[[diffusers.ControlNetUnionModel]]

diffusers.ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

diffusers.ControlNetUnionModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), only_cross_attention: 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 | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 1280, transformer_layers_per_block: int | tuple[int, ...] = 1, encoder_hid_dim: int | None = None, encoder_hid_dim_type: str | None = None, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, class_embed_type: str | None = None, addition_embed_type: str | None = None, addition_time_embed_dim: int | None = None, num_class_embeds: int | None = None, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', projection_class_embeddings_input_dim: int | None = None, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (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 (bool | tuple[bool]，默认为 False) --

block_out_channels (tuple[int]，默认为 (320, 640, 1280, 1280))：每个 block 的输出通道数元组。

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_hid_dim_type 将 encoder_hidden_states 及其他潜在嵌入下投影到维度为 cross_attention 的文本嵌入。

attention_head_dim (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。

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

A ControlNetUnion 模型。

forward[[diffusers.ControlNetUnionModel.forward]]

forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: list[torch.Tensor], control_type: Tensor, control_type_idx: list[int], conditioning_scale: float | 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: dict[str, torch.Tensor] | None = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, from_multi: bool = False, guess_mode: bool = False, return_dict: bool = True)

源代码

参数：

sample (torch.Tensor) : 带噪声的输入张量。

timestep (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 层传入的 timestep_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)：是否返回 ~models.controlnet.ControlNetOutput 而不是普通元组。

返回： ~models.controlnet.ControlNetOutput 或 tuple

如果 return_dict 为 True，则返回 ~models.controlnet.ControlNetOutput，否则返回一个元组，其中第一个元素是样本张量。

ControlNetUnionModel 的前向方法。

from_unet[[diffusers.ControlNetUnionModel.from_unet]]

from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True)

源代码

参数：

unet (UNet2DConditionModel)：要复制到 ControlNetUnionModel 的 UNet 模型权重。所有适用的配置选项也会一并复制。

从 UNet2DConditionModel 实例化一个 ControlNetUnionModel。

set_attention_slice[[diffusers.ControlNetUnionModel.set_attention_slice]]

set_attention_slice(slice_size: str | int | list[int])

源代码

参数：

slice_size (str 或 int 或 list(int)，可选，默认为 "auto")：当值为 "auto" 时，输入到注意力头的张量会被减半，因此注意力计算分两步进行。如果值为 "max"，则每次只运行一个切片，以节省最大内存。如果提供数字，则使用 attention_head_dim // slice_size 个切片。在这种情况下，attention_head_dim 必须是 slice_size 的倍数。

启用切片注意力计算。

启用此选项后，注意力模块会将输入张量切分为多个切片，分步计算注意力。这有助于节省部分内存，但会略微降低速度。

set_default_attn_processor[[diffusers.ControlNetUnionModel.set_default_attn_processor]]

set_default_attn_processor()

源代码

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