Diffusers documentation

Kandinsky 2.1

Diffusers

Начало работы

Diffusers Установка Быстрый старт Интерфейс командной строки

Вывод

Использование конвейеров диффузии

Адаптеры и персонализация

Оптимизация и масштабирование

Базовая производительность

Вывод

Методы сообщества

Квантование

Ускорение для конкретного оборудования

Развёртывание и масштабирование

Модульные Diffusers

Обучение и дообучение

Ресурсы

Внести вклад

API

Основные классы

Модульный

Загрузчики

Модели

Конвейеры

Обзор AutoPipeline

Аудио

Изображение

Anima AnimateDiff AuraFlow Bria 3.2 Bria Fibo Bria Fibo 2.0 Bria Fibo Edit Chroma CogView3 CogView4 Модели согласованности ControlNet ControlNet с Flux.1 ControlNet с Hunyuan-DiT ControlNet со Stable Diffusion 3 ControlNet со Stable Diffusion XL ControlNet-Sana ControlNetUnion DDIM DDPM DeepFloyd IF DiT DreamLite EasyAnimate Эхо ERNIE-Image Flux Flux2 Flux3 FluxControlInpaint GLM-Image HiDream-I1 Hunyuan-DiT HunyuanImage2.1 Ideogram 4 InstructPix2Pix JoyImage Edit JoyImage Edit Plus Kandinsky 2.1 Kandinsky 2.2 Kandinsky 3 Kandinsky 5.0 Image Kolors Krea 2 Модели латентной консистентности Latent Diffusion LEDITS++LongCat-Image Lumina 2.0 Lumina-T2X Marigold NucleusMoE-Image OmniGen Ovis-Image P-H3-Image PAG Pika H3 Flex PixArt-α PixArt-Σ PRX PRX Pixel Qwen-Image 2.1 QwenImage Sana Sana Sprint Sana Video SANA-WM Shap-E Stable Cascade

Stable Diffusion

Stable unCLIP Выборка с наведением по значению VisualCloze Z-Image

Protein

Текст

Видео

Планировщики

Внутренние классы

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 создан Арсением Шахматовым, Антоном Разжигаевым, Александром Николичем, Владимиром Архипкиным, Игорем Павловым, Андреем Кузнецовым и Денисом Димитровым.

Описание с его страницы на GitHub:

Kandinsky 2.1 наследует лучшие практики от Dall-E 2 и Latent diffusion, одновременно вводя ряд новых идей. В качестве текстового и изображенийого энкодера используется модель CLIP, а также диффузионный априорный (mapping) между латентными пространствами модальностей CLIP. Такой подход повышает визуальное качество модели и открывает новые возможности для смешивания изображений и манипуляций с изображениями по текстовому руководству.

Исходный код можно найти в репозитории ai-forever/Kandinsky-2.

Ознакомьтесь с организацией Kandinsky Community на Hub, где размещены официальные контрольные точки моделей для таких задач, как генерация изображений по тексту, преобразование изображения в изображение и инпейнтинг.

Обязательно ознакомьтесь с руководством по планировщикам, чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом повторное использование компонентов в разных конвейерах, чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.

Убедитесь, что у вас установлены следующие библиотеки.

# 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-пайплайна для кодирования промпта и генерации эмбеддингов изображения. Prior-пайплайн также генерирует negative_image_embeds, соответствующие негативному промпту "". Для лучших результатов вы можете передать в prior-пайплайн реальный negative_prompt, но это увеличит эффективный размер батча prior-пайплайна в 2 раза.

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers также предоставляет сквозной API с KandinskyCombinedPipeline и KandinskyV22CombinedPipeline, что означает, что вам не нужно отдельно загружать prior и text-to-image pipeline. Комбинированный pipeline автоматически загружает как prior-модель, так и декодер. При необходимости вы по-прежнему можете задавать разные значения для prior pipeline с помощью параметров prior_guidance_scale и prior_num_inference_steps.

Используйте AutoPipelineForText2Image, чтобы автоматически вызывать объединённые пайплайны под капотом:

Kandinsky 2.1

Kandinsky 2.2

Изображение в изображение

Для задачи image-to-image передайте начальное изображение и текстовый промпт, задающий условия для изображения, в пайплайн. Начните с загрузки пайплайна 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 также предоставляет API для сквозной работы с KandinskyImg2ImgCombinedPipeline и KandinskyV22Img2ImgCombinedPipeline, что означает, что вам не нужно отдельно загружать prior и image-to-image pipeline. Комбинированный pipeline автоматически загружает как prior-модель, так и декодер. При необходимости вы по-прежнему можете задавать разные значения для prior pipeline с помощью параметров prior_guidance_scale и prior_num_inference_steps.

Используйте 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

Интерполяция

Интерполяция позволяет исследовать латентное пространство между эмбеддингами изображения и текста, что является удобным способом увидеть некоторые промежуточные выводы модели-предшественника. Загрузите пайплайн предшественника и два изображения, которые вы хотите интерполировать:

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

Затем можно использовать Pipeline depth-estimation из 🤗 Transformers для обработки изображения и получения карты глубины:

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

Изображение в изображение

Для image-to-image с ControlNet вам нужно использовать:

KandinskyV22PriorEmb2EmbPipeline для генерации эмбеддингов изображений на основе текстового промпта и изображения
KandinskyV22ControlnetImg2ImgPipeline для генерации изображения на основе исходного изображения и эмбеддингов изображения

Обработайте и извлеките карту глубины исходного изображения кошки с помощью Pipeline depth-estimation из 🤗 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"

Загрузите предыдущий конвейер и 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 на этапе инференса.

Включите xFormers, если вы используете 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()

Включите 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())

Перенесите модель на CPU с помощью enable_model_cpu_offload(), чтобы избежать ошибок нехватки памяти:

  from diffusers import DiffusionPipeline
  import torch

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

По умолчанию конвейер text-to-image использует 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

класс diffusers.KandinskyPipeline

__call__

KandinskyCombinedPipeline

класс diffusers.KandinskyCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyImg2ImgPipeline

класс diffusers.KandinskyImg2ImgPipeline

__call__

KandinskyImg2ImgCombinedPipeline

класс diffusers.KandinskyImg2ImgCombinedPipeline

__call__

enable_sequential_cpu_offload

KandinskyInpaintPipeline

класс diffusers.KandinskyInpaintPipeline

__call__

KandinskyInpaintCombinedPipeline

класс diffusers.KandinskyInpaintCombinedPipeline

__call__

enable_sequential_cpu_offload

call

call

call

call

call

call

call