Diffusers documentation

Kandinsky 2.1

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Kandinsky 2.1

Kandinsky 2.1 由 Arseniy Shakhmatov、Anton Razzhigaev、Aleksandr Nikolich、Vladimir Arkhipkin、Igor Pavlov、Andrey Kuznetsov 和 Denis Dimitrov 创建。

其 GitHub 页面上的描述为：

Kandinsky 2.1 继承了 Dall-E 2 和 Latent diffusion 的最佳实践，同时引入了一些新想法。它使用 CLIP 模型作为文本和图像编码器，并在 CLIP 模态的潜在空间之间引入扩散图像先验（映射）。这种方法提升了模型的视觉表现，并在图像融合以及文本引导的图像操作方面开辟了新的可能性。

原始代码库可在 ai-forever/Kandinsky-2 中找到。

在 Hub 上查看 Kandinsky Community 组织，以获取文本生成图像、图像生成图像和图像修复等任务的官方模型检查点。

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

请确保已安装以下库。

# uncomment to install the necessary libraries in Colab
#!pip install -q diffusers transformers accelerate

Kandinsky 2.1 和 2.2 的用法非常相似！唯一的区别在于，Kandinsky 2.2 在解码潜变量时不接受 prompt 作为输入。相反，Kandinsky 2.2 在解码时仅接受 image_embeds。

Kandinsky 3 的架构更为简洁，且无需依赖先验模型。这意味着其使用方式与其他扩散模型（如 Stable Diffusion XL）完全相同。

文本到图像

要将 Kandinsky 模型用于任何任务，您始终需要首先设置 prior pipeline，以编码提示词并生成图像嵌入。prior pipeline 还会生成与负向提示词 "" 对应的 negative_image_embeds。为了获得更好的效果，您可以向 prior pipeline 传入实际的 negative_prompt，但这会使 prior pipeline 的有效批处理大小增加 2 倍。

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers 还提供了端到端 API，即 KandinskyCombinedPipeline 和 KandinskyV22CombinedPipeline，这意味着您无需分别加载 prior 和 text-to-image 流水线。组合流水线会自动加载 prior 模型和 decoder。如果您愿意，仍然可以通过 prior_guidance_scale 和 prior_num_inference_steps 参数为 prior 流水线设置不同的值。

使用 AutoPipelineForText2Image 可在底层自动调用组合管道：

Kandinsky 2.1

Kandinsky 2.2

图像到图像

对于图像到图像任务，请将初始图像和文本提示词传递给流水线，以作为生成图像的条件。首先，加载先验流水线：

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

下载一张用于条件生成的图像：

from diffusers.utils import load_image

# download image
url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
original_image = load_image(url)
original_image = original_image.resize((768, 512))

使用先前的流水线生成 image_embeds 和 negative_image_embeds：

prompt = "A fantasy landscape, Cinematic lighting"
negative_prompt = "low quality, bad quality"

image_embeds, negative_image_embeds = prior_pipeline(prompt, negative_prompt).to_tuple()

现在将原始图像以及所有提示词和嵌入向量传入流水线以生成图像：

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers 还提供了端到端 API，即 KandinskyImg2ImgCombinedPipeline 和 KandinskyV22Img2ImgCombinedPipeline，这意味着您无需分别加载 prior 和图像到图像 pipeline。组合 pipeline 会自动加载 prior 模型和 decoder。如果您愿意，仍然可以通过 prior_guidance_scale 和 prior_num_inference_steps 参数为 prior pipeline 设置不同的值。

使用 AutoPipelineForImage2Image 可在底层自动调用组合管道：

Kandinsky 2.1

Kandinsky 2.2

图像修复

⚠️ Kandinsky 模型现在使用 ⬜️ 白色像素 而非黑色像素来表示遮罩区域。如果您在生产环境中使用 KandinskyInpaintPipeline，需要将遮罩更改为使用白色像素：
# For PIL input
import PIL.ImageOps
mask = PIL.ImageOps.invert(mask)

# For PyTorch and NumPy input
mask = 1 - mask

对于图像修复（inpainting），您需要原始图像、原始图像中待替换区域的掩码，以及描述要修复内容的文本提示。加载之前的流水线：

Kandinsky 2.1

Kandinsky 2.2

加载初始图像并创建掩码：

init_image = load_image("https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png")
mask = np.zeros((768, 768), dtype=np.float32)
# mask area above cat's head
mask[:250, 250:-250] = 1

使用先前的流水线生成嵌入：

prompt = "a hat"
prior_output = prior_pipeline(prompt)

现在将初始图像、掩码、提示词和嵌入传递给管道以生成图像：

