Diffusers 文档

Stable Diffusion 3

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

Stable Diffusion 3

LoRA MPS

Stable Diffusion 3 (SD3) 在 Patrick Esser, Sumith Kulal, Andreas Blattmann, Rahim Entezari, Jonas Muller, Harry Saini, Yam Levi, Dominik Lorenz, Axel Sauer, Frederic Boesel, Dustin Podell, Tim Dockhorn, Zion English, Kyle Lacey, Alex Goodwin, Yannik Marek, 和 Robin Rombach 的论文 《通过扩展整流流 Transformer 实现高分辨率图像合成》(Scaling Rectified Flow Transformers for High-Resolution Image Synthesis)中被提出。

论文摘要如下:

扩散模型通过反转数据朝向噪声的前向路径,从噪声中创建数据,并已成为一种强大的生成建模技术,适用于图像和视频等高维感知数据。整流流是一种新近的生成模型公式,它将数据和噪声以直线连接。尽管其理论性质更优且概念简单,但尚未被确立为标准实践。在这项工作中,我们改进了现有的用于训练整流流模型的噪声采样技术,使其偏向于与感知相关的尺度。通过大规模研究,我们证明了该方法在高分辨率文本到图像合成方面,相较于已有的扩散公式表现更优。此外,我们提出了一种新颖的基于 Transformer 的文本到图像生成架构,该架构为两种模态使用独立的权重,并允许图像和文本 token 之间进行双向信息流,从而改善了文本理解、排版和人类偏好评分。我们证明,该架构遵循可预测的扩展趋势,并且较低的验证损失与通过各种指标和人类评估测量的文本到图像合成效果的提升相关。

使用示例

由于该模型是受限访问的,在使用 diffusers 之前,您首先需要访问 Stable Diffusion 3 Medium Hugging Face 页面,填写表格并接受使用条款。一旦获得授权,您需要登录,以便您的系统知道您已接受条款。

使用以下命令登录

huggingface-cli login

SD3 pipeline 使用三个文本编码器来生成图像。为了在大多数消费级硬件上运行,必须进行模型卸载。请使用 torch.float16 数据类型以节省更多内存。

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", torch_dtype=torch.float16)
pipe.to("cuda")

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world.png")

注意: Stable Diffusion 3.5 也可以使用 SD3 pipeline 运行,并且所有提到的优化和技术也同样适用。SD3 系列总共有三个官方模型

使用 IP-Adapters 进行图像提示

IP-Adapter 允许您除了文本提示外,还可以用图像来提示 SD3。当您有参考图像并且要描述难以用文本表达的复杂概念时,这尤其有用。要加载和使用 IP-Adapter,您需要

  • image_encoder:用于获取图像特征的预训练视觉模型,通常是 CLIP 图像编码器。
  • feature_extractor:为所选的 image_encoder 准备输入图像的图像处理器。
  • ip_adapter_id:包含图像交叉注意力层和图像投影参数的检查点。

IP-Adapters 是为特定模型架构训练的,因此它们也适用于基础模型的微调变体。您可以使用 ~SD3IPAdapterMixin.set_ip_adapter_scale 函数来调整输出与图像提示的对齐强度。值越高,模型越紧密地遵循图像提示。默认值 0.5 通常是一个很好的平衡,确保模型同等考虑文本和图像提示。

import torch
from PIL import Image

from diffusers import StableDiffusion3Pipeline
from transformers import SiglipVisionModel, SiglipImageProcessor

image_encoder_id = "google/siglip-so400m-patch14-384"
ip_adapter_id = "InstantX/SD3.5-Large-IP-Adapter"

feature_extractor = SiglipImageProcessor.from_pretrained(
    image_encoder_id,
    torch_dtype=torch.float16
)
image_encoder = SiglipVisionModel.from_pretrained(
    image_encoder_id,
    torch_dtype=torch.float16
).to( "cuda")

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    torch_dtype=torch.float16,
    feature_extractor=feature_extractor,
    image_encoder=image_encoder,
).to("cuda")

