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 조직에서 텍스트-이미지, 이미지-이미지, 인페인팅과 같은 작업에 대한 공식 모델 체크포인트를 확인해 보세요.

Scheduler의 가이드를 확인하여 스케줄러의 속도와 품질 사이의 트레이드오프를 탐색하는 방법을 배우고, 파이프라인 간 구성 요소 재사용 섹션을 확인하여 동일한 구성 요소를 여러 파이프라인에 효율적으로 로드하는 방법을 배워보세요.

다음 라이브러리가 설치되어 있는지 확인하세요.

# 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와 같은 다른 diffusion 모델과 동일한 방식으로 사용할 수 있음을 의미합니다.

텍스트-이미지

Kandinsky 모델을 어떤 작업에 사용하든, 프롬프트를 인코딩하고 이미지 임베딩을 생성하기 위해 prior 파이프라인을 설정하는 것부터 시작합니다. prior 파이프라인은 또한 negative prompt ""에 해당하는 negative_image_embeds를 생성합니다. 더 나은 결과를 얻으려면 prior 파이프라인에 실제 negative_prompt를 전달할 수 있지만, 이렇게 하면 prior 파이프라인의 실효 배치 크기가 2배로 증가합니다.

Kandinsky 2.1

Kandinsky 2.2

Kandinsky 3

🤗 Diffusers는 KandinskyCombinedPipeline와 KandinskyV22CombinedPipeline을 통해 end-to-end 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을 통해 end-to-end 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

end-to-end KandinskyInpaintCombinedPipeline와 KandinskyV22InpaintCombinedPipeline를 사용하여 내부적으로 prior와 decoder 파이프라인을 함께 호출할 수도 있습니다. 이를 위해 AutoPipelineForInpainting를 사용하세요:

Kandinsky 2.1

Kandinsky 2.2

보간

Interpolation을 사용하면 이미지와 텍스트 임베딩 사이의 잠재 공간(latent space)을 탐색할 수 있으며, 이는 이전 모델의 중간 출력 중 일부를 확인하는 좋은 방법입니다. 이전 파이프라인과 보간할 두 이미지를 로드하세요:

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은 깊이 맵이나 엣지 검출과 같은 추가 입력으로 사전 학습된 대규모 diffusion 모델을 조건화할 수 있게 합니다. 예를 들어, 깊이 맵으로 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"

텍스트-이미지

이전 파이프라인과 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"

이전 파이프라인과 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를 이미지로 디코딩하기 위한 두 번째 파이프라인이 필요하다는 점에서 독특합니다. 대부분의 계산이 두 번째 파이프라인에서 수행되므로 최적화 작업은 이 부분에 집중해야 합니다. 추론 시 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)

이는 attention processor를 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

클래스 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