Hugging Face 的 LOGO

Diffusers 文档

ControlNet 与 Stable Diffusion 3

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

ControlNet 与 Stable Diffusion 3

LoRA

StableDiffusion3ControlNetPipeline 是 ControlNet 在 Stable Diffusion 3 上的实现。

ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《为文本到图像扩散模型添加条件控制》 中提出。

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

论文摘要如下：

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

此 ControlNet 代码主要由 InstantX 团队实现。与图像修复相关的代码由 阿里巴巴妈妈创意团队开发。您可以在下表中找到 SD3-ControlNet 的预训练检查点

ControlNet 类型 开发者 链接
边缘检测 InstantX 团队 链接
深度 InstantX 团队 链接
姿态 InstantX 团队 链接
平铺 InstantX 团队 链接
图像修复 阿里巴巴妈妈创意团队 链接

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

StableDiffusion3ControlNetPipeline

类 diffusers.StableDiffusion3ControlNetPipeline

< >

( 转换器: SD3Transformer2DModel 调度器: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL 文本编码器: CLIPTextModelWithProjection 分词器: CLIPTokenizer 文本编码器_2: CLIPTextModelWithProjection 分词器_2: CLIPTokenizer 文本编码器_3: T5EncoderModel 分词器_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] 图像编码器: typing.Optional[transformers.models.siglip.modeling_siglip.SiglipVisionModel] = None 特征提取器: typing.Optional[transformers.models.siglip.image_processing_siglip.SiglipImageProcessor] = None )

参数

  • 转换器 (SD3Transformer2DModel) — 用于对编码图像潜变量进行去噪的条件转换器 (MMDiT) 架构。
  • 调度器 (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 变体。
  • 分词器 (CLIPTokenizer) — CLIPTokenizer 类的分词器。
  • tokenizer_2 (CLIPTokenizer) — 第二个 CLIPTokenizer 类的分词器。
  • tokenizer_3 (T5TokenizerFast) — T5Tokenizer 类的分词器。
  • controlnet (SD3ControlNetModel 或 List[SD3ControlNetModel] 或 SD3MultiControlNetModel) — 在去噪过程中为 unet 提供额外的条件。如果将多个 ControlNet 设置为列表，则每个 ControlNet 的输出将相加，以创建一个组合的额外条件。
  • 图像编码器 (SiglipVisionModel, 可选) — 用于 IP Adapter 的预训练视觉模型。
  • 特征提取器 (SiglipImageProcessor, 可选) — 用于 IP Adapter 的图像处理器。

__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 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 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[torch.Tensor] = 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 或 tuple

参数

  • 提示词 (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], — List[List[torch.Tensor]], List[List[np.ndarray]] or 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，则可以将其相应的比例设置为列表。
  • 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 输入参数生成。
  • pooled_prompt_embeds (torch.FloatTensor, 可选) — 预先生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，池化文本嵌入将从 prompt 输入参数生成。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预先生成的负池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，负池化提示嵌入将从 negative_prompt 输入参数生成。
  • ip_adapter_image (PipelineImageInput, 可选) — 用于 IP Adapters 的可选图像输入。
  • ip_adapter_image_embeds (torch.Tensor, 可选) — 为 IP-Adapter 预先生成的图像嵌入。应为形状 (batch_size, num_images, emb_dim) 的张量。如果 do_classifier_free_guidance 设置为 True，则应包含负图像嵌入。如果未提供，则根据 ip_adapter_image 输入参数计算嵌入。
  • 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

如果 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_image

< >

( 图像: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] 设备: device ) → torch.Tensor

参数

  • image (PipelineImageInput) — 要编码的输入图像。
  • device — (torch.device): Torch 设备。

返回

torch.Tensor

编码后的图像特征表示。

使用预训练的图像编码器将给定图像编码为特征表示。

encode_prompt

< >

