Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

2 days ago

preview code

download

raw

5.72 kB

# FluxControlNetModel

FluxControlNetModel 是 Flux.1 的 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 有助于将图像扩散模型的应用扩展到更广泛的领域。*

## 从原始格式加载

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

```py
from diffusers import FluxControlNetPipeline
from diffusers.models import FluxControlNetModel, FluxMultiControlNetModel
controlnet = FluxControlNetModel.from_pretrained("InstantX/FLUX.1-dev-Controlnet-Canny")
pipe = FluxControlNetPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", controlnet=controlnet)
controlnet = FluxControlNetModel.from_pretrained("InstantX/FLUX.1-dev-Controlnet-Canny")
controlnet = FluxMultiControlNetModel([controlnet])
pipe = FluxControlNetPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", controlnet=controlnet)
```

## FluxControlNetModel[[diffusers.FluxControlNetModel]]

#### diffusers.FluxControlNetModel[[diffusers.FluxControlNetModel]]

```python
diffusers.FluxControlNetModel(patch_size: int = 1, in_channels: int = 64, num_layers: int = 19, num_single_layers: int = 38, attention_head_dim: int = 128, num_attention_heads: int = 24, joint_attention_dim: int = 4096, pooled_projection_dim: int = 768, guidance_embeds: bool = False, axes_dims_rope: list[int] = [16, 56, 56], num_mode: int = None, conditioning_embedding_channels: int = None)
```

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

#### forward[[diffusers.FluxControlNetModel.forward]]

```python
forward(hidden_states: Tensor, controlnet_cond: Tensor, controlnet_mode: Tensor = None, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, img_ids: Tensor = None, txt_ids: Tensor = None, guidance: Tensor = 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_flux.py#L157)

**参数：**

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

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

controlnet_mode (`torch.Tensor`) : 形状为 `(batch_size, 1)` 的模式张量。

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

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

img_ids (`torch.Tensor`) : 图像 token 的位置 ID。
txt_ids (`torch.Tensor`) : 文本 token 的位置 ID。

guidance (`torch.Tensor`, *可选*) : 模型引导蒸馏变体所使用的引导尺度张量。

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`，其中第一个元素是样本张量。

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

## FluxControlNetOutput[[diffusers.models.controlnets.FluxControlNetOutput]]

#### diffusers.models.controlnets.FluxControlNetOutput[[diffusers.models.controlnets.FluxControlNetOutput]]

```python
diffusers.models.controlnets.FluxControlNetOutput(controlnet_block_samples: tuple[torch.Tensor], controlnet_single_block_samples: tuple[torch.Tensor])
```

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

Xet Storage Details

Size:: 5.72 kB
Xet hash:: 1521b680c009c0e372ef100fc6bf57d0ddd55c5c67f4d8ba198f90eea326d46d

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

	# FluxControlNetModel

	FluxControlNetModel 是 Flux.1 的 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 有助于将图像扩散模型的应用扩展到更广泛的领域。

	## 从原始格式加载

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

	```py
	from diffusers import FluxControlNetPipeline
	from diffusers.models import FluxControlNetModel, FluxMultiControlNetModel

	controlnet = FluxControlNetModel.from_pretrained("InstantX/FLUX.1-dev-Controlnet-Canny")
	pipe = FluxControlNetPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", controlnet=controlnet)

	controlnet = FluxControlNetModel.from_pretrained("InstantX/FLUX.1-dev-Controlnet-Canny")
	controlnet = FluxMultiControlNetModel([controlnet])
	pipe = FluxControlNetPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", controlnet=controlnet)
	```

	## FluxControlNetModel[[diffusers.FluxControlNetModel]]

	#### diffusers.FluxControlNetModel[[diffusers.FluxControlNetModel]]

	```python
	diffusers.FluxControlNetModel(patch_size: int = 1, in_channels: int = 64, num_layers: int = 19, num_single_layers: int = 38, attention_head_dim: int = 128, num_attention_heads: int = 24, joint_attention_dim: int = 4096, pooled_projection_dim: int = 768, guidance_embeds: bool = False, axes_dims_rope: list[int] = [16, 56, 56], num_mode: int = None, conditioning_embedding_channels: int = None)
	```

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

	#### forward[[diffusers.FluxControlNetModel.forward]]

	```python
	forward(hidden_states: Tensor, controlnet_cond: Tensor, controlnet_mode: Tensor = None, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, img_ids: Tensor = None, txt_ids: Tensor = None, guidance: Tensor = 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_flux.py#L157)

	参数：

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

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

	controlnet_mode (`torch.Tensor`) : 形状为 `(batch_size, 1)` 的模式张量。

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

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

	pooled_projections (`torch.FloatTensor`，形状为 `(batch_size, projection_dim)`) : 从输入条件的嵌入中投影得到的嵌入。

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

	img_ids (`torch.Tensor`) : 图像 token 的位置 ID。

	txt_ids (`torch.Tensor`) : 文本 token 的位置 ID。

	guidance (`torch.Tensor`, 可选) : 模型引导蒸馏变体所使用的引导尺度张量。

	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`，其中第一个元素是样本张量。

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

	## FluxControlNetOutput[[diffusers.models.controlnets.FluxControlNetOutput]]

	#### diffusers.models.controlnets.FluxControlNetOutput[[diffusers.models.controlnets.FluxControlNetOutput]]

	```python
	diffusers.models.controlnets.FluxControlNetOutput(controlnet_block_samples: tuple[torch.Tensor], controlnet_single_block_samples: tuple[torch.Tensor])
	```

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