Diffusers documentation

深度到图像

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

深度到图像

LoRA

Stable Diffusion 模型还可以使用 MiDaS 根据图像推断深度。这使得您可以传入文本提示和初始图像来引导新图像的生成,同时传入 depth_map 以保留图像结构。

请务必查看 Stable Diffusion 的 技巧 部分,了解如何探索调度器速度与质量之间的权衡,以及如何高效地复用流水线组件!

如果您对使用某个任务的官方检查点感兴趣,请探索 CompVis 和 Stability AI Hub 组织!

StableDiffusionDepth2ImgPipeline

类 diffusers.StableDiffusionDepth2ImgPipeline

< >

( vae: AutoencoderKLtext_encoder: CLIPTextModeltokenizer: CLIPTokenizerunet: UNet2DConditionModelscheduler: KarrasDiffusionSchedulersdepth_estimator: DPTForDepthEstimationfeature_extractor: DPTImageProcessorPil )

参数

使用 Stable Diffusion 进行文本引导的深度图到图像生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法(下载、保存、在特定设备上运行等),请参阅父类文档。

该 pipeline 还继承了以下加载方法:

__call__

< >

( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonedepth_map: typing.Optional[torch.Tensor] = Nonestrength: float = 0.8num_inference_steps: int | None = 50guidance_scale: float | None = 7.5negative_prompt: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float | None = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecross_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']**kwargs ) → StableDiffusionPipelineOutput or tuple

参数

  • prompt (str 或 list[str],可选) — 用于引导图像生成的提示词或提示词列表。如果未定义,则需要传入 prompt_embeds。
  • image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image] 或 list[np.ndarray]) — Image 或表示图像批次的张量,用作起始点。仅当 depth_map 不为 None 时,才能将图像潜在表示作为 image 传入。
  • depth_map (torch.Tensor, 可选) — 用于图像生成过程的额外条件输入的深度预测。如果未定义,则自动使用 self.depth_estimator 预测深度。
  • strength (float, 可选,默认为 0.8) — 指示对参考 image 进行变换的程度。取值必须在 0 到 1 之间。image 用作起始点,strength 越高,添加的噪声越多。去噪步数取决于初始添加的噪声量。当 strength 为 1 时,添加的噪声达到最大值,去噪过程将运行 num_inference_steps 中指定的完整迭代次数。值为 1 时,基本上会忽略 image。
  • num_inference_steps (int,可选,默认值为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的图像,但推理速度会更慢。此参数受 strength 调节。
  • guidance_scale (float,可选,默认值为 7.5) — 较高的 guidance scale 值会促使模型生成与文本 prompt 紧密相关的图像,但代价是图像质量降低。当 guidance_scale > 1 时,guidance scale 生效。
  • negative_prompt (str 或 list[str],可选) — 用于指导图像生成中不应包含的内容的提示词或提示词列表。如果未定义,则需要改为传入 negative_prompt_embeds。在未使用引导(guidance_scale < 1)时将被忽略。
  • num_images_per_prompt (int,可选,默认为 1) — 每个提示词生成的图像数量。
  • eta(float,可选,默认值为 0.0)— 对应 DDIM 论文中的参数 eta (η)。仅适用于 DDIMScheduler,在其他调度器中会被忽略。
  • generator (torch.Generator 或 list[torch.Generator],可选) — 用于使生成过程确定性的 torch.Generator。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入(提示词加权)。如果未提供,则从 prompt 输入参数生成文本嵌入。
  • negative_prompt_embeds (torch.Tensor,可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入(提示词权重)。如果未提供,negative_prompt_embeds 将根据 negative_prompt 输入参数生成。
  • output_type (str,可选,默认为 "pil") — 生成图像的输出格式。可选 PIL.Image 或 np.array。
  • return_dict (bool,可选,默认为 True) — 是否返回 StableDiffusionPipelineOutput 而不是普通元组。
  • cross_attention_kwargs (dict, 可选) — 一个 kwargs 字典,如果指定,将作为参数传递给 self.processor 中定义的 AttentionProcessor。
  • clip_skip (int, 可选) — 在计算提示嵌入时,从 CLIP 中跳过的层数。值为 1 表示使用倒数第二层的输出来计算提示嵌入。
  • 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 属性中列出的变量。

返回值

StableDiffusionPipelineOutput 或 tuple

如果 return_dict 为 True,则返回 StableDiffusionPipelineOutput,否则返回一个 tuple,其中第一个元素是包含生成图像的列表。

用于生成的 pipeline 的调用函数。

示例:

>>> import torch
>>> import requests
>>> from PIL import Image

>>> from diffusers import StableDiffusionDepth2ImgPipeline

>>> pipe = StableDiffusionDepth2ImgPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-2-depth",
...     torch_dtype=torch.float16,
... )
>>> pipe.to("cuda")


>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> init_image = Image.open(requests.get(url, stream=True).raw)
>>> prompt = "two tigers"
>>> n_prompt = "bad, deformed, ugly, bad anotomy"
>>> image = pipe(prompt=prompt, image=init_image, negative_prompt=n_prompt, strength=0.7).images[0]

enable_attention_slicing

< >

( slice_size: str | int = 'auto' )

参数

  • slice_size (str 或 int,可选,默认为 "auto") — 当值为 "auto" 时,将输入到注意力头的数据减半,因此注意力计算将分两步进行。如果值为 "max",则每次只运行一个切片,从而节省最大量的内存。如果提供了数字,则使用 attention_head_dim // slice_size 个切片。在这种情况下,attention_head_dim 必须是 slice_size 的倍数。

启用切片注意力计算。启用此选项后,注意力模块会将输入张量切分为多个切片,分步计算注意力。当存在多个注意力头时,计算将按顺序针对每个头执行。此功能可用于节省部分内存,代价是速度略有下降。

> ⚠️ 如果您已经在使用 PyTorch > 2.0 或 xFormers 中的 scaled_dot_product_attention(SDPA),请勿启用注意力切片。这些注意力计算本身已经非常节省内存,因此您无需启用 > 此功能。如果在 SDPA 或 xFormers 上启用注意力切片,可能会导致严重的性能下降!

示例:

>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]

