Diffusers 文档
带Flux.1的ControlNet
并获得增强的文档体验
开始使用
带Flux.1的ControlNet
FluxControlNetPipeline是ControlNet在Flux.1上的实现。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《为文本到图像扩散模型添加条件控制》 中提出。
使用ControlNet模型，您可以提供额外的控制图像来条件化和控制Stable Diffusion生成。例如，如果您提供深度图，ControlNet模型将生成一张图像，该图像将保留深度图中的空间信息。这是一种更灵活、更准确地控制图像生成过程的方法。
论文摘要如下：
我们提出了ControlNet，这是一种神经网络架构，用于为大型预训练的文本到图像扩散模型添加空间条件控制。ControlNet锁定生产就绪的大型扩散模型，并重用它们通过数十亿张图像预训练的深度且鲁棒的编码层作为强大的骨干网络，以学习多样化的条件控制集。该神经网络架构通过“零卷积”（零初始化卷积层）连接，这些卷积层从零开始逐步增长参数，并确保不会有有害噪声影响微调。我们使用Stable Diffusion测试了各种条件控制，例如边缘、深度、分割、人体姿态等，使用单一或多个条件，有或没有提示词。我们表明，ControlNets的训练对于小型（<50k）和大型（>1m）数据集都非常稳定。大量结果表明，ControlNet可能促进图像扩散模型更广泛的应用。
此ControlNet代码由The InstantX Team实现。您可以在下表中找到Flux-ControlNet的预训练检查点
| ControlNet类型 | 开发者 | 链接 |
|---|---|---|
| 边缘检测 | The InstantX Team | 链接 |
| 深度 | The InstantX Team | 链接 |
| Union | The InstantX Team | 链接 |
还支持XLabs ControlNets，该模型由XLabs团队贡献。
| ControlNet类型 | 开发者 | 链接 |
|---|---|---|
| 边缘检测 | XLabs团队 | 链接 |
| 深度 | XLabs团队 | 链接 |
| HED | XLabs团队 | 链接 |
FluxControlNetPipeline
class diffusers.FluxControlNetPipeline
< 来源 >( 调度器: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL text_encoder: CLIPTextModel tokenizer: CLIPTokenizer text_encoder_2: T5EncoderModel tokenizer_2: T5TokenizerFast transformer: FluxTransformer2DModel controlnet: typing.Union[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel, typing.List[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel], diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModel] image_encoder: CLIPVisionModelWithProjection = None feature_extractor: CLIPImageProcessor = None )
参数
- transformer (FluxTransformer2DModel) — 用于对编码图像潜变量进行去噪的条件Transformer (MMDiT) 架构。
- 调度器 (FlowMatchEulerDiscreteScheduler) — 与
transformer结合使用的调度器，用于对编码图像潜变量进行去噪。 - vae (AutoencoderKL) — 用于将图像编码和解码为潜在表示的变分自编码器 (VAE) 模型。
- text_encoder (
CLIPTextModel) — CLIP，特别是clip-vit-large-patch14变体。 - text_encoder_2 (
T5EncoderModel) — T5，特别是google/t5-v1_1-xxl变体。 - tokenizer (
CLIPTokenizer) — CLIPTokenizer类的分词器。 - tokenizer_2 (
T5TokenizerFast) — 第二个分词器，属于T5TokenizerFast类。
用于文本到图像生成的 Flux 管道。
参考：https://blackforestlabs.ai/announcing-black-forest-labs/
__call__
< 来源 >( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt: typing.Union[str, typing.List[str]] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None true_cfg_scale: float = 1.0 height: typing.Optional[int] = None width: typing.Optional[int] = None num_inference_steps: int = 28 sigmas: typing.Optional[typing.List[float]] = None guidance_scale: float = 7.0 control_guidance_start: typing.Union[float, typing.List[float]] = 0.0 control_guidance_end: typing.Union[float, typing.List[float]] = 1.0 control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None control_mode: typing.Union[int, typing.List[int], NoneType] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 num_images_per_prompt: typing.Optional[int] = 1 generator: typing.Union[torch._C.Generator, typing.List[torch._C.Generator], NoneType] = None latents: typing.Optional[torch.FloatTensor] = None prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None ip_adapter_image_embeds: typing.Optional[typing.List[torch.Tensor]] = None negative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None negative_ip_adapter_image_embeds: typing.Optional[typing.List[torch.Tensor]] = None negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'] max_sequence_length: int = 512 ) → ~pipelines.flux.FluxPipelineOutput 或 tuple
参数
- prompt (
str或List[str]，可选) — 用于引导图像生成的提示词。如果未定义，则必须传入prompt_embeds。 - prompt_2 (
str或List[str]，可选) — 将发送给tokenizer_2和text_encoder_2的提示词。如果未定义，将使用prompt。 - height (
int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的像素高度。为获得最佳效果，默认设置为 1024。 - width (
int，可选，默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的像素宽度。为获得最佳效果，默认设置为 1024。 - num_inference_steps (
int，可选，默认为 50) — 去噪步数。更多去噪步数通常会带来更高质量的图像，但推理速度会变慢。 - sigmas (
List[float]，可选) — 用于去噪过程的自定义sigmas，适用于在其set_timesteps方法中支持sigmas参数的调度器。如果未定义，将使用传入num_inference_steps时的默认行为。 - guidance_scale (
float，可选，默认为 7.0) — Classifier-Free Diffusion Guidance中定义的指导比例。guidance_scale定义为Imagen Paper方程2中的w。通过设置guidance_scale > 1启用指导比例。更高的指导比例会鼓励生成与文本prompt更紧密相关的图像，通常以牺牲图像质量为代价。 - control_guidance_start (
float或List[float]，可选，默认为 0.0) — ControlNet开始应用的总体步骤的百分比。 - control_guidance_end (
float或List[float]，可选，默认为 1.0) — ControlNet停止应用的总体步骤的百分比。 - control_image (
torch.Tensor,PIL.Image.Image,np.ndarray,List[torch.Tensor],List[PIL.Image.Image],List[np.ndarray], —List[List[torch.Tensor]],List[List[np.ndarray]]或List[List[PIL.Image.Image]])：ControlNet输入条件，为unet提供生成指导。如果类型指定为torch.Tensor，则按原样传递给ControlNet。PIL.Image.Image也可以作为图像接受。输出图像的尺寸默认为image的尺寸。如果传入高度和/或宽度，则image将相应调整大小。如果在init中指定了多个ControlNet，则图像必须作为列表传递，以便列表的每个元素都可以正确批处理以输入到单个ControlNet中。 - controlnet_conditioning_scale (
float或List[float]，可选，默认为 1.0) — ControlNet的输出在添加到原始unet中的残差之前乘以controlnet_conditioning_scale。如果在init中指定了多个ControlNet，则可以将相应的比例设置为列表。 - control_mode (
int或List[int]，可选，默认为 None) — 应用ControlNet-Union时的控制模式。 - num_images_per_prompt (
int，可选，默认为 1) — 每个提示词生成的图像数量。 - generator (
torch.Generator或List[torch.Generator], 可选) — 一个或多个 torch 生成器，用于使生成具有确定性。 - latents (
torch.FloatTensor, 可选) — 预生成的噪声潜在变量，从高斯分布中采样，用作图像生成的输入。可用于使用不同的提示来调整相同的生成。如果未提供，将使用提供的随机generator进行采样以生成潜在张量。 - prompt_embeds (
torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从prompt输入参数生成文本嵌入。 - pooled_prompt_embeds (
torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从prompt输入参数生成池化文本嵌入。 - ip_adapter_image — (
PipelineImageInput, 可选)：用于 IP Adapters 的可选图像输入。 - ip_adapter_image_embeds (
List[torch.Tensor], 可选) — IP-Adapter 预生成的图像嵌入。它应该是一个列表，长度与 IP-adapter 的数量相同。每个元素都应该是一个形状为(batch_size, num_images, emb_dim)的张量。如果未提供，嵌入将从ip_adapter_image输入参数计算。 - negative_ip_adapter_image — (
PipelineImageInput, 可选)：用于 IP Adapters 的可选图像输入。 - negative_ip_adapter_image_embeds (
List[torch.Tensor], 可选) — IP-Adapter 预生成的图像嵌入。它应该是一个列表，长度与 IP-adapter 的数量相同。每个元素都应该是一个形状为(batch_size, num_images, emb_dim)的张量。如果未提供，嵌入将从ip_adapter_image输入参数计算。 - output_type (
str, 可选, 默认为"pil") — 生成图像的输出格式。选择 PIL:PIL.Image.Image或np.array。 - return_dict (
bool, 可选, 默认为True) — 是否返回~pipelines.flux.FluxPipelineOutput而不是普通元组。 - joint_attention_kwargs (
dict, 可选) — 一个 kwargs 字典，如果指定，将作为参数传递给 diffusers.models.attention_processor 中定义的self.processor的AttentionProcessor。 - callback_on_step_end (
Callable, 可选) — 在推理过程中，每个去噪步骤结束时调用的函数。该函数将使用以下参数调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs将包含callback_on_step_end_tensor_inputs指定的所有张量列表。 - callback_on_step_end_tensor_inputs (
List, 可选) —callback_on_step_end函数的张量输入列表。列表中指定的张量将作为callback_kwargs参数传递。您只能包含管道类._callback_tensor_inputs属性中列出的变量。 - max_sequence_length (
int默认为 512) — 与prompt一起使用的最大序列长度。
返回
~pipelines.flux.FluxPipelineOutput 或 tuple
如果 return_dict 为 True，则为 ~pipelines.flux.FluxPipelineOutput，否则为 tuple。返回元组时，第一个元素是生成的图像列表。
调用管道进行生成时调用的函数。
示例
>>> import torch
>>> from diffusers.utils import load_image
>>> from diffusers import FluxControlNetPipeline
>>> from diffusers import FluxControlNetModel
>>> base_model = "black-forest-labs/FLUX.1-dev"
>>> controlnet_model = "InstantX/FLUX.1-dev-controlnet-canny"
>>> controlnet = FluxControlNetModel.from_pretrained(controlnet_model, torch_dtype=torch.bfloat16)
>>> pipe = FluxControlNetPipeline.from_pretrained(
... base_model, controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg")
>>> prompt = "A girl in city, 25 years old, cool, futuristic"
>>> image = pipe(
... prompt,
... control_image=control_image,
... control_guidance_start=0.2,
... control_guidance_end=0.8,
... controlnet_conditioning_scale=1.0,
... num_inference_steps=28,
... guidance_scale=3.5,
... ).images[0]
>>> image.save("flux.png")encode_prompt
< 源文件 >( prompt: typing.Union[str, typing.List[str]] prompt_2: typing.Union[str, typing.List[str]] device: typing.Optional[torch.device] = None num_images_per_prompt: int = 1 prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None max_sequence_length: int = 512 lora_scale: typing.Optional[float] = None )
参数
- prompt (
str或List[str], 可选) — 待编码的提示词。 - prompt_2 (
str或List[str], 可选) — 要发送到tokenizer_2和text_encoder_2的提示词。如果未定义，所有文本编码器都将使用prompt。 - device — (
torch.device)：torch 设备。 - num_images_per_prompt (
int) — 每个提示词应生成的图像数量。 - prompt_embeds (
torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从prompt输入参数生成文本嵌入。 - pooled_prompt_embeds (
torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从prompt输入参数生成池化文本嵌入。 - clip_skip (
int, 可选) — 在计算提示嵌入时从 CLIP 跳过的层数。值为 1 表示将使用倒数第二层的输出计算提示嵌入。 - lora_scale (
float, 可选) — 应用于文本编码器所有 LoRA 层的 LoRA 比例（如果已加载 LoRA 层）。
FluxPipelineOutput
类 diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput
< 源文件 >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
Stable Diffusion 管道的输出类。