( 提示: typing.Union[str, typing.List[str]] 提示_2: typing.Union[str, typing.List[str]] 提示_3: typing.Union[str, typing.List[str]] 设备: typing.Optional[torch.device] = None 每个提示的图像数量: int = 1 do_classifier_free_guidance: bool = True 负提示: typing.Union[str, typing.List[str], NoneType] = None 负提示_2: typing.Union[str, typing.List[str], NoneType] = None 负提示_3: typing.Union[str, typing.List[str], NoneType] = None 提示嵌入: typing.Optional[torch.FloatTensor] = None 负提示嵌入: typing.Optional[torch.FloatTensor] = None 池化提示嵌入: typing.Optional[torch.FloatTensor] = None 负池化提示嵌入: typing.Optional[torch.FloatTensor] = None clip_skip: typing.Optional[int] = None 最大序列长度: 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_3 (str 或 List[str], 可选) — 发送到 tokenizer_3 和 text_encoder_3 的不用于指导图像生成的提示。如果未定义，则在所有文本编码器中都使用 negative_prompt。
  • prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，负提示嵌入将从 negative_prompt 输入参数生成。
  • pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，池化文本嵌入将从 prompt 输入参数生成。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，负池化提示嵌入将从 negative_prompt 输入参数生成。
  • clip_skip (int, 可选) — 在计算提示嵌入时，从 CLIP 跳过的层数。值为 1 表示使用倒数第二层的输出计算提示嵌入。
  • lora_scale (float, 可选) — 将应用于文本编码器所有 LoRA 层的 LoRA 比例（如果加载了 LoRA 层）。

prepare_ip_adapter_image_embeds

< >

( 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[torch.Tensor] = None 设备: typing.Optional[torch.device] = None 每个提示的图像数量: int = 1 do_classifier_free_guidance: bool = True )

参数

  • ip_adapter_image (PipelineImageInput, 可选) — 用于从 IP-Adapter 中提取特征的输入图像。
  • ip_adapter_image_embeds (torch.Tensor, 可选) — 预计算的图像嵌入。
  • device — (torch.device, 可选): Torch 设备。
  • num_images_per_prompt (int, 默认为 1) — 每个提示应生成的图像数量。
  • do_classifier_free_guidance (bool, 默认为 True) — 是否使用分类器自由指导。

准备图像嵌入以供 IP-Adapter 使用。

必须传递 ip_adapter_image 或 ip_adapter_image_embeds。

StableDiffusion3ControlNetInpaintingPipeline

class diffusers.StableDiffusion3ControlNetInpaintingPipeline

< >

( 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] image_encoder: SiglipModel = None feature_extractor: typing.Optional[transformers.models.siglip.image_processing_siglip.SiglipImageProcessor] = None )

参数

  • 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) — 在去噪过程中为 `transformer` 提供额外的条件。如果将多个 ControlNet 设置为列表，则每个 ControlNet 的输出将被相加，以创建一个组合的额外条件。
  • image_encoder (PreTrainedModel, 可选) — 用于 IP Adapter 的预训练视觉模型。
  • feature_extractor (BaseImageProcessor, 可选) — 用于 IP Adapter 的图像处理器。

__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 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[torch.Tensor] = 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 或 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，与支持 `sigmas` 参数的调度器结合使用（在它们的 `set_timesteps` 方法中）。如果未定义，则在传入 `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]) — 要进行修复的图像（需要使用 `control_mask` 遮罩的部分将根据 `prompt` 重新绘制）。对于 numpy 数组和 pytorch 张量，预期值范围在 `[0, 1]` 之间。如果是张量或张量列表，预期形状应为 `(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]) — 图像、numpy 数组或张量，表示用于遮罩 `image` 的图像批次。遮罩中的白色像素将被重新绘制，而黑色像素将被保留。如果 `mask_image` 是 PIL 图像，它在使用前将转换为单通道（亮度）。如果它是 numpy 数组或 pytorch 张量，它应该包含一个颜色通道（L）而不是 3，因此 pytorch 张量的预期形状为 `(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` 进行采样生成潜变量张量。
  • prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，文本嵌入将从 `prompt` 输入参数生成。
  • negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，`negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。
  • pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，池化文本嵌入将从 `prompt` 输入参数生成。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负池化文本嵌入。可用于轻松调整文本输入，例如提示词权重。如果未提供，池化负 `negative_prompt_embeds` 将从 `negative_prompt` 输入参数生成。
  • ip_adapter_image (PipelineImageInput, 可选) — 与 IP Adapters 配合使用的可选图像输入。
  • ip_adapter_image_embeds (torch.Tensor, 可选) — 预生成的 IP-Adapter 图像嵌入。应为形状 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`，则应包含负图像嵌入。如果未提供，嵌入将从 `ip_adapter_image` 输入参数计算。
  • 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

