Diffusers 文档

ControlNet 与 Stable Diffusion 3

Diffusers

加入 Hugging Face 社区

并获得增强的文档体验

协作处理模型、数据集和 Spaces

通过加速推理获得更快的示例

切换文档主题

开始使用

ControlNet 与 Stable Diffusion 3

StableDiffusion3ControlNetPipeline 是 ControlNet 为 Stable Diffusion 3 的实现。

ControlNet 在 Adding Conditional Control to Text-to-Image Diffusion Models (作者：Lvmin Zhang, Anyi Rao 和 Maneesh Agrawala) 中被介绍。

通过 ControlNet 模型，您可以提供额外的控制图像来调节和控制 Stable Diffusion 的生成。例如，如果您提供深度图，ControlNet 模型将生成一张保留深度图空间信息的图像。这是一种更灵活和准确的方式来控制图像生成过程。

以下是论文的摘要

我们提出了 ControlNet，一种神经网络架构，用于向大型预训练文本到图像扩散模型添加空间条件控制。ControlNet 锁定已投入生产的大型扩散模型，并重用其使用数十亿图像进行预训练的深度和鲁棒的编码层，作为学习各种条件控制的强大骨干。该神经网络架构与“零卷积”（零初始化的卷积层）相连，这些卷积层逐渐从零开始增长参数，并确保没有有害噪声会影响微调。我们测试了各种条件控制，例如，边缘、深度、分割、人体姿势等，与 Stable Diffusion 一起使用，使用单个或多个条件，有或没有提示。我们表明，ControlNet 的训练对于小型（<50k）和大型（>1m）数据集都是稳健的。广泛的结果表明，ControlNet 可以促进更广泛的应用来控制图像扩散模型。

此 controlnet 代码主要由 The InstantX Team 实现。与图像修复相关的代码由 The Alimama Creative Team 开发。您可以在下表中找到 SD3-ControlNet 的预训练检查点

ControlNet 类型	开发者	链接
Canny	The InstantX Team	链接
深度	The InstantX Team	链接
姿势	The InstantX Team	链接
Tile	The InstantX Team	链接
图像修复	The AlimamaCreative Team	链接

请务必查看 Schedulers 指南，了解如何探索调度器速度和质量之间的权衡，并查看在 pipelines 之间重用组件部分，了解如何有效地将相同的组件加载到多个 pipelines 中。

StableDiffusion3ControlNetPipeline

class diffusers.StableDiffusion3ControlNetPipeline

< source >