pipe.load_ip_adapter(ip_adapter_id)
pipe.set_ip_adapter_scale(0.6)

ref_img = Image.open("image.jpg").convert('RGB')

image = pipe(
    width=1024,
    height=1024,
    prompt="a cat",
    negative_prompt="lowres, low quality, worst quality",
    num_inference_steps=24,
    guidance_scale=5.0,
    ip_adapter_image=ref_img
).images[0]

image.save("result.jpg")
使用提示词“a cat”的 IP-Adapter 示例

查看 IP-Adapter 了解更多关于 IP-Adapters 工作原理的信息。

SD3 内存优化

SD3 使用三个文本编码器,其中一个是巨大的 T5-XXL 模型。这使得在显存小于 24GB 的 GPU 上运行该模型变得具有挑战性,即使使用 fp16 精度也是如此。以下部分概述了 Diffusers 中的一些内存优化方法,使在低资源硬件上运行 SD3 更加容易。

通过模型卸载运行推理

Diffusers 中最基本的内存优化方法允许您在推理过程中将模型的组件卸载到 CPU 以节省内存,同时推理延迟会略有增加。模型卸载只会在需要执行时将模型组件移动到 GPU,而将其余组件保留在 CPU 上。

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", torch_dtype=torch.float16)
pipe.enable_model_cpu_offload()

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world.png")

在推理期间移除 T5 文本编码器

在推理期间移除占用大量内存的 4.7B 参数 T5-XXL 文本编码器,可以显著减少 SD3 的内存需求,而性能仅有轻微下降。

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers",
    text_encoder_3=None,
    tokenizer_3=None,
    torch_dtype=torch.float16
)
pipe.to("cuda")

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world-no-T5.png")

使用 T5 文本编码器的量化版本

我们可以利用 bitsandbytes 库来加载并将 T5-XXL 文本编码器量化到 8 位精度。这允许您继续使用所有三个文本编码器,而性能仅受轻微影响。

首先安装 bitsandbytes 库。

pip install bitsandbytes

然后使用 BitsAndBytesConfig 加载 T5-XXL 模型。

import torch
from diffusers import StableDiffusion3Pipeline
from transformers import T5EncoderModel, BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(load_in_8bit=True)

model_id = "stabilityai/stable-diffusion-3-medium-diffusers"
text_encoder = T5EncoderModel.from_pretrained(
    model_id,
    subfolder="text_encoder_3",
    quantization_config=quantization_config,
)
pipe = StableDiffusion3Pipeline.from_pretrained(
    model_id,
    text_encoder_3=text_encoder,
    device_map="balanced",
    torch_dtype=torch.float16
)

image = pipe(
    prompt="a photo of a cat holding a sign that says hello world",
    negative_prompt="",
    num_inference_steps=28,
    height=1024,
    width=1024,
    guidance_scale=7.0,
).images[0]

image.save("sd3_hello_world-8bit-T5.png")

您可以在这里找到端到端的脚本。

SD3 性能优化

使用 Torch Compile 加速推理

在 SD3 pipeline 中使用编译后的组件可以将推理速度提高多达 4 倍。以下代码片段演示了如何编译 SD3 pipeline 的 Transformer 和 VAE 组件。

import torch
from diffusers import StableDiffusion3Pipeline

torch.set_float32_matmul_precision("high")

torch._inductor.config.conv_1x1_as_mm = True
torch._inductor.config.coordinate_descent_tuning = True
torch._inductor.config.epilogue_fusion = False
torch._inductor.config.coordinate_descent_check_all_directions = True

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers",
    torch_dtype=torch.float16
).to("cuda")
pipe.set_progress_bar_config(disable=True)

pipe.transformer.to(memory_format=torch.channels_last)
pipe.vae.to(memory_format=torch.channels_last)

