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 foi criado por Arseniy Shakhmatov, Anton Razzhigaev, Aleksandr Nikolich, Vladimir Arkhipkin, Igor Pavlov, Andrey Kuznetsov e Denis Dimitrov.

A descrição em sua página no GitHub é:

O Kandinsky 2.1 herda as melhores práticas do Dall-E 2 e da difusão latente, ao mesmo tempo em que introduz algumas ideias novas. Como codificador de texto e imagem, ele utiliza o modelo CLIP e um prior de difusão de imagem (mapeamento) entre os espaços latentes das modalidades do CLIP. Essa abordagem aumenta o desempenho visual do modelo e abre novos horizontes na fusão de imagens e na manipulação de imagens guiada por texto.

O código-fonte original pode ser encontrado em ai-forever/Kandinsky-2.

Confira a organização Kandinsky Community no Hub para os checkpoints oficiais de modelos para tarefas como text-to-image, image-to-image e inpainting.

Certifique-se de consultar o guia de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção reutilização de componentes entre pipelines para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

Certifique-se de que as seguintes bibliotecas estão instaladas.

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

O uso de Kandinsky 2.1 e 2.2 é muito semelhante! A única diferença é que o Kandinsky 2.2 não aceita prompt como entrada ao decodificar os latentes. Em vez disso, o Kandinsky 2.2 aceita apenas image_embeds durante a decodificação.

O Kandinsky 3 possui uma arquitetura mais concisa e não requer um modelo prévio. Isso significa que seu uso é idêntico ao de outros modelos de difusão, como o Stable Diffusion XL.

Texto para imagem

Para usar os modelos Kandinsky em qualquer tarefa, você sempre começa configurando o pipeline prior para codificar o prompt e gerar os embeddings da imagem. O pipeline prior também gera negative_image_embeds que correspondem ao prompt negativo "". Para obter melhores resultados, você pode passar um negative_prompt real para o pipeline prior, mas isso aumentará o tamanho efetivo do lote do pipeline prior em 2x.

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 O Diffusers também fornece uma API de ponta a ponta com o KandinskyCombinedPipeline e o KandinskyV22CombinedPipeline, o que significa que você não precisa carregar separadamente o pipeline de prior e o pipeline de texto para imagem. O pipeline combinado carrega automaticamente tanto o modelo de prior quanto o decodificador. Você ainda pode definir valores diferentes para o pipeline de prior com os parâmetros prior_guidance_scale e prior_num_inference_steps, se desejar.

Use o AutoPipelineForText2Image para chamar automaticamente os pipelines combinados por baixo dos panos:

Kandinsky 2.1

Kandinsky 2.2

Imagem para imagem

Para image-to-image, passe a imagem inicial e o prompt de texto para condicionar a imagem ao pipeline. Comece carregando o pipeline anterior:

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

Baixe uma imagem para usar como condição:

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

Gere os image_embeds e negative_image_embeds com o pipeline anterior:

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

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

Agora, passe a imagem original, bem como todos os prompts e embeddings, para o pipeline para gerar uma imagem:

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 O Diffusers também fornece uma API de ponta a ponta com o KandinskyImg2ImgCombinedPipeline e o KandinskyV22Img2ImgCombinedPipeline, o que significa que você não precisa carregar separadamente o prior e o pipeline de imagem para imagem. O pipeline combinado carrega automaticamente tanto o modelo prior quanto o decodificador. Você ainda pode definir valores diferentes para o pipeline prior com os parâmetros prior_guidance_scale e prior_num_inference_steps, se desejar.

Use o AutoPipelineForImage2Image para chamar automaticamente os pipelines combinados por baixo dos panos:

Kandinsky 2.1

Kandinsky 2.2

Inpainting

⚠️ Os modelos Kandinsky agora usam ⬜️ pixels brancos para representar a área mascarada, em vez de pixels pretos. Se você estiver usando KandinskyInpaintPipeline em produção, precisa alterar a máscara para usar pixels brancos:
# For PIL input
import PIL.ImageOps
mask = PIL.ImageOps.invert(mask)

# For PyTorch and NumPy input
mask = 1 - mask

Para inpainting, você precisará da imagem original, de uma máscara da área a ser substituída na imagem original e de um prompt de texto do que deve ser feito o inpainting. Carregue o pipeline anterior:

Kandinsky 2.1

Kandinsky 2.2

