Hugging Face 的 LOGO

Diffusers 文档

带Flux.1的ControlNet

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

带Flux.1的ControlNet

LoRA

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 )

参数

用于文本到图像生成的 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] )

参数

  • images (List[PIL.Image.Image] 或 np.ndarray) — 去噪后的 PIL 图像列表，长度为 batch_size，或形状为 (batch_size, height, width, num_channels) 的 numpy 数组。PIL 图像或 numpy 数组表示扩散管道的去噪图像。

Stable Diffusion 管道的输出类。

< > 在 GitHub 上更新

←ControlNet ControlNet with Hunyuan-DiT→