pipe.transformer = torch.compile(pipe.transformer, mode="max-autotune", fullgraph=True)
pipe.vae.decode = torch.compile(pipe.vae.decode, mode="max-autotune", fullgraph=True)

# Warm Up
prompt = "a photo of a cat holding a sign that says hello world"
for _ in range(3):
    _ = pipe(prompt=prompt, generator=torch.manual_seed(1))

# Run Inference
image = pipe(prompt=prompt, generator=torch.manual_seed(1)).images[0]
image.save("sd3_hello_world.png")

查看完整脚本这里

量化

量化有助于通过以较低精度数据类型存储模型权重来减少大型模型的内存需求。但是,量化对视频质量的影响可能因视频模型而异。

请参考量化概述以了解更多关于支持的量化后端以及如何选择适合您用例的量化后端。下面的示例演示了如何使用 bitsandbytes 加载一个量化后的 StableDiffusion3Pipeline 进行推理。

import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, SD3Transformer2DModel, StableDiffusion3Pipeline
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    subfolder="text_encoder_3",
    quantization_config=quant_config,
    torch_dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = SD3Transformer2DModel.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    subfolder="transformer",
    quantization_config=quant_config,
    torch_dtype=torch.float16,
)

pipeline = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    torch_dtype=torch.float16,
    device_map="balanced",
)

prompt = "a tiny astronaut hatching from an egg on the moon"
image = pipeline(prompt, num_inference_steps=28, guidance_scale=7.0).images[0]
image.save("sd3.png")

在 T5 文本编码器中使用长提示词

默认情况下,T5 文本编码器的提示词最大序列长度为 256。可以通过设置 max_sequence_length 来调整以接受更少或更多的 token。请注意,较长的序列需要更多的资源并会导致更长的生成时间,例如在批量推理时。

prompt = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. It features the distinctive, bulky body shape of a hippo. However, instead of the usual grey skin, the creature’s body resembles a golden-brown, crispy waffle fresh off the griddle. The skin is textured with the familiar grid pattern of a waffle, each square filled with a glistening sheen of syrup. The environment combines the natural habitat of a hippo with elements of a breakfast table setting, a river of warm, melted butter, with oversized utensils or plates peeking out from the lush, pancake-like foliage in the background, a towering pepper mill standing in for a tree.  As the sun rises in this fantastical world, it casts a warm, buttery glow over the scene. The creature, content in its butter river, lets out a yawn. Nearby, a flock of birds take flight"

image = pipe(
    prompt=prompt,
    negative_prompt="",
    num_inference_steps=28,
    guidance_scale=4.5,
    max_sequence_length=512,
).images[0]

向 T5 文本编码器发送不同的提示词

您可以向 CLIP 文本编码器和 T5 文本编码器发送不同的提示词,以防止提示词被 CLIP 文本编码器截断并改善生成效果。

CLIP 文本编码器的提示词仍然被截断到 77 个 token 的限制。

prompt = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. A river of warm, melted butter, pancake-like foliage in the background, a towering pepper mill standing in for a tree."

prompt_3 = "A whimsical and creative image depicting a hybrid creature that is a mix of a waffle and a hippopotamus, basking in a river of melted butter amidst a breakfast-themed landscape. It features the distinctive, bulky body shape of a hippo. However, instead of the usual grey skin, the creature’s body resembles a golden-brown, crispy waffle fresh off the griddle. The skin is textured with the familiar grid pattern of a waffle, each square filled with a glistening sheen of syrup. The environment combines the natural habitat of a hippo with elements of a breakfast table setting, a river of warm, melted butter, with oversized utensils or plates peeking out from the lush, pancake-like foliage in the background, a towering pepper mill standing in for a tree.  As the sun rises in this fantastical world, it casts a warm, buttery glow over the scene. The creature, content in its butter river, lets out a yawn. Nearby, a flock of birds take flight"

