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 は latents をデコードする際に prompt を入力として受け付けない点です。代わりに、Kandinsky 2.2 はデコード時に image_embeds のみを接受します。

Kandinsky 3 はより簡潔なアーキテクチャを持ち、事前モデルを必要としません。そのため、Stable Diffusion XL などの他の拡散モデルと同様に使用できます。

テキストから画像へ

Kandinsky モデルを任意のタスクに使用する場合、常にまず prior パイプラインを設定して、プロンプトをエンコードし、画像埋め込みを生成します。prior パイプラインは、ネガティブプロンプト "" に対応する negative_image_embeds も生成します。より良い結果を得るには、prior パイプラインに実際の negative_prompt を渡すことができますが、これにより prior パイプラインの有効なバッチサイズが 2 倍になります。

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers は KandinskyCombinedPipeline と KandinskyV22CombinedPipeline を用いたエンドツーエンドの API も提供しています。これにより、prior と text-to-image のパイプラインを個別にロードする必要はありません。統合パイプラインは、prior モデルとデコーダーの両方を自動的にロードします。必要に応じて、prior_guidance_scale および prior_num_inference_steps パラメータで prior パイプラインの異なる値を設定することもできます。

AutoPipelineForText2Image を使用すると、内部で統合されたパイプラインが自動的に呼び出されます。

Kandinsky 2.1

Kandinsky 2.2

画像から画像へ

画像から画像への生成では、初期画像とテキストプロンプトをパイプラインに渡して、画像の条件付けを行います。まず、priorパイプラインを読み込みます:

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 は、KandinskyImg2ImgCombinedPipeline および KandinskyV22Img2ImgCombinedPipeline によるエンドツーエンドの API も提供しています。これにより、prior と image-to-image パイプラインを個別にロードする必要はありません。統合パイプラインは、prior モデルとデコーダーの両方を自動的にロードします。必要に応じて、prior_guidance_scale および prior_num_inference_steps パラメータを使用して、prior パイプラインに異なる値を設定することもできます。

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

インペインティングには、元の画像、元の画像内で置き換える領域のマスク、そしてインペインティングする内容を示すテキストプロンプトが必要です。以前のパイプラインを読み込みます:

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

補間

Interpolationは、画像とテキストの埋め込みの間の潜在空間を探索することを可能にし、事前モデルの中間出力の一部を確認するクールな方法です。事前パイプラインと、補間したい2つの画像を読み込みます:

Kandinsky 2.1

Kandinsky 2.2

猫

ゴッホの絵画「星月夜」

補間するテキストや画像を指定し、各テキストや画像の重みを設定します。重みを調整して、補間への影響を確認してみてください!

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

interpolate関数を呼び出して埋め込みを生成し、それをパイプラインに渡して画像を生成します。

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 の Pipeline depth-estimation を使用して画像を処理し、深度マップを取得できます:

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"

テキストから画像へ

パイプラインと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 は、マッピングを生成するための事前のパイプラインと、潜変数（latents）を画像にデコードするための第2のパイプラインの両方を必要とする点で独特です。計算の大部分は第2のパイプラインで行われるため、最適化の努力はそちらに集中させるべきです。以下は、推論時の 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()

torch.compile を有効にすると、PyTorch >= 2.0 を使用している場合に、スケーリングドットプロダクトアテンション（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

クラス diffusers.KandinskyPriorPipeline

__call__

interpolate

KandinskyPipeline

class diffusers.KandinskyPipeline

__call__

KandinskyCombinedPipeline

クラス diffusers.KandinskyCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyImg2ImgPipeline

クラス diffusers.KandinskyImg2ImgPipeline

__call__

KandinskyImg2ImgCombinedPipeline

クラス 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