disable_attention_slicing

< >

( )

禁用切片注意力计算。如果之前调用过 enable_attention_slicing,则注意力将一次性计算完成。

enable_xformers_memory_efficient_attention

< >

( attention_op: typing.Optional[typing.Callable] = None )

参数

启用来自 xFormers 的内存高效注意力机制。启用此选项后,您应能观察到更低的 GPU 内存占用,并且在推理期间可能会获得加速。训练期间的加速并不保证。

> ⚠️ 当同时启用 memory efficient attention 和 sliced attention 时,memory efficient attention 具有 > 优先权。

示例:

>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)

disable_xformers_memory_efficient_attention

< >

( )

禁用来自 xFormers 的内存高效注意力。

load_textual_inversion

< >

( pretrained_model_name_or_path: str | list[str] | dict[str, torch.Tensor] | list[dict[str, torch.Tensor]]token: str | list[str] | None = Nonetokenizer: 'PreTrainedTokenizer' | None = Nonetext_encoder: 'PreTrainedModel' | None = None**kwargs )

参数

  • pretrained_model_name_or_path (str 或 os.PathLike 或 list[str or os.PathLike] 或 Dict 或 list[Dict]) — 可以是以下其中一项,也可以是它们的列表:
    • 一个字符串,即托管在 Hub 上的预训练模型的 model id(例如 sd-concepts-library/low-poly-hd-logos-icons)。
    • 指向包含文本反转权重的目录的路径(例如 ./my_text_inversion_directory/)。
    • 指向包含文本反转权重的文件的路径(例如 ./my_text_inversions.pt)。
    • 一个 torch 状态字典。
  • token (str 或 list[str],可选) — 用于覆盖文本反转权重所使用的 token。如果 pretrained_model_name_or_path 是一个列表,则 token 也必须是一个长度相等的列表。
  • text_encoder (CLIPTextModel,可选) — 冻结的文本编码器(clip-vit-large-patch14)。 如果未指定,函数将使用 self.tokenizer。
  • tokenizer (CLIPTokenizer,可选) — 用于对文本进行分词的 CLIPTokenizer。如果未指定,函数将使用 self.tokenizer。
  • weight_name (str, 可选) — 自定义权重文件的名称。在以下情况下应使用此参数:
    • 保存的文本反演文件采用 🤗 Diffusers 格式,但保存时使用了特定的权重名称,例如 text_inv.bin。
    • 保存的文本反演文件采用 Automatic1111 格式。
  • cache_dir (str | os.PathLike, 可选) — 如果未使用标准缓存,则下载的预训练模型配置将被缓存到的目录路径。
  • force_download (bool,可选,默认为 False) — 是否强制(重新)下载模型权重和配置文件,如果存在缓存版本则覆盖它们。
  • proxies (dict[str, str],可选) — 按协议或端点使用的代理服务器字典,例如 {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。每次请求都会使用这些代理。
  • local_files_only (bool,可选,默认为 False) — 是否仅加载本地的模型权重和配置文件。如果设置为 True,则不会从 Hub 下载模型。
  • hf_token (str 或 bool,可选) — 用于远程文件的 HTTP bearer 授权令牌。如果为 True,则使用由 diffusers-cli login 生成的令牌(存储在 ~/.huggingface 中)。
  • revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 id,或 Git 允许的任何标识符。
  • subfolder (str,可选,默认为 "") — 模型文件在 Hub 或本地更大的模型仓库中的子文件夹位置。
  • mirror (str, 可选) — 镜像源,用于解决在中国下载模型时可能遇到的访问问题。我们不保证该源的时效性或安全性,详情请参阅镜像站点。

将 Textual Inversion 嵌入加载到 StableDiffusionPipeline 的文本编码器中(同时支持 🤗 Diffusers 和 Automatic1111 格式)。

示例:

要在 🤗 Diffusers 格式中加载 Textual Inversion 嵌入向量:

from diffusers import StableDiffusionPipeline
import torch

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")

pipe.load_textual_inversion("sd-concepts-library/cat-toy")

prompt = "A <cat-toy> backpack"

image = pipe(prompt, num_inference_steps=50).images[0]
image.save("cat-backpack.png")

要在 Automatic1111 格式中加载 Textual Inversion 嵌入向量,请先下载该向量(例如从 civitAI 下载),然后加载该向量

本地:

from diffusers import StableDiffusionPipeline
import torch

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")

pipe.load_textual_inversion("./charturnerv2.pt", token="charturnerv2")

prompt = "charturnerv2, multiple views of the same character in the same outfit, a character turnaround of a woman wearing a black jacket and red shirt, best quality, intricate details."

image = pipe(prompt, num_inference_steps=50).images[0]
image.save("character.png")

load_lora_weights

< >

( pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor]adapter_name: str | None = Nonehotswap: bool = False**kwargs )