如果 return_dict 为 True，则返回 ~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_image

< >

( 图像: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] 设备: device ) → torch.Tensor

参数

  • image (PipelineImageInput) — 要编码的输入图像。
  • device — (torch.device): Torch 设备。

返回

torch.Tensor

编码后的图像特征表示。

使用预训练的图像编码器将给定图像编码为特征表示。

encode_prompt

< >

( 提示: typing.Union[str, typing.List[str]] 提示_2: typing.Union[str, typing.List[str]] 提示_3: typing.Union[str, typing.List[str]] 设备: typing.Optional[torch.device] = None 每个提示的图像数量: int = 1 do_classifier_free_guidance: bool = True 负提示: typing.Union[str, typing.List[str], NoneType] = None 负提示_2: typing.Union[str, typing.List[str], NoneType] = None 负提示_3: typing.Union[str, typing.List[str], NoneType] = None 提示嵌入: typing.Optional[torch.FloatTensor] = None 负提示嵌入: typing.Optional[torch.FloatTensor] = None 池化提示嵌入: typing.Optional[torch.FloatTensor] = None 负池化提示嵌入: typing.Optional[torch.FloatTensor] = None clip_skip: typing.Optional[int] = None 最大序列长度: 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_3 (str 或 List[str], 可选) — 要发送到 tokenizer_3 和 text_encoder_3 的不用于引导图像生成的提示词。如果未定义，则在所有文本编码器中使用 negative_prompt。
  • prompt_embeds (torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示词权重。如果未提供，则将从 prompt 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如 提示词权重。如果未提供，则将从 negative_prompt 输入参数生成负向提示词嵌入。
  • pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如 提示词权重。如果未提供，则将从 prompt 输入参数生成池化文本嵌入。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负向池化文本嵌入。可用于轻松调整文本输入，例如 提示词权重。如果未提供，则将从 negative_prompt 输入参数生成池化负向提示词嵌入。
  • clip_skip (int, 可选) — 计算提示词嵌入时要跳过的 CLIP 层数。值为 1 表示将使用倒数第二层的输出计算提示词嵌入。
  • lora_scale (float, 可选) — 将应用于文本编码器所有 LoRA 层的 LoRA 缩放因子（如果 LoRA 层已加载）。

prepare_ip_adapter_image_embeds

< >

( 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[torch.Tensor] = None 设备: typing.Optional[torch.device] = None 每个提示的图像数量: int = 1 do_classifier_free_guidance: bool = True )

参数

  • ip_adapter_image (PipelineImageInput, 可选) — 用于 IP-Adapter 提取特征的输入图像。
  • ip_adapter_image_embeds (torch.Tensor, 可选) — 预计算的图像嵌入。
  • device — (torch.device, 可选): Torch 设备。
  • num_images_per_prompt (int, 默认为 1) — 每个提示词应生成的图像数量。
  • do_classifier_free_guidance (bool, 默认为 True) — 是否使用分类器自由引导。

准备图像嵌入以供 IP-Adapter 使用。

必须传递 ip_adapter_image 或 ip_adapter_image_embeds。

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) — 经过去噪的 PIL 图像列表，长度为 batch_size，或形状为 (batch_size, height, width, num_channels) 的 numpy 数组。PIL 图像或 numpy 数组表示扩散管道的去噪图像。

Stable Diffusion 管道的输出类。

< > 在 GitHub 上更新

←ControlNet with Hunyuan-DiT ControlNet with Stable Diffusion XL→
© . This site is unofficial and not affiliated with Hugging Face, Inc.