Carregue uma imagem inicial e crie uma máscara:

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

Gere os embeddings com o pipeline anterior:

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

Agora, passe a imagem inicial, a máscara, o prompt e os embeddings para o pipeline para gerar uma imagem:

Kandinsky 2.1

Kandinsky 2.2

Você também pode usar os pipelines KandinskyInpaintCombinedPipeline e KandinskyV22InpaintCombinedPipeline de ponta a ponta para chamar os pipelines de prior e decodificador juntos por baixo dos panos. Use o AutoPipelineForInpainting para isso:

Kandinsky 2.1

Kandinsky 2.2

Interpolação

A interpolação permite explorar o espaço latente entre os embeddings de imagem e de texto, o que é uma maneira interessante de visualizar algumas das saídas intermediárias do modelo anterior. Carregue o pipeline anterior e duas imagens que você deseja interpolar:

Kandinsky 2.1

Kandinsky 2.2

um gato

A pintura A Noite Estrelada de Van Gogh

Especifique os textos ou imagens a serem interpolados e defina os pesos para cada texto ou imagem. Experimente com os pesos para ver como eles afetam a interpolação!

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

Chame a função interpolate para gerar os embeddings e, em seguida, passe-os para o pipeline para gerar a imagem:

Kandinsky 2.1

Kandinsky 2.2

ControlNet

⚠️ O ControlNet é suportado apenas para o Kandinsky 2.2!

ControlNet permite condicionar grandes modelos de difusão pré-treinados com entradas adicionais, como um mapa de profundidade ou detecção de bordas. Por exemplo, você pode condicionar o Kandinsky 2.2 com um mapa de profundidade para que o modelo entenda e preserve a estrutura da imagem de profundidade.

Vamos carregar uma imagem e extrair seu mapa de profundidade:

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

Em seguida, você pode usar o Pipeline depth-estimation do 🤗 Transformers para processar a imagem e recuperar o mapa de profundidade:

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"

Texto para imagem

Carregue o pipeline anterior e o 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")

Gere os embeddings de imagem a partir de um prompt e de um prompt negativo:

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

Por fim, passe os embeddings da imagem e a imagem de profundidade para o KandinskyV22ControlnetPipeline para gerar uma imagem:

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

Imagem para imagem

Para image-to-image com ControlNet, você precisará usar o:

KandinskyV22PriorEmb2EmbPipeline para gerar os embeddings de imagem a partir de um prompt de texto e uma imagem
KandinskyV22ControlnetImg2ImgPipeline para gerar uma imagem a partir da imagem inicial e dos embeddings da imagem

Processe e extraia um mapa de profundidade de uma imagem inicial de um gato com o Pipeline depth-estimation do 🤗 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"

Carregue o pipeline anterior e o 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")

Passe um prompt de texto e a imagem inicial para o pipeline prior para gerar os embeddings da imagem:

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)

Agora você pode executar o KandinskyV22ControlnetImg2ImgPipeline para gerar uma imagem a partir da imagem inicial e dos embeddings da imagem:

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)

Otimizações

Kandinsky é único porque exige um pipeline anterior para gerar os mapeamentos e um segundo pipeline para decodificar os latentes em uma imagem. Os esforços de otimização devem ser focados no segundo pipeline, pois é onde a maior parte do cálculo é realizada. Aqui estão algumas dicas para melhorar o Kandinsky durante a inferência.

Ative o xFormers se você estiver usando 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()

Ative torch.compile se você estiver usando PyTorch >= 2.0 para usar automaticamente a scaled dot-product attention (SDPA):

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

Isso é o mesmo que definir explicitamente o processador de atenção para usar AttnAddedKVProcessor2_0:

from diffusers.models.attention_processor import AttnAddedKVProcessor2_0

pipe.unet.set_attn_processor(AttnAddedKVProcessor2_0())

Desloque o modelo para a CPU com enable_model_cpu_offload() para evitar erros de memória insuficiente:

  from diffusers import DiffusionPipeline
  import torch

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

Por padrão, o pipeline de texto para imagem usa o DDIMScheduler, mas você pode substituí-lo por outro agendador, como o DDPMScheduler, para ver como isso afeta o equilíbrio entre a velocidade de inferência e a qualidade da imagem:

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

Texto para imagem

Imagem para imagem

Inpainting

Interpolação

ControlNet

Texto para imagem

Imagem para imagem

Otimizações

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