参数

  • pretrained_model_name_or_path_or_dict (str 或 os.PathLike 或 dict) — 参见 lora_state_dict()。
  • adapter_name (str, 可选) — 用于引用已加载的适配器模型的适配器名称。如果未指定,将使用 default_{i},其中 i 为正在加载的适配器总数。
  • low_cpu_mem_usage (bool,可选) — 通过仅加载预训练的 LoRA 权重而不初始化随机权重,来加快模型加载速度。
  • hotswap (bool, 可选) — 默认值为 False. 是否用新加载的适配器就地替换现有的(LoRA)适配器。这意味着,不会加载额外的适配器,而是将现有适配器的权重替换为新适配器的权重。这样可能更快且更节省内存。然而,热替换的主要优势在于,当模型使用 torch.compile 编译时,加载新适配器无需重新编译模型。使用热替换时,传入的 adapter_name 应为已加载适配器的名称。如果新适配器和旧适配器的秩和/或 LoRA alpha(即缩放)不同,在加载适配器之前需要调用一个额外方法:pipeline = ... # 加载 diffusers pipeline max_rank = ... # 想要加载的所有 LoRA 中的最高秩 # 在编译和加载 LoRA 适配器*之前*调用 pipeline.enable_lora_hotswap(target_rank=max_rank) pipeline.load_lora_weights(file_name) # 现在可选地编译模型 请注意,文本编码器的适配器热替换目前尚不支持。此技术还有一些其他限制,记录在此处:https://huggingface.co/docs/peft/main/en/package_reference/hotswap

    如果新适配器和旧适配器的秩和/或 LoRA alpha(即缩放)不同,则在加载适配器之前需要调用一个额外的方法:

    pipeline = ...  # load diffusers pipeline
    max_rank = ...  # the highest rank among all LoRAs that you want to load
    # call *before* compiling and loading the LoRA adapter
    pipeline.enable_lora_hotswap(target_rank=max_rank)
    pipeline.load_lora_weights(file_name)
    # optionally compile the model now

    请注意,目前尚不支持热替换文本编码器的适配器。该技术还存在一些其他限制,相关文档如下: https://huggingface.co/docs/peft/main/en/package_reference/hotswap

  • kwargs (dict,可选) — 参见 lora_state_dict()。