Kandinsky 2.1

Kandinsky 2.2

您还可以使用端到端的 KandinskyInpaintCombinedPipeline 和 KandinskyV22InpaintCombinedPipeline，在底层同时调用 prior 和 decoder 流水线。请使用 AutoPipelineForInpainting 来实现：

Kandinsky 2.1

Kandinsky 2.2

插值

插值允许你探索图像嵌入和文本嵌入之间的潜在空间，这是一种查看先前模型中间输出的有趣方式。加载先前管道以及你想要进行插值的两张图像：

Kandinsky 2.1

Kandinsky 2.2

一只猫

梵高的《星夜》

指定要插值的文本或图像，并为每个文本或图像设置权重。尝试调整权重，观察它们如何影响插值效果！

images_texts = ["a cat", img_1, img_2]
weights = [0.3, 0.3, 0.4]

调用 interpolate 函数生成嵌入，然后将其传递给 pipeline 以生成图像：

Kandinsky 2.1

Kandinsky 2.2

ControlNet

⚠️ ControlNet 仅支持 Kandinsky 2.2！

ControlNet 允许使用深度图或边缘检测等额外输入来为大型预训练扩散模型提供条件。例如，你可以使用深度图为 Kandinsky 2.2 提供条件，使模型能够理解并保留深度图像的结构。

让我们加载一张图像并提取其深度图：

from diffusers.utils import load_image

img = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinskyv22/cat.png"
).resize((768, 768))
img

然后，您可以使用 🤗 Transformers 中的 depth-estimation Pipeline 来处理图像并获取深度图：

import torch
import numpy as np

from transformers import pipeline

def make_hint(image, depth_estimator):
    image = depth_estimator(image)["depth"]
    image = np.array(image)
    image = image[:, :, None]
    image = np.concatenate([image, image, image], axis=2)
    detected_map = torch.from_numpy(image).float() / 255.0
    hint = detected_map.permute(2, 0, 1)
    return hint

depth_estimator = pipeline("depth-estimation")
hint = make_hint(img, depth_estimator).unsqueeze(0).half().to("cuda")  # or "mps", "xpu", "cpu"

文本到图像

加载先前的 pipeline 和 KandinskyV22ControlnetPipeline：

from diffusers import KandinskyV22PriorPipeline, KandinskyV22ControlnetPipeline

prior_pipeline = KandinskyV22PriorPipeline.from_pretrained(
    "kandinsky-community/kandinsky-2-2-prior", dtype=torch.float16, use_safetensors=True
).to("cuda")  # or "mps", "xpu", "cpu"

pipeline = KandinskyV22ControlnetPipeline.from_pretrained(
    "kandinsky-community/kandinsky-2-2-controlnet-depth", dtype=torch.float16
).to("cuda")

根据提示词和负面提示词生成图像嵌入：

prompt = "A robot, 4k photo"
negative_prior_prompt = "lowres, text, error, cropped, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, out of frame, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, username, watermark, signature"

generator = torch.Generator(device="cuda").manual_seed(43)  # or "mps", "xpu", "cpu"

image_emb, zero_image_emb = prior_pipeline(
    prompt=prompt, negative_prompt=negative_prior_prompt, generator=generator
).to_tuple()

最后，将图像嵌入和深度图像传入 KandinskyV22ControlnetPipeline 以生成图像：

image = pipeline(image_embeds=image_emb, negative_image_embeds=zero_image_emb, hint=hint, num_inference_steps=50, generator=generator, height=768, width=768).images[0]
image

图像到图像

对于使用 ControlNet 的图像到图像任务，您需要使用：

使用 KandinskyV22PriorEmb2EmbPipeline 从文本提示词和图像生成图像嵌入
使用 KandinskyV22ControlnetImg2ImgPipeline 根据初始图像和图像嵌入生成图像

使用 🤗 Transformers 中的 Pipeline 对一张猫的初始图像进行处理，并提取其深度图，管道类型为 depth-estimation：

import torch
import numpy as np

from diffusers import KandinskyV22PriorEmb2EmbPipeline, KandinskyV22ControlnetImg2ImgPipeline
from diffusers.utils import load_image
from transformers import pipeline

img = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinskyv22/cat.png"
).resize((768, 768))

def make_hint(image, depth_estimator):
    image = depth_estimator(image)["depth"]
    image = np.array(image)
    image = image[:, :, None]
    image = np.concatenate([image, image, image], axis=2)
    detected_map = torch.from_numpy(image).float() / 255.0
    hint = detected_map.permute(2, 0, 1)
    return hint

