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 a été créé par Arseniy Shakhmatov, Anton Razzhigaev, Aleksandr Nikolich, Vladimir Arkhipkin, Igor Pavlov, Andrey Kuznetsov et Denis Dimitrov.

La description de sa page GitHub est :

Kandinsky 2.1 reprend les meilleures pratiques de Dall-E 2 et de la diffusion latente, tout en introduisant de nouvelles idées. Il utilise le modèle CLIP comme encodeur de texte et d’image, ainsi qu’un a priori de diffusion d’image (mapping) entre les espaces latents des modalités CLIP. Cette approche améliore les performances visuelles du modèle et ouvre de nouvelles perspectives en matière de fusion d’images et de manipulation d’images guidée par le texte.

Le code source original peut être trouvé sur ai-forever/Kandinsky-2.

Consultez l'organisation Kandinsky Community sur le Hub pour les points de contrôle officiels des modèles destinés à des tâches telles que la génération d'images à partir de texte, la transformation d'image en image et l'inpainting.

Pensez à consulter le guide des Schedulers pour apprendre à explorer le compromis entre la vitesse et la qualité du scheduler, et à consulter la section réutilisation des composants entre les pipelines pour apprendre à charger efficacement les mêmes composants dans plusieurs pipelines.

Assurez-vous d'avoir installé les bibliothèques suivantes.

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

L'utilisation de Kandinsky 2.1 et 2.2 est très similaire ! La seule différence est que Kandinsky 2.2 n'accepte pas prompt comme entrée lors du décodage des latents. En revanche, Kandinsky 2.2 n'accepte que image_embeds lors du décodage.

Kandinsky 3 possède une architecture plus concise et ne nécessite pas de modèle préalable. Son utilisation est donc identique à celle d’autres modèles de diffusion comme Stable Diffusion XL.

Texte vers image

Pour utiliser les modèles Kandinsky pour toute tâche, vous commencez toujours par configurer le pipeline prior afin d’encoder le prompt et de générer les embeddings d’image. Le pipeline prior génère également des negative_image_embeds qui correspondent au prompt négatif "". Pour de meilleurs résultats, vous pouvez passer un negative_prompt réel au pipeline prior, mais cela augmentera la taille effective du lot du pipeline prior par un facteur de 2.

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers fournit également une API de bout en bout avec KandinskyCombinedPipeline et KandinskyV22CombinedPipeline, ce qui signifie qu’il n’est pas nécessaire de charger séparément le pipeline prior et le pipeline texte-vers-image. Le pipeline combiné charge automatiquement à la fois le modèle prior et le décodeur. Vous pouvez toujours définir des valeurs différentes pour le pipeline prior à l’aide des paramètres prior_guidance_scale et prior_num_inference_steps si vous le souhaitez.

Utilisez AutoPipelineForText2Image pour appeler automatiquement les pipelines combinés en arrière-plan :

Kandinsky 2.1

Kandinsky 2.2

Image vers image

Pour l'image-à-image, passez l'image initiale et le prompt de texte pour conditionner l'image au pipeline. Commencez par charger le pipeline prior :

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

Télécharger une image à utiliser comme condition :

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))

Générer les image_embeds et les negative_image_embeds avec le pipeline précédent :

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

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

Passez maintenant l'image d'origine, ainsi que tous les prompts et embeddings, au pipeline pour générer une image :

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers fournit également une API de bout en bout avec KandinskyImg2ImgCombinedPipeline et KandinskyV22Img2ImgCombinedPipeline, ce qui signifie qu’il n’est pas nécessaire de charger séparément le pipeline prior et le pipeline image-à-image. Le pipeline combiné charge automatiquement à la fois le modèle prior et le décodeur. Vous pouvez toujours définir des valeurs différentes pour le pipeline prior à l’aide des paramètres prior_guidance_scale et prior_num_inference_steps si vous le souhaitez.

Utilisez AutoPipelineForImage2Image pour appeler automatiquement les pipelines combinés en arrière-plan :

Kandinsky 2.1

Kandinsky 2.2

Inpainting

⚠️ Les modèles Kandinsky utilisent désormais des pixels blancs ⬜️ pour représenter la zone masquée, au lieu de pixels noirs. Si vous utilisez KandinskyInpaintPipeline en production, vous devez modifier le masque pour utiliser des pixels blancs :
# For PIL input
import PIL.ImageOps
mask = PIL.ImageOps.invert(mask)

# For PyTorch and NumPy input
mask = 1 - mask

Pour l'inpainting, vous aurez besoin de l'image d'origine, d'un masque de la zone à remplacer dans l'image d'origine et d'un prompt texte décrivant ce qu'il faut inpainter. Chargez le pipeline précédent :

Kandinsky 2.1

Kandinsky 2.2

Charger une image initiale et créer un masque :

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

Générer les embeddings avec le pipeline précédent :

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

Passez maintenant l'image initiale, le masque, le prompt et les embeddings au pipeline pour générer une image :

Kandinsky 2.1