( transformer: SD3Transformer2DModel scheduler: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL text_encoder: CLIPTextModelWithProjection tokenizer: CLIPTokenizer text_encoder_2: CLIPTextModelWithProjection tokenizer_2: CLIPTokenizer text_encoder_3: T5EncoderModel tokenizer_3: T5TokenizerFast controlnet: typing.Union[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel, typing.List[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModel] )

参数

transformer (SD3Transformer2DModel) — 用于去噪编码图像 latents 的条件 Transformer (MMDiT) 架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 与 transformer 结合使用的调度器，用于去噪编码图像 latents。
vae (AutoencoderKL) — 变分自编码器 (VAE) 模型，用于将图像编码和解码为 latent 表示形式。
text_encoder (`CLIPTextModelWithProjection`) — CLIP，特别是 clip-vit-large-patch14 变体，带有一个额外的投影层，该投影层使用 `hidden_size` 作为其维度的对角矩阵进行初始化。
text_encoder_2 (`CLIPTextModelWithProjection`) — CLIP，特别是 laion/CLIP-ViT-bigG-14-laion2B-39B-b160k 变体。
text_encoder_3 (`T5EncoderModel`) — 冻结的文本编码器。 Stable Diffusion 3 使用 T5，特别是 t5-v1_1-xxl 变体。
tokenizer (`CLIPTokenizer`) — `CLIPTokenizer` 类的分词器。
tokenizer_2 (`CLIPTokenizer`) — `CLIPTokenizer` 类的第二个分词器。
tokenizer_3 (`T5TokenizerFast`) — `T5Tokenizer` 类的分词器。
controlnet (SD3ControlNetModel 或 `List[SD3ControlNetModel]` 或 `SD3MultiControlNetModel`) — 在去噪过程中为 `unet` 提供额外的条件控制。如果您将多个 ControlNet 设置为列表，则每个 ControlNet 的输出将加在一起以创建一个组合的额外条件控制。

call

< source >

( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None prompt_3: typing.Union[str, typing.List[str], NoneType] = None 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 controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_3: typing.Union[str, typing.List[str], NoneType] = None 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 negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_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 clip_skip: typing.Optional[int] = 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 = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

参数

prompt (`str` 或 `List[str]`, *可选*) — 引导图像生成的 prompt 或 prompts。如果未定义，则必须改为传递 `prompt_embeds`。
prompt_2 (`str` 或 `List[str]`, *可选*) — 要发送到 `tokenizer_2` 和 `text_encoder_2` 的 prompt 或 prompts。如果未定义，则将使用 `prompt` 代替。
prompt_3 (`str` 或 `List[str]`, *可选*) — 要发送到 `tokenizer_3` 和 `text_encoder_3` 的 prompt 或 prompts。如果未定义，则将使用 `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`, *可选*, 默认为 5.0) — [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598) 中定义的 guidance scale。 `guidance_scale` 定义为 [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf) 公式 2 中的 `w`。通过设置 `guidance_scale > 1` 启用 guidance scale。较高的 guidance scale 鼓励生成与文本 `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]] or List[List[PIL.Image.Image]]): 提供给 unet 以引导生成的 ControlNet 输入条件。如果类型指定为 torch.Tensor，则会按原样传递给 ControlNet。 PIL.Image.Image 也可以作为图像接受。输出图像的尺寸默认为 image 的尺寸。如果传递了 height 和/或 width，则会相应地调整 image 的大小。如果在 init 中指定了多个 ControlNet，则必须将图像作为列表传递，以便列表的每个元素都可以正确地批量处理，以输入到单个 ControlNet。
controlnet_conditioning_scale (float 或 List[float], 可选, 默认为 1.0) — ControlNet 的输出在添加到原始 unet 中的残差之前，会乘以 controlnet_conditioning_scale。如果在 init 中指定了多个 ControlNet，则可以将相应的比例设置为列表。
controlnet_pooled_projections (形状为 (batch_size, projection_dim) 的 torch.FloatTensor) — 从 controlnet 输入条件的嵌入中投影出的嵌入。
negative_prompt (str 或 List[str], 可选) — 不用于引导图像生成的提示或提示列表。如果未定义，则必须传递 negative_prompt_embeds 代替。当不使用引导时会被忽略（即，如果 guidance_scale 小于 1 则忽略）。
negative_prompt_2 (str 或 List[str], 可选) — 不用于引导图像生成的提示或提示列表，将发送到 tokenizer_2 和 text_encoder_2。如果未定义，则使用 negative_prompt 代替
negative_prompt_3 (str 或 List[str], 可选) — 不用于引导图像生成的提示或提示列表，将发送到 tokenizer_3 和 text_encoder_3。如果未定义，则使用 negative_prompt 代替
num_images_per_prompt (int, 可选, 默认为 1) — 每个提示要生成的图像数量。
generator (torch.Generator 或 List[torch.Generator], 可选) — 用于使生成具有确定性的一个或一组 torch 生成器。
latents (torch.FloatTensor, 可选) — 预生成的噪声潜变量，从高斯分布中采样，用作图像生成的输入。可用于使用不同的提示调整相同的生成结果。如果未提供，则将使用提供的随机 generator 采样生成潜变量张量。
prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负面文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 negative_prompt 输入参数生成 negative_prompt_embeds。
pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成池化文本嵌入。
negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负面池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 negative_prompt 输入参数生成 pooled negative_prompt_embeds。
output_type (str, 可选, 默认为 "pil") — 生成图像的输出格式。在 PIL: PIL.Image.Image 或 np.array 之间选择。
return_dict (bool, 可选, 默认为 True) — 是否返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 而不是普通元组。
joint_attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，则会作为 self.processor 下定义的 AttentionProcessor 传递到 diffusers.models.attention_processor。
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 默认为 256) — 与 prompt 一起使用的最大序列长度。

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput，否则返回 tuple。当返回元组时，第一个元素是包含生成图像的列表。

调用管道进行生成时调用的函数。

示例

>>> import torch
>>> from diffusers import StableDiffusion3ControlNetPipeline
>>> from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
>>> from diffusers.utils import load_image

>>> controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny", torch_dtype=torch.float16)

>>> pipe = StableDiffusion3ControlNetPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> control_image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png"
... )
>>> prompt = "A bird in space"
>>> image = pipe(
...     prompt, control_image=control_image, height=1024, width=768, controlnet_conditioning_scale=0.7
... ).images[0]
>>> image.save("sd3.png")

encode_prompt

< source >

( prompt: typing.Union[str, typing.List[str]] prompt_2: typing.Union[str, typing.List[str]] prompt_3: typing.Union[str, typing.List[str]] device: typing.Optional[torch.device] = None num_images_per_prompt: int = 1 do_classifier_free_guidance: bool = True negative_prompt: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_3: typing.Union[str, typing.List[str], NoneType] = None prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None clip_skip: typing.Optional[int] = None max_sequence_length: int = 256 lora_scale: typing.Optional[float] = None )

参数

prompt (str 或 List[str], 可选) — 要编码的提示
prompt_2 (str 或 List[str], 可选) — 要发送到 tokenizer_2 和 text_encoder_2 的提示或提示列表。如果未定义，则在所有文本编码器中使用 prompt
prompt_3 (str 或 List[str], 可选) — 要发送到 tokenizer_3 和 text_encoder_3 的提示或提示列表。如果未定义，则在所有文本编码器中使用 prompt
device — (torch.device): torch 设备
num_images_per_prompt (int) — 每个提示应生成的图像数量
do_classifier_free_guidance (bool) — 是否使用无分类器引导
negative_prompt (str 或 List[str], 可选) — 不用于引导图像生成的提示。如果未定义，则必须传递 negative_prompt_embeds。当不使用引导时忽略（即，如果 guidance_scale 小于 1 则忽略）。
negative_prompt_2 (str 或 List[str], 可选) — 不用于引导图像生成的提示，将发送到 tokenizer_2 和 text_encoder_2。如果未定义，则在所有文本编码器中使用 negative_prompt。
negative_prompt_2 (str 或 List[str], 可选) — 不用于引导图像生成的提示，将发送到 tokenizer_3 和 text_encoder_3。如果未定义，则在两个文本编码器中使用 negative_prompt
prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 negative_prompt 输入参数生成 negative_prompt_embeds。
pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成池化文本嵌入。
negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 negative_prompt 输入参数生成池化 negative_prompt_embeds。
clip_skip (int, 可选) — 在计算提示嵌入时，从 CLIP 跳过的层数。值为 1 表示将使用倒数第二层的输出计算提示嵌入。
lora_scale (float, 可选) — 如果加载了 LoRA 层，则将应用于文本编码器的所有 LoRA 层的 lora 缩放比例。

StableDiffusion3ControlNetInpaintingPipeline

class diffusers.pipelines.StableDiffusion3ControlNetInpaintingPipeline

< 源代码 >

参数

transformer (SD3Transformer2DModel) — 条件 Transformer (MMDiT) 架构，用于对编码的图像潜在空间进行去噪。
scheduler (FlowMatchEulerDiscreteScheduler) — 调度器，与 transformer 结合使用，以对编码的图像潜在空间进行去噪。
vae (AutoencoderKL) — 变分自动编码器 (VAE) 模型，用于将图像编码和解码为潜在表示。
text_encoder (CLIPTextModelWithProjection) — CLIP, 特别是 clip-vit-large-patch14 变体，带有一个额外的投影层，该投影层使用以 hidden_size 为维度的对角矩阵初始化。
text_encoder_2 (CLIPTextModelWithProjection) — CLIP, 特别是 laion/CLIP-ViT-bigG-14-laion2B-39B-b160k 变体。
text_encoder_3 (T5EncoderModel) — 冻结的文本编码器。 Stable Diffusion 3 使用 T5，特别是 t5-v1_1-xxl 变体。
tokenizer (CLIPTokenizer) — CLIPTokenizer 类的分词器。
tokenizer_2 (CLIPTokenizer) — CLIPTokenizer 类的第二个分词器。
tokenizer_3 (T5TokenizerFast) — T5Tokenizer 类的分词器。
controlnet (SD3ControlNetModel 或 List[SD3ControlNetModel] 或 SD3MultiControlNetModel) — 在去噪过程中为 unet 提供额外的条件控制。如果将多个 ControlNet 设置为列表，则每个 ControlNet 的输出将加在一起，以创建一个组合的额外条件控制。

call

< 源代码 >

( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None prompt_3: typing.Union[str, typing.List[str], NoneType] = None 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_mask: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_3: typing.Union[str, typing.List[str], NoneType] = None 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 negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_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 clip_skip: typing.Optional[int] = 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 = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

参数

prompt (str 或 List[str], 可选) — 用于引导图像生成的提示语或提示语列表。如果未定义，则必须传入 prompt_embeds。
prompt_2 (str 或 List[str], 可选) — 将发送到 tokenizer_2 和 text_encoder_2 的提示语或提示语列表。如果未定义，则将使用 prompt。
prompt_3 (str 或 List[str], 可选) — 将发送到 tokenizer_3 和 text_encoder_3 的提示语或提示语列表。如果未定义，则将使用 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, 可选, 默认为 5.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]) — Image，numpy 数组或 tensor，表示要进行图像修复的图像批次（图像的哪些部分要用 control_mask 遮罩，并根据 prompt 重新绘制）。对于 numpy 数组和 pytorch tensor，预期值范围在 [0, 1] 之间。如果是 tensor 或 tensor 列表，则预期形状应为 (B, C, H, W)。如果是 numpy 数组或数组列表，则预期形状应为 (B, H, W, C) 或 (H, W, C)。
control_mask (torch.Tensor, PIL.Image.Image, np.ndarray, List[torch.Tensor], List[PIL.Image.Image], List[np.ndarray]) — Image，numpy 数组或 tensor，表示要遮罩 image 的图像批次。蒙版中的白色像素将被重新绘制，而黑色像素将被保留。如果 mask_image 是 PIL 图像，则在使用前将其转换为单通道（亮度）。如果它是 numpy 数组或 pytorch tensor，则它应包含一个颜色通道 (L) 而不是 3 个，因此 pytorch tensor 的预期形状为 (B, 1, H, W)。而对于 numpy 数组，预期形状为 (B, H, W, 1), (B, H, W), (H, W, 1), 或 (H, W)。
controlnet_conditioning_scale (float 或 List[float], 可选, 默认为 1.0) — ControlNet 的输出在添加到原始 unet 中的残差之前，会乘以 controlnet_conditioning_scale。如果在 init 中指定了多个 ControlNet，则可以将相应的比例设置为列表。
controlnet_pooled_projections (形状为 (batch_size, projection_dim) 的 torch.FloatTensor) — 从 controlnet 输入条件的嵌入投影而来的嵌入。
negative_prompt (str 或 List[str], 可选) — 不用于引导图像生成的提示语或提示语列表。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时忽略（即，如果 guidance_scale 小于 1 则忽略）。
negative_prompt_2 (str 或 List[str], 可选) — 不用于引导图像生成的提示语或提示语列表，将发送到 tokenizer_2 和 text_encoder_2。如果未定义，则使用 negative_prompt。
negative_prompt_3 (str 或 List[str], 可选) — 不用于引导图像生成的提示语或提示语列表，将发送到 tokenizer_3 和 text_encoder_3。如果未定义，则使用 negative_prompt。
num_images_per_prompt (int, 可选, 默认为 1) — 每个提示语要生成的图像数量。
generator (torch.Generator 或 List[torch.Generator], 可选) — 一个或多个 torch 生成器，用于使生成结果确定。
latents (torch.FloatTensor, 可选) — 预生成的噪声潜变量，从高斯分布中采样，用作图像生成的输入。可用于通过不同的提示语调整相同的生成结果。如果未提供，则将通过使用提供的随机 generator 进行采样来生成潜变量 tensor。
prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示语权重。如果未提供，则将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负面文本嵌入。可用于轻松调整文本输入，例如提示语权重。如果未提供，则将从 negative_prompt 输入参数生成 negative_prompt_embeds。
pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示语权重。如果未提供，则将从 prompt 输入参数生成池化文本嵌入。
negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负面池化文本嵌入。可用于轻松调整文本输入，例如提示语权重。如果未提供，则将从 negative_prompt 输入参数生成 pooled negative_prompt_embeds。
output_type (str, 可选, 默认为 "pil") — 生成图像的输出格式。从 PIL: PIL.Image.Image 或 np.array 中选择。
return_dict (bool, 可选, 默认为 True) — 是否返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 而不是普通元组。
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 默认为 256) — 与 prompt 一起使用的最大序列长度。

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 或 tuple

调用管道进行生成时调用的函数。

示例

>>> import torch
>>> from diffusers.utils import load_image, check_min_version
>>> from diffusers.pipelines import StableDiffusion3ControlNetInpaintingPipeline
>>> from diffusers.models.controlnet_sd3 import SD3ControlNetModel

>>> controlnet = SD3ControlNetModel.from_pretrained(
...     "alimama-creative/SD3-Controlnet-Inpainting", use_safetensors=True, extra_conditioning_channels=1
... )
>>> pipe = StableDiffusion3ControlNetInpaintingPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers",
...     controlnet=controlnet,
...     torch_dtype=torch.float16,
... )
>>> pipe.text_encoder.to(torch.float16)
>>> pipe.controlnet.to(torch.float16)
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog.png"
... )
>>> mask = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog_mask.png"
... )
>>> width = 1024
>>> height = 1024
>>> prompt = "A cat is sitting next to a puppy."
>>> generator = torch.Generator(device="cuda").manual_seed(24)
>>> res_image = pipe(
...     negative_prompt="deformed, distorted, disfigured, poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, mutated hands and fingers, disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation, NSFW",
...     prompt=prompt,
...     height=height,
...     width=width,
...     control_image=image,
...     control_mask=mask,
...     num_inference_steps=28,
...     generator=generator,
...     controlnet_conditioning_scale=0.95,
...     guidance_scale=7,
... ).images[0]
>>> res_image.save(f"sd3.png")

encode_prompt

< 源代码 >

参数

prompt (str 或 List[str], 可选) — 要编码的 prompt
prompt_2 (str 或 List[str], 可选) — 要发送到 tokenizer_2 和 text_encoder_2 的 prompt 或 prompts。如果未定义，则 prompt 用于所有文本编码器
prompt_3 (str 或 List[str], 可选) — 要发送到 tokenizer_3 和 text_encoder_3 的 prompt 或 prompts。如果未定义，则 prompt 用于所有文本编码器
device — (torch.device): torch 设备
num_images_per_prompt (int) — 每个 prompt 应生成的图像数量
do_classifier_free_guidance (bool) — 是否使用无分类器 guidance
negative_prompt (str 或 List[str], 可选) — 不引导图像生成的 prompt 或 prompts。如果未定义，则必须传递 negative_prompt_embeds 代替。当不使用 guidance 时忽略（即，如果 guidance_scale 小于 1 则忽略）。
negative_prompt_2 (str 或 List[str], 可选) — 不引导图像生成的 prompt 或 prompts，将发送到 tokenizer_2 和 text_encoder_2。如果未定义，则 negative_prompt 用于所有文本编码器。
negative_prompt_2 (str 或 List[str], 可选) — 不引导图像生成的 prompt 或 prompts，将发送到 tokenizer_3 和 text_encoder_3。如果未定义，则 negative_prompt 用于两个文本编码器
prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，则将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，则将从 negative_prompt 输入参数生成 negative_prompt_embeds。
pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，则将从 prompt 输入参数生成池化文本嵌入。
negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负池化文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，则将从 negative_prompt 输入参数生成池化 negative_prompt_embeds。
clip_skip (int, 可选) — 从 CLIP 跳过的层数，用于计算 prompt 嵌入。值 1 表示预最终层的输出将用于计算 prompt 嵌入。
lora_scale (float, 可选) — 如果加载了 LoRA 层，则将应用于文本编码器的所有 LoRA 层的 lora 比例。

StableDiffusion3PipelineOutput

class diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

< 源代码 >

( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )

参数

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

Stable Diffusion 管道的输出类。

< > 在 GitHub 上更新

←带有 Hunyuan-DiT 的 ControlNet 带有 Stable Diffusion XL 的 ControlNet→

Diffusers

ControlNet 与 Stable Diffusion 3

StableDiffusion3ControlNetPipeline

class diffusers.StableDiffusion3ControlNetPipeline

__call__

encode_prompt

StableDiffusion3ControlNetInpaintingPipeline

class diffusers.pipelines.StableDiffusion3ControlNetInpaintingPipeline

__call__

encode_prompt

StableDiffusion3PipelineOutput

class diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

call

call