# Kandinsky 3

  

Kandinsky 3은 [Vladimir Arkhipkin](https://github.com/oriBetelgeuse), [Anastasia Maltseva](https://github.com/NastyaMittseva), [Igor Pavlov](https://github.com/boomb0om), [Andrei Filatov](https://github.com/anvilarth), [Arseniy Shakhmatov](https://github.com/cene555), [Andrey Kuznetsov](https://github.com/kuznetsoffandrey), [Denis Dimitrov](https://github.com/denndimitrov), [Zein Shaheen](https://github.com/zeinsh)에 의해 개발되었습니다.

GitHub 페이지의 설명:

*Kandinsky 3.0는 Kandinsky2-x 모델 계열을 기반으로 구축된 오픈소스 텍스트-이미지 확산 모델입니다. 이전 버전과 비교하여 텍스트 인코더와 Diffusion U-Net 모델의 크기를 각각 늘림으로써 모델의 텍스트 이해 능력과 시각적 품질을 향상시켰습니다.*

아키텍처에는 3개의 주요 구성 요소가 포함되어 있습니다:
1. T5 아키텍처 기반의 인코더-디코더 모델인 [FLAN-UL2](https://huggingface.co/google/flan-ul2)
2. BigGAN-deep 블록을 갖춘 새로운 U-Net 아키텍처는 매개변수 수를 동일하게 유지하면서 깊이를 두 배로 늘립니다.
3. Sber-MoVQGAN은 이미지 복원 분야에서 우수한 결과를 입증한 디코더입니다.

원본 코드베이스는 [ai-forever/Kandinsky-3](https://github.com/ai-forever/Kandinsky-3)에서 찾을 수 있습니다.

> [!TIP]
> Hub의 [Kandinsky Community](https://huggingface.co/kandinsky-community) 조직에서 텍스트-이미지, 이미지-이미지, 인페인팅과 같은 작업에 대한 공식 모델 체크포인트를 확인해 보세요.

> [!TIP]
> 스케줄러의 [가이드](../../using-diffusers/schedulers)를 확인하여 스케줄러의 속도와 품질 사이의 트레이드오프를 탐색하는 방법을 배우고, [파이프라인 간 구성 요소 재사용](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) 섹션을 확인하여 동일한 구성 요소를 여러 파이프라인에 효율적으로 로드하는 방법을 배워보세요.

## Kandinsky3Pipeline[[diffusers.Kandinsky3Pipeline]]

#### diffusers.Kandinsky3Pipeline[[diffusers.Kandinsky3Pipeline]]

```python
diffusers.Kandinsky3Pipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, unet: Kandinsky3UNet, scheduler: DDPMScheduler, movq: VQModel)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3.py#L59)

#### __호출__[[diffusers.Kandinsky3Pipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, num_inference_steps: int = 25, guidance_scale: float = 3.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, height: int | None = 1024, width: int | None = 1024, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, negative_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, latents = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3.py#L334)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`를 대신 전달해야 합니다.

num_inference_steps (`int`, *선택 사항*, 기본값 25) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

guidance_scale (`float`, *선택 사항*, 기본값 3.0) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다.

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

num_images_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 이미지의 수.

height (`int`, *선택 사항*, 기본값은 self.unet.config.sample_size) : 생성된 이미지의 픽셀 단위 높이.

width (`int`, *선택 사항*, 기본값은 self.unet.config.sample_size) : 생성된 이미지의 픽셀 단위 너비.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

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

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

attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 attention mask입니다. `prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

negative_attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 negative attention mask입니다. `negative_prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.stable_diffusion.IFPipelineOutput`를 반환할지 여부.

latents (`torch.Tensor`, *선택 사항*) : 이미지 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

callback_on_step_end (`Callable`, *선택 사항*) : 추론 중 각 디노이징 단계의 끝에서 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs`에는 `callback_on_step_end_tensor_inputs`로 지정된 모든 텐서 목록이 포함됩니다.

callback_on_step_end_tensor_inputs (`list`, *선택 사항*) : `callback_on_step_end` 함수의 텐서 입력 목록입니다. 목록에 지정된 텐서는 `callback_kwargs` 인수로 전달됩니다. 파이프라인 클래스의 `._callback_tensor_inputs` 속성에 나열된 변수만 포함할 수 있습니다.

**반환값:** [ImagePipelineOutput](/docs/diffusers/v0.43.0/ko/api/pipelines/consistency_models#diffusers.ImagePipelineOutput) 또는 `tuple`

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> from diffusers import AutoPipelineForText2Image
>>> import torch

>>> pipe = AutoPipelineForText2Image.from_pretrained(
...     "kandinsky-community/kandinsky-3", variant="fp16", torch_dtype=torch.float16
... )
>>> pipe.enable_model_cpu_offload()

>>> prompt = "A photograph of the inside of a subway train. There are raccoons sitting on the seats. One of them is reading a newspaper. The window shows the city in the background."

>>> generator = torch.Generator(device="cpu").manual_seed(0)
>>> image = pipe(prompt, num_inference_steps=25, generator=generator).images[0]
```

#### encode_prompt[[diffusers.Kandinsky3Pipeline.encode_prompt]]

```python
encode_prompt(prompt, do_classifier_free_guidance = True, num_images_per_prompt = 1, device = None, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, _cut_context = False, attention_mask: typing.Optional[torch.Tensor] = None, negative_attention_mask: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3.py#L91)

**매개변수:**

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

device : (`torch.device`, *선택 사항*): 생성된 임베딩을 배치할 torch device

num_images_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 이미지 수

do_classifier_free_guidance (`bool`, *선택 사항*, 기본값 `True`) : classifier free guidance를 사용할지 여부

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

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

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

attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 attention mask입니다. `prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

negative_attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 negative attention mask입니다. `negative_prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

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

## Kandinsky3Img2ImgPipeline[[diffusers.Kandinsky3Img2ImgPipeline]]

#### diffusers.Kandinsky3Img2ImgPipeline[[diffusers.Kandinsky3Img2ImgPipeline]]

```python
diffusers.Kandinsky3Img2ImgPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, unet: Kandinsky3UNet, scheduler: DDPMScheduler, movq: VQModel)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3_img2img.py#L56)

#### __호출__[[diffusers.Kandinsky3Img2ImgPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, image: typing.Union[torch.Tensor, list[torch.Tensor], PIL.Image.Image, list[PIL.Image.Image]] = None, strength: float = 0.3, num_inference_steps: int = 25, guidance_scale: float = 3.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, negative_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3_img2img.py#L400)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`를 대신 전달해야 합니다.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, 또는 `list[np.ndarray]`) : `Image` 또는 이미지 배치 텐서로, 프로세스의 시작점으로 사용됩니다.

strength (`float`, *선택 사항*, 기본값 0.8) : 참조 `image`를 변환할 정도를 나타냅니다. 0과 1 사이여야 합니다. `image`는 시작점으로 사용되며, `strength` 값이 높을수록 더 많은 노이즈가 추가됩니다. 디노이징 단계의 수는 초기에 추가된 노이즈의 양에 따라 결정됩니다. `strength`가 1이면 추가되는 노이즈가 최대가 되며, `num_inference_steps`에 지정된 전체 반복 횟수만큼 디노이징 프로세스가 실행됩니다. 1이라는 값은 사실상 `image`를 무시하는 것과 같습니다.

num_inference_steps (`int`, *선택 사항*, 기본값 50) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

guidance_scale (`float`, *선택 사항*, 기본값 3.0) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다.

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

num_images_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 이미지의 수.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

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

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

attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 attention mask입니다. `prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

negative_attention_mask (`torch.Tensor`, *선택 사항*) : 미리 생성된 negative attention mask입니다. `negative_prompt_embeds`를 직접 전달하는 경우 반드시 제공해야 합니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.stable_diffusion.IFPipelineOutput`를 반환할지 여부.

callback_on_step_end (`Callable`, *선택 사항*) : 추론 중 각 디노이징 단계의 끝에서 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs`에는 `callback_on_step_end_tensor_inputs`로 지정된 모든 텐서 목록이 포함됩니다.

callback_on_step_end_tensor_inputs (`list`, *선택 사항*) : `callback_on_step_end` 함수의 텐서 입력 목록입니다. 목록에 지정된 텐서는 `callback_kwargs` 인수로 전달됩니다. 파이프라인 클래스의 `._callback_tensor_inputs` 속성에 나열된 변수만 포함할 수 있습니다.

**반환값:** [ImagePipelineOutput](/docs/diffusers/v0.43.0/ko/api/pipelines/consistency_models#diffusers.ImagePipelineOutput) 또는 `tuple`

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> from diffusers import AutoPipelineForImage2Image
>>> from diffusers.utils import load_image
>>> import torch

>>> pipe = AutoPipelineForImage2Image.from_pretrained(
...     "kandinsky-community/kandinsky-3", variant="fp16", torch_dtype=torch.float16
... )
>>> pipe.enable_model_cpu_offload()

>>> prompt = "A painting of the inside of a subway train with tiny raccoons."
>>> image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky3/t2i.png"
... )

>>> generator = torch.Generator(device="cpu").manual_seed(0)
>>> image = pipe(prompt, image=image, strength=0.75, num_inference_steps=25, generator=generator).images[0]
```

#### encode_prompt[[diffusers.Kandinsky3Img2ImgPipeline.encode_prompt]]

```python
encode_prompt(prompt, do_classifier_free_guidance = True, num_images_per_prompt = 1, device = None, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, _cut_context = True, attention_mask: typing.Optional[torch.Tensor] = None, negative_attention_mask: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/kandinsky3/pipeline_kandinsky3_img2img.py#L106)

**매개변수:**

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

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

device: (`torch.device`, *선택 사항*): 생성된 임베딩을 배치할 torch 디바이스 num_images_per_prompt (`int`, *선택 사항*, 기본값 1): 프롬프트당 생성할 이미지 수 do_classifier_free_guidance (`bool`, *선택 사항*, 기본값 `True`): classifier free guidance를 사용할지 여부 negative_prompt (`str` 또는 `list[str]`, *선택 사항*): 이미지 생성을 유도하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 `negative_prompt_embeds`를 전달해야 합니다. 정의되지 않은 경우 대신 `negative_prompt_embeds`를 전달해야 합니다. guidance를 사용하지 않는 경우 무시됩니다(즉, `guidance_scale`이 `1`보다 작은 경우 무시됨). prompt_embeds (`torch.Tensor`, *선택 사항*): 사전 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다. negative_prompt_embeds (`torch.Tensor`, *선택 사항*): 사전 생성된 부정 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 negative_prompt_embeds가 `negative_prompt` 입력 인자에서 생성됩니다. attention_mask (`torch.Tensor`, *선택 사항*): 사전 생성된 어텐션 마스크입니다. `prompt_embeds`를 직접 전달하는 경우 제공해야 합니다. negative_attention_mask (`torch.Tensor`, *선택 사항*): 사전 생성된 부정 어텐션 마스크입니다. `negative_prompt_embeds`를 직접 전달하는 경우 제공해야 합니다.