Kandinsky 2.2

Vous pouvez également utiliser les pipelines de bout en bout KandinskyInpaintCombinedPipeline et KandinskyV22InpaintCombinedPipeline pour appeler les pipelines prior et decoder ensemble en interne. Utilisez AutoPipelineForInpainting pour cela :

Kandinsky 2.1

Kandinsky 2.2

Interpolation

L’interpolation vous permet d’explorer l’espace latent entre les embeddings d’image et de texte, ce qui est une excellente façon de visualiser certaines des sorties intermédiaires du modèle prior. Chargez le pipeline prior et les deux images que vous souhaitez interpoler :

Kandinsky 2.1

Kandinsky 2.2

un chat

La peinture La Nuit étoilée de Van Gogh

Spécifiez les textes ou images à interpoler et définissez les poids pour chaque texte ou image. Expérimentez avec les poids pour voir comment ils affectent l'interpolation !

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

Appel de la fonction interpolate pour générer les embeddings, puis de leur passage au pipeline pour générer l'image :

Kandinsky 2.1

Kandinsky 2.2

ControlNet

⚠️ ControlNet n'est pris en charge que pour Kandinsky 2.2 !

ControlNet permet de conditionner de grands modèles de diffusion pré-entraînés avec des entrées supplémentaires telles qu'une carte de profondeur ou une détection de contours. Par exemple, vous pouvez conditionner Kandinsky 2.2 avec une carte de profondeur afin que le modèle comprenne et conserve la structure de l'image de profondeur.

Chargons une image et extrayons sa carte de profondeur :

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

Vous pouvez ensuite utiliser le Pipeline depth-estimation de 🤗 Transformers pour traiter l'image et récupérer la carte de profondeur :

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"

Texte vers image

Chargez le pipeline précédent et le 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")

Générer les embeddings d’image à partir d’un prompt et d’un prompt négatif :

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()

Enfin, passez les embeddings d'image et l'image de profondeur à KandinskyV22ControlnetPipeline pour générer une image :

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

Image vers image

Pour l'image-à-image avec ControlNet, vous devrez utiliser :

KandinskyV22PriorEmb2EmbPipeline pour générer les embeddings d’image à partir d’un prompt texte et d’une image
KandinskyV22ControlnetImg2ImgPipeline pour générer une image à partir de l’image initiale et des embeddings d’image

Traitez et extrayez une carte de profondeur d'une image initiale d'un chat à l'aide du Pipeline depth-estimation de 🤗 Transformers :

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"

Chargez le pipeline précédent et le 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")

Transmettez un prompt de texte et l'image initiale au pipeline prior pour générer les embeddings d'image :

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)

Vous pouvez maintenant exécuter le KandinskyV22ControlnetImg2ImgPipeline pour générer une image à partir de l'image initiale et des embeddings d'image :

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)

Optimisations

Kandinsky est unique car il nécessite un pipeline préalable pour générer les correspondances, puis un second pipeline pour décoder les latents en image. Les efforts d'optimisation doivent se concentrer sur le second pipeline, car c'est là que se fait l'essentiel du calcul. Voici quelques conseils pour améliorer Kandinsky lors de l'inférence.

Activez xFormers si vous utilisez PyTorch < 2.0 :

  from diffusers import DiffusionPipeline
  import torch

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

Activez torch.compile si vous utilisez PyTorch >= 2.0 afin d’utiliser automatiquement l’attention à point produit mis à l’échelle (SDPA) :

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

Cela revient à définir explicitement le processeur d’attention à utiliser comme étant AttnAddedKVProcessor2_0 :

from diffusers.models.attention_processor import AttnAddedKVProcessor2_0

pipe.unet.set_attn_processor(AttnAddedKVProcessor2_0())

Déchargez le modèle sur le CPU avec enable_model_cpu_offload() pour éviter les erreurs de mémoire insuffisante :

  from diffusers import DiffusionPipeline
  import torch

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

Par défaut, le pipeline texte-vers-image utilise le DDIMScheduler, mais vous pouvez le remplacer par un autre planificateur comme DDPMScheduler pour voir comment cela affecte le compromis entre la vitesse d'inférence et la qualité de l'image :

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

Texte vers image

Image vers image

Inpainting

Interpolation

ControlNet

Texte vers image

Image vers image

Optimisations

KandinskyPriorPipeline

classe diffusers.KandinskyPriorPipeline

__call__

interpolate

KandinskyPipeline

classe diffusers.KandinskyPipeline

__call__

KandinskyCombinedPipeline

classe diffusers.KandinskyCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyImg2ImgPipeline

classe diffusers.KandinskyImg2ImgPipeline

__call__

KandinskyImg2ImgCombinedPipeline

classe diffusers.KandinskyImg2ImgCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyInpaintPipeline

classe diffusers.KandinskyInpaintPipeline

__call__

KandinskyInpaintCombinedPipeline

classe diffusers.KandinskyInpaintCombinedPipeline

__call__

enable_sequential_cpu_offload

call

call

call

call

call

call

call