image = pipe(
    prompt=prompt,
    prompt_3=prompt_3,
    negative_prompt="",
    num_inference_steps=28,
    guidance_scale=4.5,
    max_sequence_length=512,
).images[0]

用于 Stable Diffusion 3 的微型自动编码器

用于 Stable Diffusion 的微型自动编码器 (TAESD3) 是由 Ollin Boer Bohan 开发的 Stable Diffusion 3 的 VAE 的微型蒸馏版本,可以几乎瞬间解码 StableDiffusion3Pipeline 的潜变量。

与 Stable Diffusion 3 一起使用

import torch
from diffusers import StableDiffusion3Pipeline, AutoencoderTiny

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3-medium-diffusers", torch_dtype=torch.float16
)
pipe.vae = AutoencoderTiny.from_pretrained("madebyollin/taesd3", torch_dtype=torch.float16)
pipe = pipe.to("cuda")

prompt = "slice of delicious New York-style berry cheesecake"
image = pipe(prompt, num_inference_steps=25).images[0]
image.save("cheesecake.png")

通过 from_single_file 加载原始检查点

SD3Transformer2DModelStableDiffusion3Pipeline 类支持通过 from_single_file 方法加载原始检查点。此方法允许您加载用于训练模型的原始检查点文件。

为 SD3Transformer2DModel 加载原始检查点

from diffusers import SD3Transformer2DModel

model = SD3Transformer2DModel.from_single_file("https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium.safetensors")

为 StableDiffusion3Pipeline 加载单个检查点

加载不带 T5 的单个文件检查点

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium_incl_clips.safetensors",
    torch_dtype=torch.float16,
    text_encoder_3=None
)
pipe.enable_model_cpu_offload()

image = pipe("a picture of a cat holding a sign that says hello world").images[0]
image.save('sd3-single-file.png')

加载带 T5 的单个文件检查点

以下示例加载以 8 位浮点格式存储的检查点,需要 PyTorch 2.3 或更高版本。

import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3-medium/blob/main/sd3_medium_incl_clips_t5xxlfp8.safetensors",
    torch_dtype=torch.float16,
)
pipe.enable_model_cpu_offload()

image = pipe("a picture of a cat holding a sign that says hello world").images[0]
image.save('sd3-single-file-t5-fp8.png')

为 Stable Diffusion 3.5 Transformer 模型加载单个文件检查点

import torch
from diffusers import SD3Transformer2DModel, StableDiffusion3Pipeline

transformer = SD3Transformer2DModel.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-3.5-large-turbo/blob/main/sd3.5_large.safetensors",
    torch_dtype=torch.bfloat16,
)
pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    transformer=transformer,
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
image = pipe("a cat holding a sign that says hello world").images[0]
image.save("sd35.png")

StableDiffusion3Pipeline

class diffusers.StableDiffusion3Pipeline

< >

( 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 image_encoder: SiglipVisionModel = None feature_extractor: 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 类的分词器。
  • image_encoder (SiglipVisionModel, optional) — 用于 IP Adapter 的预训练视觉模型。
  • feature_extractor (SiglipImageProcessor, optional) — 用于 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 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 skip_guidance_layers: typing.List[int] = None skip_layer_guidance_scale: float = 2.8 skip_layer_guidance_stop: float = 0.2 skip_layer_guidance_start: float = 0.01 mu: typing.Optional[float] = None ) ~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutputtuple

