SD3ControlNetModel

SD3ControlNetModel 是 Stable Diffusion 3 的 ControlNet 实现。

ControlNet 模型由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 Adding Conditional Control to Text-to-Image Diffusion Models 中提出。它通过以边缘图、深度图、分割图以及用于姿态检测的关键点等额外输入作为条件，为文本到图像生成提供了更强的控制能力。

该论文的摘要如下：

我们提出了 ControlNet，一种用于为大型预训练文本到图像扩散模型添加空间条件控制的神经网络架构。ControlNet 锁定生产就绪的大型扩散模型，并复用其使用数十亿张图像预训练得到的深层且鲁棒的编码层作为强大的骨干网络，以学习多样化的条件控制。该神经架构通过“零卷积”（零初始化的卷积层）进行连接，这些层使参数从零开始逐步增长，并确保在微调过程中不会产生有害噪声。我们使用 Stable Diffusion 测试了多种条件控制，例如边缘、深度、分割、人体姿态等，支持使用单一或多个条件，以及有或无提示词的情况。我们展示了 ControlNet 的训练在小规模（<50k）和大规模（>1m）数据集上均具有鲁棒性。大量结果表明，ControlNet 有助于将图像扩散模型的应用扩展到更广泛的领域。

从原始格式加载

默认情况下，SD3ControlNetModel 应使用 from_pretrained() 进行加载。

from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel

controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)

SD3ControlNetModel

类 diffusers.SD3ControlNetModel

< source >

( sample_size: int = 128patch_size: int = 2in_channels: int = 16num_layers: int = 18attention_head_dim: int = 64num_attention_heads: int = 18joint_attention_dim: int = 4096caption_projection_dim: int = 1152pooled_projection_dim: int = 2048out_channels: int = 16pos_embed_max_size: int = 96extra_conditioning_channels: int = 0dual_attention_layers: tuple[int, ...] = ()qk_norm: str | None = Nonepos_embed_type: str | None = 'sincos'use_pos_embed: bool = Trueforce_zeros_for_pooled_projection: bool = True )

参数

sample_size (int，默认为 128) — 潜在表示的宽度/高度。由于用于学习一定数量的位置嵌入，该值在训练期间是固定的。
patch_size (int，默认为 2) — 用于将输入数据划分为小块的块大小。
in_channels (int，默认为 16) — 输入中的潜在通道数。
num_layers (int，默认为 18) — 要使用的 transformer 块层数。
attention_head_dim (int，默认为 64) — 每个头中的通道数。
num_attention_heads (int，默认为 18) — 多头注意力机制中使用的注意力头数量。
joint_attention_dim (int，默认为 4096) — 用于联合文本-图像注意力的嵌入维度。
caption_projection_dim (int，默认为 1152) — 字幕嵌入的嵌入维度。
pooled_projection_dim (int，默认为 2048) — 池化文本投影的嵌入维度。
out_channels (int，默认为 16) — 输出中的潜在通道数。
pos_embed_max_size (int，默认为 96) — 位置嵌入的最大潜在高度/宽度。
extra_conditioning_channels (int，默认为 0) — 用于 patch embedding 的条件信息的额外通道数。
dual_attention_layers (tuple[int, ...]，默认为 ()) — 要使用的双流 Transformer 块的数量。
qk_norm (str，可选，默认为 None) — 注意力层中用于 query 和 key 的归一化方式。如果为 None，则不使用归一化。
pos_embed_type (str，默认为 "sincos") — 要使用的位置编码类型。在 "sincos" 和 None 之间进行选择。
use_pos_embed (bool，默认为 True) — 是否使用位置嵌入。
force_zeros_for_pooled_projection (bool，默认为 True) — 是否强制将池化投影嵌入设为零。这由流水线通过读取 ControlNet 模型的配置值来处理。

用于 Stable Diffusion 3 的 ControlNet 模型。

enable_forward_chunking

< source >

( chunk_size: int | None = Nonedim: int = 0 )

参数

chunk_size (int, 可选) — 前馈层的块大小。如果未指定，将对每个 dim=dim 的张量单独运行前馈层。
dim (int，可选，默认为 0) — 前馈计算应进行分块的维度。可选择 dim=0（批次）或 dim=1（序列长度）。

将注意力处理器设置为使用前馈分块。

forward

< source >

( hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0encoder_hidden_states: Tensor = Nonepooled_projections: Tensor = Nonetimestep: LongTensor = Nonejoint_attention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True )

参数

hidden_states（形状为 (batch size, channel, height, width) 的 torch.Tensor）— 输入的 hidden_states。
controlnet_cond (torch.Tensor) — 形状为 (batch_size, sequence_length, hidden_size) 的条件输入张量。
conditioning_scale (float，默认为 1.0) — ControlNet 输出的缩放因子。
encoder_hidden_states（形状为 (batch size, sequence_len, embed_dims) 的 torch.Tensor）— 要使用的条件嵌入（例如从提示词等输入条件计算得出的嵌入）。
pooled_projections（形状为 (batch_size, projection_dim) 的 torch.Tensor）— 由输入条件的嵌入投影得到的嵌入。
timestep ( torch.LongTensor) — 用于指示去噪步骤。
joint_attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，将作为参数传递给 diffusers.models.attention_processor 中 self.processor 下定义的 AttentionProcessor。
return_dict (bool，可选，默认为 True) — 是否返回 ~models.transformer_2d.Transformer2DModelOutput 而不是普通的元组。