depth_estimator = pipeline("depth-estimation")
hint = make_hint(img, depth_estimator).unsqueeze(0).half().to("cuda")  # or "mps", "xpu", "cpu"

加载先前的 pipeline 和 KandinskyV22ControlnetImg2ImgPipeline：

prior_pipeline = KandinskyV22PriorEmb2EmbPipeline.from_pretrained(
    "kandinsky-community/kandinsky-2-2-prior", dtype=torch.float16, use_safetensors=True
).to("cuda")  # or "mps", "xpu", "cpu"

pipeline = KandinskyV22ControlnetImg2ImgPipeline.from_pretrained(
    "kandinsky-community/kandinsky-2-2-controlnet-depth", dtype=torch.float16
).to("cuda")

将文本提示和初始图像传入 prior 流水线，以生成图像嵌入：

prompt = "A robot, 4k photo"
negative_prior_prompt = "lowres, text, error, cropped, worst quality, low quality, jpeg artifacts, ugly, duplicate, morbid, mutilated, out of frame, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, blurry, dehydrated, bad anatomy, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck, username, watermark, signature"

generator = torch.Generator(device="cuda").manual_seed(43)  # or "mps", "xpu", "cpu"

img_emb = prior_pipeline(prompt=prompt, image=img, strength=0.85, generator=generator)
negative_emb = prior_pipeline(prompt=negative_prior_prompt, image=img, strength=1, generator=generator)

现在，您可以运行 KandinskyV22ControlnetImg2ImgPipeline，根据初始图像和图像嵌入生成图像：

image = pipeline(image=img, strength=0.5, image_embeds=img_emb.image_embeds, negative_image_embeds=negative_emb.image_embeds, hint=hint, num_inference_steps=50, generator=generator, height=768, width=768).images[0]
make_image_grid([img.resize((512, 512)), image.resize((512, 512))], rows=1, cols=2)

优化

Kandinsky 的独特之处在于，它需要一个前置流水线来生成映射，以及一个第二流水线将潜在变量解码为图像。优化工作应集中在第二流水线上，因为大部分计算都在此完成。以下是一些在推理阶段提升 Kandinsky 性能的技巧。

如果您使用的是 PyTorch < 2.0，请启用 xFormers：

  from diffusers import DiffusionPipeline
  import torch

  pipe = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1", dtype=torch.float16)
+ pipe.enable_xformers_memory_efficient_attention()

如果您使用的是 PyTorch >= 2.0，请启用 torch.compile 以自动使用缩放点积注意力（SDPA）：

  pipe.unet.to(memory_format=torch.channels_last)
+ pipe.unet = torch.compile(pipe.unet, mode="reduce-overhead", fullgraph=True)

这与显式将注意力处理器设置为使用 AttnAddedKVProcessor2_0 的效果相同：

from diffusers.models.attention_processor import AttnAddedKVProcessor2_0

pipe.unet.set_attn_processor(AttnAddedKVProcessor2_0())

使用 enable_model_cpu_offload() 将模型卸载到 CPU，以避免内存不足错误：

  from diffusers import DiffusionPipeline
  import torch

  pipe = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1", dtype=torch.float16)
+ pipe.enable_model_cpu_offload()

默认情况下，文本到图像流水线使用 DDIMScheduler，但您可以将其替换为其他调度器，例如 DDPMScheduler，以观察其对推理速度与图像质量之间权衡的影响：

from diffusers import DDPMScheduler
from diffusers import DiffusionPipeline

scheduler = DDPMScheduler.from_pretrained("kandinsky-community/kandinsky-2-1", subfolder="ddpm_scheduler")
pipe = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1", scheduler=scheduler, dtype=torch.float16, use_safetensors=True).to("cuda")  # or "mps", "xpu", "cpu"

Diffusers

Kandinsky 2.1

文本到图像

图像到图像

图像修复

插值

ControlNet

文本到图像

图像到图像

优化

KandinskyPriorPipeline

class diffusers.KandinskyPriorPipeline

__call__

interpolate

KandinskyPipeline

class diffusers.KandinskyPipeline

__call__

KandinskyCombinedPipeline

class diffusers.KandinskyCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyImg2ImgPipeline

class diffusers.KandinskyImg2ImgPipeline

__call__

KandinskyImg2ImgCombinedPipeline

class diffusers.KandinskyImg2ImgCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyInpaintPipeline

class diffusers.KandinskyInpaintPipeline

__call__

KandinskyInpaintCombinedPipeline

class diffusers.KandinskyInpaintCombinedPipeline

__call__

enable_sequential_cpu_offload

call

call

call

call

call

call

call