参数

  • prompt (strList[str], optional) — 用于引导图像生成的提示或提示列表。如果未定义,则必须传递 `prompt_embeds`。
  • prompt_2 (strList[str], optional) — 将发送到 `tokenizer_2` 和 `text_encoder_2` 的提示或提示列表。如果未定义,将使用 `prompt`。
  • prompt_3 (strList[str], optional) — 将发送到 `tokenizer_3` 和 `text_encoder_3` 的提示或提示列表。如果未定义,将使用 `prompt`。
  • height (int, optional, 默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度(以像素为单位)。为获得最佳效果,默认设置为 1024。
  • width (int, optional, 默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度(以像素为单位)。为获得最佳效果,默认设置为 1024。
  • num_inference_steps (int, optional, 默认为 50) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像,但会牺牲推理速度。
  • sigmas (List[float], optional) — 用于去噪过程的自定义 sigmas,适用于在其 `set_timesteps` 方法中支持 `sigmas` 参数的调度器。如果未定义,将使用传递 `num_inference_steps` 时的默认行为。
  • guidance_scale (float, optional, 默认为 7.0) — 如Classifier-Free Diffusion Guidance中所定义的引导比例。`guidance_scale` 被定义为Imagen Paper中公式2的 `w`。通过设置 `guidance_scale > 1` 来启用引导比例。更高的引导比例会鼓励生成与文本 `prompt` 紧密相关的图像,但这通常会牺牲图像质量。
  • negative_prompt (strList[str], optional) — 不用于引导图像生成的提示或提示列表。如果未定义,则必须传递 `negative_prompt_embeds`。在不使用引导时(即 `guidance_scale` 小于 `1` 时)会被忽略。
  • negative_prompt_2 (strList[str], optional) — 不用于引导图像生成并发送到 `tokenizer_2` 和 `text_encoder_2` 的提示或提示列表。如果未定义,将使用 `negative_prompt`。
  • negative_prompt_3 (strList[str], optional) — 不用于引导图像生成并发送到 `tokenizer_3` 和 `text_encoder_3` 的提示或提示列表。如果未定义,将使用 `negative_prompt`。
  • num_images_per_prompt (int, optional, 默认为 1) — 每个提示要生成的图像数量。
  • generator (torch.GeneratorList[torch.Generator], optional) — 一个或多个 torch generator,用于使生成过程具有确定性。
  • latents (torch.FloatTensor, optional) — 预生成的噪声潜变量,从高斯分布中采样,用作图像生成的输入。可用于使用不同提示微调相同的生成过程。如果未提供,将使用提供的随机 `generator` 进行采样生成潜变量张量。
  • prompt_embeds (torch.FloatTensor, optional) — 预生成的文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `prompt` 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.FloatTensor, optional) — 预生成的负向文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `negative_prompt` 输入参数生成 negative_prompt_embeds。
  • pooled_prompt_embeds (torch.FloatTensor, optional) — 预生成的池化文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `prompt` 输入参数生成池化文本嵌入。
  • negative_pooled_prompt_embeds (torch.FloatTensor, optional) — 预生成的负向池化文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `negative_prompt` 输入参数生成池化的 negative_prompt_embeds。
  • ip_adapter_image (PipelineImageInput, optional) — 可选的图像输入,用于与 IP Adapters 配合使用。
  • ip_adapter_image_embeds (torch.Tensor, optional) — 为 IP-Adapter 预生成的图像嵌入。应为形状为 `(batch_size, num_images, emb_dim)` 的张量。如果 `do_classifier_free_guidance` 设置为 `True`,则应包含负向图像嵌入。如果未提供,将从 `ip_adapter_image` 输入参数计算嵌入。
  • output_type (str, optional, 默认为 "pil") — 生成图像的输出格式。在 PIL: PIL.Image.Imagenp.array 之间选择。
  • return_dict (bool, optional, 默认为 True) — 是否返回一个 `~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutput` 而不是一个普通的元组。
  • joint_attention_kwargs (dict, optional) — 一个 kwargs 字典,如果指定,将传递给在 diffusers.models.attention_processor 中 `self.processor` 下定义的 `AttentionProcessor`。
  • callback_on_step_end (Callable, optional) — 在推理过程中每个去噪步骤结束时调用的函数。该函数使用以下参数调用:`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, optional) — `callback_on_step_end` 函数的张量输入列表。列表中指定的张量将作为 `callback_kwargs` 参数传递。您只能包含在您的 pipeline 类的 `._callback_tensor_inputs` 属性中列出的变量。
  • max_sequence_length (int 默认为 256) — 与 `prompt` 一起使用的最大序列长度。
  • skip_guidance_layers (List[int], optional) — 一个整数列表,指定在引导期间要跳过的层。如果未提供,所有层都将用于引导。如果提供,引导将仅应用于列表中指定的层。StabiltyAI 针对 Stable Diffusion 3.5 Medium 推荐的值为 [7, 8, 9]。
  • skip_layer_guidance_scale (int, optional) — `skip_guidance_layers` 中指定层的引导比例。引导将以 `skip_layer_guidance_scale` 的比例应用于 `skip_guidance_layers` 中指定的层。引导将以 `1` 的比例应用于其余层。
  • skip_layer_guidance_stop (int, optional) — `skip_guidance_layers` 中指定层的引导停止的步骤。引导将应用于 `skip_guidance_layers` 中指定的层,直到达到 `skip_layer_guidance_stop` 中指定的分数。StabiltyAI 针对 Stable Diffusion 3.5 Medium 推荐的值为 0.2。
  • skip_layer_guidance_start (int, optional) — `skip_guidance_layers` 中指定层的引导开始的步骤。引导将从 `skip_layer_guidance_start` 中指定的分数开始应用于 `skip_guidance_layers` 中指定的层。StabiltyAI 针对 Stable Diffusion 3.5 Medium 推荐的值为 0.01。
  • mu (float, optional) — 用于 `dynamic_shifting` 的 `mu` 值。

返回

~pipelines.stable_diffusion_3.StableDiffusion3PipelineOutputtuple

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

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

示例

>>> import torch
>>> from diffusers import StableDiffusion3Pipeline

>>> pipe = StableDiffusion3Pipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = pipe(prompt).images[0]
>>> image.save("sd3.png")

encode_image

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] device: device ) torch.Tensor

参数

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

返回

torch.Tensor

编码后的图像特征表示。

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

encode_prompt

< >

( 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 (strList[str], optional) — 要编码的提示
  • prompt_2 (strList[str], optional) — 将发送到 `tokenizer_2` 和 `text_encoder_2` 的提示或提示列表。如果未定义,`prompt` 将用于所有文本编码器
  • prompt_3 (strList[str], optional) — 将发送到 `tokenizer_3` 和 `text_encoder_3` 的提示或提示列表。如果未定义,`prompt` 将用于所有文本编码器
  • device — (torch.device): torch 设备
  • num_images_per_prompt (int) — 每个提示应生成的图像数量
  • do_classifier_free_guidance (bool) — 是否使用无分类器引导
  • negative_prompt (strList[str], optional) — 不用于引导图像生成的提示或提示列表。如果未定义,则必须传递 `negative_prompt_embeds`。在不使用引导时(即 `guidance_scale` 小于 `1` 时)会被忽略。
  • negative_prompt_2 (strList[str], optional) — 不用于引导图像生成并发送到 `tokenizer_2` 和 `text_encoder_2` 的提示或提示列表。如果未定义,`negative_prompt` 将用于所有文本编码器。
  • negative_prompt_3 (strList[str], optional) — 不用于引导图像生成并发送到 `tokenizer_3` 和 `text_encoder_3` 的提示或提示列表。如果未定义,`negative_prompt` 将用于所有文本编码器。
  • prompt_embeds (torch.FloatTensor, optional) — 预生成的文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `prompt` 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.FloatTensor, optional) — 预生成的负向文本嵌入。可用于轻松微调文本输入,例如提示加权。如果未提供,将从 `negative_prompt` 输入参数生成 negative_prompt_embeds。
  • 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 device: typing.Optional[torch.device] = None num_images_per_prompt: 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_imageip_adapter_image_embeds

< > 在 GitHub 上更新