# Kolors: 사진과 같은 수준의 텍스트-이미지 합성을 위한 효과적인 Diffusion Model 학습

  
  

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/kolors/kolors_header_collage.png)

Kolors는 [Kuaishou Kolors 팀](https://github.com/Kwai-Kolors/Kolors)이 개발한 대규모 텍스트-이미지 생성 모델로, 잠재 확산(latent diffusion)을 기반으로 합니다. 수십억 개의 텍스트-이미지 쌍으로 학습된 Kolors는 시각적 품질, 복잡한 의미의 정확성, 중국어 및 영어 문자의 텍스트 렌더링 측면에서 오픈소스 및 클로즈드소스 모델 모두에 비해 뚜렷한 이점을 보입니다. 또한 Kolors는 중국어와 영어 입력을 모두 지원하며, 중국어 전용 콘텐츠의 이해 및 생성에서 강력한 성능을 보여줍니다. 자세한 내용은 이 [기술 보고서](https://github.com/Kwai-Kolors/Kolors/blob/master/imgs/Kolors_paper.pdf)를 참고하세요.

기술 보고서의 초록은 다음과 같습니다:

*Kolors는 텍스트-이미지 합성을 위한 잠재 확산 모델(latent diffusion model)로, 영어와 중국어에 대한 깊은 이해와 뛰어난 사진 수준의 사실감을 특징으로 합니다. Kolors 개발에 기여한 세 가지 핵심 통찰이 있습니다. 첫째, Imagen과 Stable Diffusion 3에서 사용된 대규모 언어 모델 T5와 달리, Kolors는 General Language Model(GLM)을 기반으로 구축되어 영어와 중국어 모두에 대한 이해 능력을 향상시킵니다. 또한, 세밀한 텍스트 이해를 위해 다중 모드 대규모 언어 모델을 활용하여 방대한 학습 데이터셋에 대한 캡션을 다시 작성(recaption)합니다. 이러한 전략은 특히 여러 개체를 포함하는 복잡한 의미론(semantics)에 대한 Kolors의 이해 능력을 크게 향상시키고, 고급 텍스트 렌더링 기능을 가능하게 합니다. 둘째, Kolors의 학습을 두 단계로 나누었습니다. 광범위한 지식을 다루는 개념 학습 단계와, 특별히 큐레이션된 고미학적(high-aesthetic) 데이터를 다루는 품질 개선 단계입니다. 또한, 노이즈 스케줄의 중요한 역할을 조사하고, 고해상도 이미지 생성을 최적화하기 위한 새로운 스케줄을 도입했습니다. 이러한 전략들은 생성된 고해상도 이미지의 시각적 매력을 종합적으로 향상시킵니다. 마지막으로, Kolors의 학습과 평가를 위한 가이드 역할을 하는 카테고리 균형 벤치마크 KolorsPrompts를 제안합니다. 그 결과, 일반적으로 사용되는 U-Net 백본을 사용함에도 불구하고, Kolors는 인간 평가에서 뛰어난 성능을 입증하여 기존 오픈소스 모델을 추월하고, 특히 시각적 매력 측면에서 Midjourney-v6 수준의 성능을 달성했습니다. Kolors의 코드와 가중치는 에서 공개할 예정이며, 시각 생성 커뮤니티의 향후 연구와 응용에 도움이 되기를 바랍니다.*

## 사용 예시

```python
import torch

from diffusers import DPMSolverMultistepScheduler, KolorsPipeline

pipe = KolorsPipeline.from_pretrained("Kwai-Kolors/Kolors-diffusers", dtype=torch.float16, variant="fp16")
pipe.to("cuda")  # or "mps", "xpu", "cpu"
pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config, use_karras_sigmas=True)

image = pipe(
    prompt='一张瓢虫的照片，微距，变焦，高质量，电影，拿着一个牌子，写着"可图"',
    negative_prompt="",
    guidance_scale=6.5,
    num_inference_steps=25,
).images[0]

image.save("kolors_sample.png")
```

### IP Adapter

Kolors는 작동하려면 다른 IP Adapter가 필요하며, 이미지 인코더로 [Openai-CLIP-336](https://huggingface.co/openai/clip-vit-large-patch14-336)를 사용합니다.

> [!TIP]
> Kolors에 IP Adapter를 사용하려면 24GB 이상의 VRAM이 필요합니다. 이를 사용하기 위해 소비자용 GPU에서는 [enable_model_cpu_offload()](/docs/diffusers/main/ko/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload)를 사용하는 것을 권장합니다.

> [!TIP]
> Kolors는 Diffusers에 통합되어 있지만, safetensor 파일을 사용하려면 리비전(revision)에서 이미지 인코더를 로드해야 합니다. pickle 체크포인트를 로드하는 데 문제가 없다면 원래 저장소의 main 브랜치를 계속 사용할 수 있습니다.

```python
import torch
from transformers import CLIPVisionModelWithProjection

from diffusers import DPMSolverMultistepScheduler, KolorsPipeline
from diffusers.utils import load_image

image_encoder = CLIPVisionModelWithProjection.from_pretrained(
    "Kwai-Kolors/Kolors-IP-Adapter-Plus",
    subfolder="image_encoder",
    low_cpu_mem_usage=True,
    dtype=torch.float16,
    revision="refs/pr/4",
)

pipe = KolorsPipeline.from_pretrained(
    "Kwai-Kolors/Kolors-diffusers", image_encoder=image_encoder, dtype=torch.float16, variant="fp16"
)
pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config, use_karras_sigmas=True)

pipe.load_ip_adapter(
    "Kwai-Kolors/Kolors-IP-Adapter-Plus",
    subfolder="",
    weight_name="ip_adapter_plus_general.safetensors",
    revision="refs/pr/4",
    image_encoder_folder=None,
)
pipe.enable_model_cpu_offload()

ipa_image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/kolors/cat_square.png")

image = pipe(
    prompt="best quality, high quality",
    negative_prompt="",
    guidance_scale=6.5,
    num_inference_steps=25,
    ip_adapter_image=ipa_image,
).images[0]

image.save("kolors_ipa_sample.png")
```

## KolorsPipeline[[diffusers.KolorsPipeline]]

#### diffusers.KolorsPipeline[[diffusers.KolorsPipeline]]

```python
diffusers.KolorsPipeline(vae: AutoencoderKL, text_encoder: ChatGLMModel, tokenizer: ChatGLMTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, force_zeros_for_empty_prompt: bool = False)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors.py#L123)

**매개변수:**

vae ([AutoencoderKL](/docs/diffusers/main/ko/api/models/autoencoderkl#diffusers.AutoencoderKL)) : 이미지를 잠재 표현으로 인코딩하고 잠재 표현에서 이미지로 디코딩하는 Variational Auto-Encoder (VAE) 모델입니다.

text_encoder (`ChatGLMModel`) : 고정된 텍스트 인코더. Kolors는 [ChatGLM3-6B](https://huggingface.co/THUDM/chatglm3-6b)를 사용합니다.

tokenizer (`ChatGLMTokenizer`) : [ChatGLMTokenizer](https://huggingface.co/THUDM/chatglm3-6b/blob/main/tokenization_chatglm.py) 클래스의 토크나이저.

unet ([UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : 인코딩된 이미지 레이턴트를 디노이즈하기 위한 조건부 U-Net 아키텍처.

scheduler ([SchedulerMixin](/docs/diffusers/main/ko/api/schedulers/overview#diffusers.SchedulerMixin)) : `unet`와 함께 사용되어 인코딩된 이미지 latents의 노이즈를 제거하는 스케줄러입니다. [DDIMScheduler](/docs/diffusers/main/ko/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler), 또는 [PNDMScheduler](/docs/diffusers/main/ko/api/schedulers/pndm#diffusers.PNDMScheduler) 중 하나일 수 있습니다.

force_zeros_for_empty_prompt (`bool`, *선택 사항*, 기본값 `"False"`) : 부정 프롬프트 임베딩을 항상 0으로 설정하도록 강제할지 여부입니다. 또한 `Kwai-Kolors/Kolors-diffusers`의 구성을 참고하세요.

Kolors를 사용한 텍스트-이미지 생성을 위한 Pipeline

이 모델은 [DiffusionPipeline](/docs/diffusers/main/ko/api/pipelines/overview#diffusers.DiffusionPipeline)에서 상속됩니다. 라이브러리가 모든 파이프라인에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

파이프라인은 다음 로딩 메서드도 상속합니다:
- LoRA 가중치를 로드하는 [load_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.load_lora_weights)
- LoRA 가중치를 저장하는 [save_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.StableDiffusionLoraLoaderMixin.save_lora_weights)
- IP Adapter를 로드하기 위한 [load_ip_adapter()](/docs/diffusers/main/ko/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter)

#### encode_prompt[[diffusers.KolorsPipeline.encode_prompt]]

```python
encode_prompt(prompt, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 256)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors.py#L199)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

device : (`torch.device`): torch 디바이스

num_images_per_prompt (`int`) : 프롬프트당 생성할 이미지 수

do_classifier_free_guidance (`bool`) : classifier free guidance를 사용할지 여부

negative_prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 `negative_prompt_embeds`를 전달해야 합니다. 가이던스를 사용하지 않는 경우 무시됩니다(즉, `guidance_scale`이 `1`보다 작은 경우 무시됩니다).

prompt_embeds (`torch.FloatTensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자로부터 텍스트 임베딩이 생성됩니다.

pooled_prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 풀링된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자로부터 풀링된 텍스트 임베딩이 생성됩니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `negative_prompt` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

negative_pooled_prompt_embeds (`torch.Tensor`, *선택*) : 미리 생성된 negative pooled text embeddings입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `negative_prompt` 입력 인수로부터 pooled negative_prompt_embeds가 생성됩니다.

max_sequence_length (`int` 기본값은 256) : `prompt`에 사용할 최대 시퀀스 길이입니다.

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

#### get_guidance_scale_embedding[[diffusers.KolorsPipeline.get_guidance_scale_embedding]]

```python
get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors.py#L590)

**매개변수:**

w (`torch.Tensor`) : 지정된 guidance scale을 사용하여 임베딩 벡터를 생성하고, 이를 통해 timestep 임베딩을 풍부하게 만듭니다.

embedding_dim (`int`, *선택 사항*, 기본값 512) : 생성할 임베딩의 차원.

dtype (`torch.dtype`, *선택 사항*, 기본값 `torch.float32`) : 생성된 임베딩의 데이터 유형입니다.

**반환값:** `torch.Tensor`

`(len(w), embedding_dim)` 형태의 임베딩 벡터.

https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 를 참조하세요.

- 전체
- __호출__

## KolorsImg2ImgPipeline[[diffusers.KolorsImg2ImgPipeline]]

#### diffusers.KolorsImg2ImgPipeline[[diffusers.KolorsImg2ImgPipeline]]

```python
diffusers.KolorsImg2ImgPipeline(vae: AutoencoderKL, text_encoder: ChatGLMModel, tokenizer: ChatGLMTokenizer, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None, force_zeros_for_empty_prompt: bool = False)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors_img2img.py#L142)

**매개변수:**

vae ([AutoencoderKL](/docs/diffusers/main/ko/api/models/autoencoderkl#diffusers.AutoencoderKL)) : 이미지를 잠재 표현으로 인코딩하고 잠재 표현에서 이미지로 디코딩하는 Variational Auto-Encoder (VAE) 모델입니다.

text_encoder (`ChatGLMModel`) : 고정된 텍스트 인코더. Kolors는 [ChatGLM3-6B](https://huggingface.co/THUDM/chatglm3-6b)를 사용합니다.

tokenizer (`ChatGLMTokenizer`) : [ChatGLMTokenizer](https://huggingface.co/THUDM/chatglm3-6b/blob/main/tokenization_chatglm.py) 클래스의 토크나이저.

unet ([UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : 인코딩된 이미지 레이턴트를 디노이즈하기 위한 조건부 U-Net 아키텍처.

scheduler ([SchedulerMixin](/docs/diffusers/main/ko/api/schedulers/overview#diffusers.SchedulerMixin)) : `unet`와 함께 사용되어 인코딩된 이미지 latents의 노이즈를 제거하는 스케줄러입니다. [DDIMScheduler](/docs/diffusers/main/ko/api/schedulers/ddim#diffusers.DDIMScheduler), [LMSDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/lms_discrete#diffusers.LMSDiscreteScheduler), 또는 [PNDMScheduler](/docs/diffusers/main/ko/api/schedulers/pndm#diffusers.PNDMScheduler) 중 하나일 수 있습니다.

force_zeros_for_empty_prompt (`bool`, *선택 사항*, 기본값 `"False"`) : 부정 프롬프트 임베딩을 항상 0으로 설정하도록 강제할지 여부입니다. 또한 `Kwai-Kolors/Kolors-diffusers`의 구성을 참고하세요.

Kolors를 사용한 텍스트-이미지 생성을 위한 Pipeline

이 모델은 [DiffusionPipeline](/docs/diffusers/main/ko/api/pipelines/overview#diffusers.DiffusionPipeline)에서 상속됩니다. 라이브러리가 모든 파이프라인에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

파이프라인은 다음 로딩 메서드도 상속합니다:
- LoRA 가중치를 로드하는 [load_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.load_lora_weights)
- LoRA 가중치를 저장하는 [save_lora_weights()](/docs/diffusers/main/ko/api/loaders/lora#diffusers.loaders.StableDiffusionXLLoraLoaderMixin.save_lora_weights)
- IP Adapter를 로드하기 위한 [load_ip_adapter()](/docs/diffusers/main/ko/api/loaders/ip_adapter#diffusers.loaders.IPAdapterMixin.load_ip_adapter)

#### encode_prompt[[diffusers.KolorsImg2ImgPipeline.encode_prompt]]

```python
encode_prompt(prompt, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 256)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors_img2img.py#L219)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

device : (`torch.device`): torch 디바이스

num_images_per_prompt (`int`) : 프롬프트당 생성할 이미지 수

do_classifier_free_guidance (`bool`) : classifier free guidance를 사용할지 여부

negative_prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 `negative_prompt_embeds`를 전달해야 합니다. 가이던스를 사용하지 않는 경우 무시됩니다(즉, `guidance_scale`이 `1`보다 작은 경우 무시됩니다).

prompt_embeds (`torch.FloatTensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자로부터 텍스트 임베딩이 생성됩니다.

pooled_prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 풀링된 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자로부터 풀링된 텍스트 임베딩이 생성됩니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `negative_prompt` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

negative_pooled_prompt_embeds (`torch.Tensor`, *선택*) : 미리 생성된 negative pooled text embeddings입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, *예를 들어* 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 `negative_prompt` 입력 인수로부터 pooled negative_prompt_embeds가 생성됩니다.

max_sequence_length (`int` 기본값은 256) : `prompt`에 사용할 최대 시퀀스 길이입니다.

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

#### get_guidance_scale_embedding[[diffusers.KolorsImg2ImgPipeline.get_guidance_scale_embedding]]

```python
get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/kolors/pipeline_kolors_img2img.py#L718)

**매개변수:**

w (`torch.Tensor`) : 지정된 guidance scale을 사용하여 임베딩 벡터를 생성하고, 이를 통해 timestep 임베딩을 풍부하게 만듭니다.

embedding_dim (`int`, *선택 사항*, 기본값 512) : 생성할 임베딩의 차원.

dtype (`torch.dtype`, *선택 사항*, 기본값 `torch.float32`) : 생성된 임베딩의 데이터 유형입니다.

**반환값:** `torch.Tensor`

`(len(w), embedding_dim)` 형태의 임베딩 벡터.

https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 를 참조하세요.

- 전체
- __호출__