Diffusers documentation
Flux.1 的 ControlNet
Flux.1 的 ControlNet
FluxControlNetPipeline 是 Flux.1 的 ControlNet 实现。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 Adding Conditional Control to Text-to-Image Diffusion Models 中提出。
使用 ControlNet 模型，您可以提供一张额外的控制图像，以调节并控制 Stable Diffusion 的生成过程。例如，如果您提供一张深度图，ControlNet 模型将生成一张保留深度图中空间信息的图像。这是一种更灵活、更精确地控制图像生成过程的方式。
该论文的摘要如下：
我们提出了 ControlNet，一种用于为大型预训练文本到图像扩散模型添加空间条件控制的神经网络架构。ControlNet 锁定生产就绪的大型扩散模型，并复用其使用数十亿张图像预训练得到的深层且鲁棒的编码层作为强大的骨干网络，以学习多样化的条件控制。该神经架构通过“零卷积”（零初始化的卷积层）进行连接，这些层使参数从零开始逐步增长，并确保在微调过程中不会产生有害噪声。我们使用 Stable Diffusion 测试了多种条件控制，例如边缘、深度、分割、人体姿态等，支持使用单一或多个条件，以及有或无提示词的情况。我们展示了 ControlNet 的训练在小规模（<50k）和大规模（>1m）数据集上均具有鲁棒性。大量结果表明，ControlNet 有助于将图像扩散模型的应用扩展到更广泛的领域。
This controlnet code is implemented by The InstantX Team. You can find pre-trained checkpoints for Flux-ControlNet in the table below:
| ControlNet 类型 | 开发者 | 链接 |
|---|---|---|
| Canny | InstantX 团队 | 链接 |
| 深度 | InstantX 团队 | 链接 |
| Union | InstantX 团队 | 链接 |
XLabs ControlNets 也得到支持，由 XLabs 团队 贡献。
| ControlNet 类型 | 开发者 | 链接 |
|---|---|---|
| Canny | XLabs 团队 | 链接 |
| 深度 | XLabs 团队 | 链接 |
| HED | XLabs 团队 | 链接 |
请务必参阅 调度器指南，了解如何探索调度器速度与质量之间的权衡，并查看 跨流水线复用组件 部分，了解如何高效地将相同组件加载到多个流水线中。
FluxControlNetPipeline
class diffusers.FluxControlNetPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModeltokenizer: CLIPTokenizertext_encoder_2: T5EncoderModeltokenizer_2: T5Tokenizertransformer: FluxTransformer2DModelcontrolnet: diffusers.models.controlnets.controlnet_flux.FluxControlNetModel | list[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModelimage_encoder: CLIPVisionModelWithProjection = Nonefeature_extractor: CLIPImageProcessorPil = None )
参数
- transformer (FluxTransformer2DModel) — 用于对编码后的图像潜变量进行去噪的条件 Transformer (MMDiT) 架构。
- scheduler (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 类的 Tokenizer。
用于文本到图像生成的 Flux 流水线。
参考：https://blackforestlabs.ai/announcing-black-forest-labs/
__call__
< source >( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Nonenegative_prompt: str | list[str] = Nonenegative_prompt_2: str | list[str] | None = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0control_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_mode: int | list[int] | None = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0num_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: list[torch.Tensor] | None = Nonenegative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_ip_adapter_image_embeds: list[torch.Tensor] | None = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512 ) → ~pipelines.flux.FluxPipelineOutput or tuple
参数
- prompt (
str或list[str]，可选) — 用于引导图像生成的提示词或提示词列表。如果未定义，则必须改为传入prompt_embeds。 - prompt_2 (
str或list[str]，可选) — 要发送给tokenizer_2和text_encoder_2的提示词。如果未定义，将使用prompt。 - negative_prompt (
str或list[str]，可选) — 用于不引导图像生成的提示词。如果未定义，则必须传入negative_prompt_embeds。当不使用引导时会被忽略（即当true_cfg_scale不大于1时会被忽略）。 - negative_prompt_2 (
str或list[str]，可选) — 用于引导图像生成的负面提示词，将发送给tokenizer_2和text_encoder_2。如果未定义，则所有文本编码器都会使用negative_prompt。 - true_cfg_scale（
float，可选，默认值为 1.0）— 当true_cfg_scale> 1 且提供了negative_prompt时，将启用真正的无分类器引导（guidance scale）。 - 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]]): 用于为unet的生成过程提供引导的 ControlNet 输入条件。如果类型指定为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输入参数生成池化文本嵌入。 - negative_prompt_embeds (
torch.FloatTensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将根据negative_prompt输入参数生成。 - negative_pooled_prompt_embeds (
torch.FloatTensor，可选) — 预生成的负向池化文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，将从negative_prompt输入参数生成池化的 negative_prompt_embeds。 - ip_adapter_image — (
PipelineImageInput，可选)：用于配合 IP Adapter 使用的可选图像输入。 - 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 Adapter 使用的可选图像输入。 - 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
~pipelines.flux.FluxPipelineOutput（当 return_dict 为 True 时），否则为 tuple。返回元组时，第一个元素是包含生成图像的列表。
调用生成 pipeline 时调用的函数。
示例：
>>> 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
< source >( prompt: str | list[str]prompt_2: str | list[str] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonemax_sequence_length: int = 512lora_scale: float | None = 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输入参数生成池化文本嵌入。 - lora_scale (
float, 可选) — 如果加载了 LoRA 层，将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。
FluxPipelineOutput
class diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
Flux 图像生成流水线的输出类。