将 pretrained_model_name_or_path_or_dict 中指定的 LoRA 权重加载到 self.unet 和 self.text_encoder 中。

所有 kwargs 都会转发到 self.lora_state_dict。

有关状态字典加载方式的更多详细信息,请参阅 lora_state_dict()。

有关状态字典如何加载到 self.unet 的更多详细信息,请参阅 load_lora_into_unet()。

有关状态字典如何加载到 self.text_encoder 的更多详细信息,请参阅 load_lora_into_text_encoder()。

save_lora_weights

< >

( save_directory: str | os.PathLikeunet_lora_layers: dict[str, typing.Union[torch.nn.Module, torch.Tensor]] = Nonetext_encoder_lora_layers: dict[str, torch.nn.Module] = Noneis_main_process: bool = Trueweight_name: str = Nonesave_function: typing.Callable = Nonesafe_serialization: bool = Trueunet_lora_adapter_metadata = Nonetext_encoder_lora_adapter_metadata = None )

参数

  • save_directory (str 或 os.PathLike) — 用于保存 LoRA 参数的目录。如果该目录不存在,将会自动创建。
  • unet_lora_layers (dict[str, torch.nn.Module] 或 dict[str, torch.Tensor]) — 与 unet 对应的 LoRA 层的 state dict。
  • text_encoder_lora_layers (dict[str, torch.nn.Module] 或 dict[str, torch.Tensor]) — 与 text_encoder 对应的 LoRA 层的 state dict。由于它来自 🤗 Transformers,因此必须显式传入文本编码器的 LoRA state dict。
  • is_main_process (bool,可选,默认为 True) — 调用此函数的进程是否为主进程。在分布式训练期间,当需要在所有进程上调用此函数时非常有用。在这种情况下,仅在主进程上设置 is_main_process=True,以避免竞态条件。
  • save_function (Callable) — 用于保存状态字典的函数。在分布式训练期间,当您需要用其他方法替换 torch.save 时非常有用。可以通过环境变量 DIFFUSERS_SAVE_MODE 进行配置。
  • safe_serialization(bool,可选,默认为 True)—— 是否使用 safetensors 保存模型,还是使用传统的基于 pickle 的 PyTorch 方式。
  • unet_lora_adapter_metadata — 与 unet 关联的 LoRA 适配器元数据,将随状态字典一起序列化。
  • text_encoder_lora_adapter_metadata — 与文本编码器关联的 LoRA 适配器元数据,将随状态字典一起序列化。

保存与 UNet 和文本编码器对应的 LoRA 参数。

encode_prompt

< >

( promptdevicenum_images_per_promptdo_classifier_free_guidancenegative_prompt = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonelora_scale: float | None = Noneclip_skip: int | None = None )

参数

  • prompt (str 或 list[str],可选) — 要编码的提示
  • device — (torch.device): torch 设备
  • num_images_per_prompt (int) — 每个提示词应生成的图像数量
  • do_classifier_free_guidance (bool) — 是否使用 classifier free guidance
  • negative_prompt (str 或 list[str],可选) — 用于不引导图像生成的提示词。如果未定义,则必须传入 negative_prompt_embeds。在未使用引导时会被忽略(即当 guidance_scale 小于 1 时忽略)。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入,例如 提示词加权。如果未提供,文本嵌入将从 prompt 输入参数生成。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入,例如提示词加权。如果未提供,negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • lora_scale (float, 可选) — 如果加载了 LoRA 层,将应用于文本编码器所有 LoRA 层的 LoRA 缩放系数。
  • clip_skip (int, 可选) — 在计算提示嵌入时,从 CLIP 中跳过的层数。值为 1 表示使用倒数第二层的输出来计算提示嵌入。

将提示词编码为文本编码器的隐藏状态。

StableDiffusionPipelineOutput

类 diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarraynsfw_content_detected: list[bool] | None )

参数

  • images (list[PIL.Image.Image] 或 np.ndarray) — 长度为 batch_size 的去噪 PIL 图像列表,或形状为 (batch_size, height, width, num_channels) 的 NumPy 数组。
  • nsfw_content_detected (list[bool]) — 一个列表,指示对应的生成图像是否包含“不适合工作场所”(nsfw)内容;如果无法执行安全检查,则为 None。

Stable Diffusion 管道的输出类。

Update on GitHub