Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /zh /api /models /controlnet_sd3.md

mishig

2 days ago

preview code

download

raw

8.64 kB

# SD3ControlNetModel

SD3ControlNetModel 是 Stable Diffusion 3 的 ControlNet 实现。

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

该论文的摘要如下：

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

## 从原始格式加载

默认情况下，[SD3ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) 应使用 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/models/overview#diffusers.ModelMixin.from_pretrained) 进行加载。

```py
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]]

#### diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

```python
diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, 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, dual_attention_layers: tuple[int, ...] = (), qk_norm: str | None = None, pos_embed_type: str | None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L42)

**参数：**

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`)：注意力层中用于查询和键的归一化方式。如果为 `None`，则不使用归一化。
pos_embed_type (`str`，默认为 `"sincos"`)：要使用的位置嵌入类型。在 `"sincos"` 和 `None` 之间进行选择。
use_pos_embed (`bool`，默认为 `True`) : 是否使用位置嵌入。
force_zeros_for_pooled_projection (`bool`，默认为 `True`)：是否强制将池化投影嵌入设为零。此行为由流水线通过读取 ControlNet 模型的配置值来处理。
用于 [Stable Diffusion 3](https://huggingface.co/papers/2403.03206) 的 ControlNet 模型。
#### enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]
```python
enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)
```
[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L178)
**参数：**
chunk_size (`int`, *可选*) : 前馈层的块大小。如果未指定，则对每个 dim=`dim` 的张量单独运行前馈层。
dim (`int`，*可选*，默认为 `0`)：前馈计算应进行分块的维度。在 dim=0（批次）或 dim=1（序列长度）之间选择。
将注意力处理器设置为使用 [前馈分块](https://huggingface.co/blog/reformer#2-chunked-feed-forward-layers)。
#### forward[[diffusers.SD3ControlNetModel.forward]]
```python
forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```
[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L272)
**参数：**
hidden_states (`torch.Tensor`，形状为 `(batch size, channel, height, width)`) : 输入 `hidden_states`。

controlnet_cond (`torch.Tensor`) : 形状为 `(batch_size, sequence_length, hidden_size)` 的条件输入张量。

conditioning_scale (`float`，默认为 `1.0`)：ControlNet 输出的缩放因子。
encoder_hidden_states (`torch.Tensor`，形状为 `(batch size, sequence_len, embed_dims)`)：要使用的条件嵌入（根据输入条件（例如提示词）计算得出的嵌入）。
pooled_projections (`torch.Tensor`，形状为 `(batch_size, projection_dim)`)：由输入条件的嵌入投影得到的嵌入。

timestep ( `torch.LongTensor`) ：用于指示去噪步骤。

joint_attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~models.transformer_2d.Transformer2DModelOutput` 而不是普通元组。

**返回值：**

如果 `return_dict` 为 True，则返回 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是样本张量。

[SD3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel) 的前向方法。

#### fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L208)

启用融合的 QKV 投影。对于自注意力模块，所有投影矩阵（即 query、key、value）均会被融合。对于交叉注意力模块，key 和 value 投影矩阵会被融合。

> [!WARNING] > 此 API 处于 🧪 实验阶段。

#### unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L230)

如果已启用，则禁用融合的 QKV 投影。

> [!WARNING] > 此 API 处于 🧪 实验阶段。

## SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

#### diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

```python
diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple[torch.Tensor])
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L38)

Xet Storage Details

Size:: 8.64 kB
Xet hash:: 5ed81e9c579b11aa4f2e7b37c622a24c057275e321db3f43cb29cbdb24c3cfeb

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# SD3ControlNetModel

	SD3ControlNetModel 是 Stable Diffusion 3 的 ControlNet 实现。

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

	该论文的摘要如下：

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

	## 从原始格式加载

	默认情况下，[SD3ControlNetModel](/docs/diffusers/v0.43.0/zh/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) 应使用 [from_pretrained()](/docs/diffusers/v0.43.0/zh/api/models/overview#diffusers.ModelMixin.from_pretrained) 进行加载。

	```py
	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]]

	#### diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

	```python
	diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, 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, dual_attention_layers: tuple[int, ...] = (), qk_norm: str \| None = None, pos_embed_type: str \| None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L42)

	参数：

	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`)：注意力层中用于查询和键的归一化方式。如果为 `None`，则不使用归一化。

	pos_embed_type (`str`，默认为 `"sincos"`)：要使用的位置嵌入类型。在 `"sincos"` 和 `None` 之间进行选择。

	use_pos_embed (`bool`，默认为 `True`) : 是否使用位置嵌入。

	force_zeros_for_pooled_projection (`bool`，默认为 `True`)：是否强制将池化投影嵌入设为零。此行为由流水线通过读取 ControlNet 模型的配置值来处理。

	用于 [Stable Diffusion 3](https://huggingface.co/papers/2403.03206) 的 ControlNet 模型。

	#### enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]

	```python
	enable_forward_chunking(chunk_size: int \| None = None, dim: int = 0)
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L178)

	参数：

	chunk_size (`int`, 可选) : 前馈层的块大小。如果未指定，则对每个 dim=`dim` 的张量单独运行前馈层。

	dim (`int`，可选，默认为 `0`)：前馈计算应进行分块的维度。在 dim=0（批次）或 dim=1（序列长度）之间选择。

	将注意力处理器设置为使用 [前馈分块](https://huggingface.co/blog/reformer#2-chunked-feed-forward-layers)。

	#### forward[[diffusers.SD3ControlNetModel.forward]]

	```python
	forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] \| None = None, return_dict: bool = True)
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L272)

	参数：

	hidden_states (`torch.Tensor`，形状为 `(batch size, channel, height, width)`) : 输入 `hidden_states`。

	controlnet_cond (`torch.Tensor`) : 形状为 `(batch_size, sequence_length, hidden_size)` 的条件输入张量。

	conditioning_scale (`float`，默认为 `1.0`)：ControlNet 输出的缩放因子。

	encoder_hidden_states (`torch.Tensor`，形状为 `(batch size, sequence_len, embed_dims)`)：要使用的条件嵌入（根据输入条件（例如提示词）计算得出的嵌入）。

	pooled_projections (`torch.Tensor`，形状为 `(batch_size, projection_dim)`)：由输入条件的嵌入投影得到的嵌入。

	timestep ( `torch.LongTensor`) ：用于指示去噪步骤。

	joint_attention_kwargs (`dict`, 可选) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。

	return_dict (`bool`，可选，默认为 `True`)：是否返回 `~models.transformer_2d.Transformer2DModelOutput` 而不是普通元组。

	返回值：

	如果 `return_dict` 为 True，则返回 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是样本张量。

	[SD3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel) 的前向方法。

	#### fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

	```python
	fuse_qkv_projections()
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L208)

	启用融合的 QKV 投影。对于自注意力模块，所有投影矩阵（即 query、key、value）均会被融合。对于交叉注意力模块，key 和 value 投影矩阵会被融合。

	> [!WARNING] > 此 API 处于 🧪 实验阶段。

	#### unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

	```python
	unfuse_qkv_projections()
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L230)

	如果已启用，则禁用融合的 QKV 投影。

	> [!WARNING] > 此 API 处于 🧪 实验阶段。

	## SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

	#### diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

	```python
	diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple[torch.Tensor])
	```

	[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L38)