Diffusers documentation
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
类 diffusers.ControlNetUnionModel
< source >( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 1280transformer_layers_per_block: int | tuple[int, ...] = 1encoder_hid_dim: int | None = Noneencoder_hid_dim_type: str | None = Noneattention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseclass_embed_type: str | None = Noneaddition_embed_type: str | None = Noneaddition_time_embed_dim: int | None = Nonenum_class_embeds: int | None = Noneupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'projection_class_embeddings_input_dim: int | None = Nonecontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (48, 96, 192, 384)global_pool_conditions: bool = Falseaddition_embed_type_num_heads: int = 64num_control_type: int = 6num_trans_channel: int = 320num_trans_head: int = 8num_trans_layer: int = 1num_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)) — 每个块的输出通道数元组。 - 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 (
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
< source >( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: list[torch.Tensor]control_type: Tensorcontrol_type_idx: list[int]conditioning_scale: float | list[float] = 1.0class_labels: typing.Optional[torch.Tensor] = Nonetimestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneadded_cond_kwargs: dict[str, torch.Tensor] | None = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Nonefrom_multi: bool = Falseguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.ControlNetOutput or tuple
参数
- 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
< source >( unet: UNet2DConditionModelcontrolnet_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
< source >( slice_size: str | int | list[int] )
启用切片注意力计算。
启用此选项后，注意力模块会将输入张量切分为多个切片，分步计算注意力。这有助于节省部分内存，但会略微降低速度。
禁用自定义注意力处理器并设置默认的注意力实现。