# Stable unCLIP

  

Stable unCLIP 체크포인트는 CLIP 이미지 임베딩을 조건으로 삼도록 [Stable Diffusion 2.1](./stable_diffusion/stable_diffusion_2) 체크포인트에서 파인튜닝되었습니다. Stable unCLIP은 여전히 텍스트 임베딩을 조건으로 사용합니다. 두 가지 독립적인 조건화가 주어지므로, Stable unCLIP은 텍스트 기반 이미지 변형에 사용할 수 있습니다. unCLIP 사전 분포와 결합하면 완전한 텍스트-이미지 생성에도 사용할 수 있습니다.

해당 논문의 초록은 다음과 같습니다:

*CLIP과 같은 대조적 모델은 의미와 스타일을 모두 포착하는 이미지의 견고한 표현을 학습할 수 있음이 입증되었습니다. 이러한 표현을 이미지 생성에 활용하기 위해, 텍스트 캡션이 주어졌을 때 CLIP 이미지 임베딩을 생성하는 사전 모델(prior)과 이미지 임베딩에 조건부화된 이미지를 생성하는 디코더로 구성된 2단계 모델을 제안합니다. 이미지 표현을 명시적으로 생성하는 것이 사진적 사실성과 캡션 유사성의 손실을 최소화하면서 이미지 다양성을 향상시킨다는 것을 보여줍니다. 이미지 표현에 조건부화된 우리의 디코더는 이미지 표현에 없는 비필수적인 세부 사항을 변화시키면서도 의미와 스타일을 모두 보존하는 이미지의 변형을 생성할 수 있습니다. 또한, CLIP의 결합 임베딩 공간은 제로샷 방식으로 언어 기반 이미지 조작을 가능하게 합니다. 디코더에는 확산 모델을 사용하고, 사전 모델에는 오토레그레시브 모델과 확산 모델 모두를 실험해 보았으며, 후자가 계산적으로 더 효율적이고 더 높은 품질의 샘플을 생성한다는 것을 발견했습니다.*

## 팁

Stable unCLIP은 추론 시 `noise_level`을 입력으로 받아 이미지 임베딩에 추가될 노이즈의 양을 결정합니다. `noise_level`이 높을수록 최종 디노이즈된 이미지의 변이가 커집니다. 기본적으로 이미지 임베딩에 추가적인 노이즈를 추가하지 않습니다(`noise_level = 0`).

### 텍스트-이미지 생성
Stable unCLIP은 KakaoBrain의 오픈소스 DALL-E 2 재현 모델인 [Karlo](https://huggingface.co/kakaobrain/karlo-v1-alpha)의 prior 모델과 파이프라인으로 연결하여 텍스트-이미지 생성에 활용할 수 있습니다:

```python
import torch
from diffusers import UnCLIPScheduler, DDPMScheduler, StableUnCLIPPipeline
from diffusers.models import PriorTransformer
from transformers import CLIPTokenizer, CLIPTextModelWithProjection

prior_model_id = "kakaobrain/karlo-v1-alpha"
data_type = torch.float16
prior = PriorTransformer.from_pretrained(prior_model_id, subfolder="prior", dtype=data_type)

prior_text_model_id = "openai/clip-vit-large-patch14"
prior_tokenizer = CLIPTokenizer.from_pretrained(prior_text_model_id)
prior_text_model = CLIPTextModelWithProjection.from_pretrained(prior_text_model_id, dtype=data_type)
prior_scheduler = UnCLIPScheduler.from_pretrained(prior_model_id, subfolder="prior_scheduler")
prior_scheduler = DDPMScheduler.from_config(prior_scheduler.config)

stable_unclip_model_id = "stabilityai/stable-diffusion-2-1-unclip-small"

pipe = StableUnCLIPPipeline.from_pretrained(
    stable_unclip_model_id,
    dtype=data_type,
    variant="fp16",
    prior_tokenizer=prior_tokenizer,
    prior_text_encoder=prior_text_model,
    prior=prior,
    prior_scheduler=prior_scheduler,
)

pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"
wave_prompt = "dramatic wave, the Oceans roar, Strong wave spiral across the oceans as the waves unfurl into roaring crests; perfect wave form; perfect wave shape; dramatic wave shape; wave shape unbelievable; wave; wave shape spectacular"

image = pipe(prompt=wave_prompt).images[0]
image
```
> [!WARNING]
> 텍스트-이미지 생성에는 CLIP ViT-L/14 임베딩으로 학습되어 Karlo 모델의 사전 학습과 동일한 `stabilityai/stable-diffusion-2-1-unclip-small`을 사용합니다. [stabilityai/stable-diffusion-2-1-unclip](https://hf.co/stabilityai/stable-diffusion-2-1-unclip)은 OpenCLIP ViT-H로 학습되었으므로 사용을 권장하지 않습니다.

### 텍스트 기반 이미지-이미지 변형

```python
from diffusers import StableUnCLIPImg2ImgPipeline
from diffusers.utils import load_image
import torch

pipe = StableUnCLIPImg2ImgPipeline.from_pretrained(
    "stabilityai/stable-diffusion-2-1-unclip", dtype=torch.float16, variation="fp16"
)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/stable_unclip/tarsila_do_amaral.png"
init_image = load_image(url)

images = pipe(init_image).images
images[0].save("variation_image.png")
```

선택적으로 `pipe`에 프롬프트를 전달할 수도 있습니다. 예를 들어:

```python
prompt = "A fantasy landscape, trending on artstation"

image = pipe(init_image, prompt=prompt).images[0]
image
```

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

## StableUnCLIPPipeline[[diffusers.StableUnCLIPPipeline]]

#### diffusers.StableUnCLIPPipeline[[diffusers.StableUnCLIPPipeline]]

```python
diffusers.StableUnCLIPPipeline(prior_tokenizer: CLIPTokenizer, prior_text_encoder: CLIPTextModelWithProjection, prior: PriorTransformer, prior_scheduler: KarrasDiffusionSchedulers, image_normalizer: StableUnCLIPImageNormalizer, image_noising_scheduler: KarrasDiffusionSchedulers, tokenizer: CLIPTokenizer, text_encoder: CLIPTextModel, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, vae: AutoencoderKL)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip.py#L70)

**매개변수:**

prior_tokenizer (`CLIPTokenizer`) : A `CLIPTokenizer`.

prior_text_encoder (`CLIPTextModelWithProjection`) : 고정된 `CLIPTextModelWithProjection` 텍스트 인코더.

prior ([PriorTransformer](/docs/diffusers/main/ko/api/models/prior_transformer#diffusers.PriorTransformer)) : 텍스트 임베딩에서 이미지 임베딩을 근사하기 위한 unCLIP의 표준 사전 분포 모델.

prior_scheduler (`KarrasDiffusionSchedulers`) : 사전 노이즈 제거 과정에서 사용되는 스케줄러.

image_normalizer (`StableUnCLIPImageNormalizer`) : 노이즈가 적용되기 전에 예측된 이미지 임베딩을 정규화하고, 노이즈가 적용된 후 이미지 임베딩을 역정규화하는 데 사용됩니다.

image_noising_scheduler (`KarrasDiffusionSchedulers`) : 예측된 이미지 임베딩에 노이즈를 추가하기 위한 노이즈 스케줄입니다. 추가할 노이즈의 양은 `noise_level`에 의해 결정됩니다.

tokenizer (`CLIPTokenizer`) : A `CLIPTokenizer`.

text_encoder (`CLIPTextModel`) : 고정된 `CLIPTextModel` 텍스트 인코더.

unet ([UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : 인코딩된 이미지 라텐트에서 노이즈를 제거하기 위한 [UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

scheduler (`KarrasDiffusionSchedulers`) : `unet`와 함께 사용하여 인코딩된 이미지 latents의 노이즈를 제거하는 데 사용되는 스케줄러입니다.

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

stable unCLIP을 사용한 텍스트-이미지 생성을 위한 Pipeline

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

파이프라인은 다음 로딩 메서드도 상속합니다:
- 텍스트 인버전 임베딩을 로드하는 [load_textual_inversion()](/docs/diffusers/main/ko/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion)
- 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)

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

```python
__call__(prompt: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 20, guidance_scale: float = 10.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int = 1, cross_attention_kwargs: dict[str, typing.Any] | None = None, noise_level: int = 0, prior_num_inference_steps: int = 25, prior_guidance_scale: float = 4.0, prior_latents: typing.Optional[torch.Tensor] = None, clip_skip: int | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip.py#L645)

**매개변수:**

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

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

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

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

guidance_scale (`float`, *선택 사항*, 기본값 10.0) : guidance scale 값이 높을수록 모델은 이미지 품질이 낮아지는 대신 텍스트 `prompt`와 밀접하게 연결된 이미지를 생성하도록 유도됩니다. `guidance_scale > 1`일 때 guidance scale이 활성화됩니다.

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

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

eta (`float`, *선택 사항*, 기본값 0.0) : [DDIM](https://huggingface.co/papers/2010.02502) 논문에서 정의한 파라미터 eta (η)에 해당합니다. [DDIMScheduler](/docs/diffusers/main/ko/api/schedulers/ddim#diffusers.DDIMScheduler)에만 적용되며, 다른 스케줄러에서는 무시됩니다.

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

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

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

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

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

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 [ImagePipelineOutput](/docs/diffusers/main/ko/api/pipelines/consistency_models#diffusers.ImagePipelineOutput)을 반환할지 여부.

callback (`Callable`, *선택 사항*) : 추론 중 `callback_steps` 단계마다 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: `callback(step: int, timestep: int, latents: torch.Tensor)`.

callback_steps (`int`, *선택 사항*, 기본값 1) : `callback` 함수가 호출되는 주기입니다. 지정하지 않으면 모든 단계에서 콜백이 호출됩니다.

cross_attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

noise_level (`int`, *선택 사항*, 기본값 `0`) : 이미지 임베딩에 추가할 노이즈의 양입니다. `noise_level`이 높을수록 최종 노이즈 제거된 이미지의 분산이 증가합니다. 자세한 내용은 [StableUnCLIPPipeline.noise_image_embeddings()](/docs/diffusers/main/ko/api/pipelines/stable_unclip#diffusers.StableUnCLIPPipeline.noise_image_embeddings)을 참조하세요.

prior_num_inference_steps (`int`, *선택 사항*, 기본값 25) : 사전(denoising) 과정의 노이즈 제거 단계 수입니다. 노이즈 제거 단계가 많을수록 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성할 수 있습니다.

prior_guidance_scale (`float`, *선택 사항*, 기본값 4.0) : guidance scale 값이 높을수록 모델은 이미지 품질이 낮아지는 대신 텍스트 `prompt`와 밀접하게 연결된 이미지를 생성하도록 유도됩니다. `guidance_scale > 1`일 때 guidance scale이 활성화됩니다.

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

clip_skip (`int`, *선택 사항*) : 프롬프트 임베딩을 계산할 때 CLIP에서 건너뛸 레이어 수. 값이 1이면 최종 레이어 바로 이전 레이어의 출력을 프롬프트 임베딩 계산에 사용합니다.

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

`return_dict`가 True이면 `~ pipeline_utils.ImagePipelineOutput`, 그렇지 않으면 `tuple`입니다. tuple을 반환하는 경우 첫 번째 요소는 생성된 이미지의 목록입니다.

생성을 위한 pipeline의 호출 함수.

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

>>> pipe = StableUnCLIPPipeline.from_pretrained(
...     "fusing/stable-unclip-2-1-l", torch_dtype=torch.float16
... )  # TODO update model path
>>> pipe = pipe.to("cuda")

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> images = pipe(prompt).images
>>> images[0].save("astronaut_horse.png")
```

#### enable_attention_slicing[[diffusers.StableUnCLIPPipeline.enable_attention_slicing]]

```python
enable_attention_slicing(slice_size: str | int = 'auto')
```

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

**매개변수:**

slice_size (`str` 또는 `int`, *선택 사항*, 기본값 `"auto"`) : `"auto"`인 경우 attention heads에 전달되는 입력을 절반으로 줄여 attention을 두 단계로 계산합니다. `"max"`인 경우 한 번에 하나의 슬라이스만 실행하여 최대의 메모리를 절약합니다. 숫자가 제공되면 `attention_head_dim // slice_size`만큼의 슬라이스를 사용합니다. 이 경우 `attention_head_dim`은 `slice_size`의 배수여야 합니다.

슬라이스된 어텐션 계산을 활성화합니다. 이 옵션이 활성화되면 어텐션 모듈은 입력 텐서를 슬라이스로 분할하여 여러 단계에 걸쳐 어텐션을 계산합니다. 어텐션 헤드 하나가 넘는 경우, 각 헤드를 순차적으로 계산합니다. 이는 속도가 약간 감소하는 대신 메모리를 절약하는 데 유용합니다.

> [!WARNING] > ⚠️ 이미 `scaled_dot_product_attention`(SDPA)를 사용 중이라면 attention slicing을 활성화하지 마세요
from PyTorch > 2.0 or xFormers. 이러한 attention 계산은 이미 메모리 효율성이 매우 높아 이 기능을 활성화할 필요가 없습니다. SDPA 또는 xFormers와 함께 attention slicing을 활성화하면 심각한 성능 저하가 발생할 수 있습니다!

예:

```py
>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]
```

#### disable_attention_slicing[[diffusers.StableUnCLIPPipeline.disable_attention_slicing]]

```python
disable_attention_slicing()
```

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

슬라이스된 어텐션 계산 기능을 비활성화합니다. `enable_attention_slicing`가 이전에 호출된 경우, 어텐션은 한 번에 계산됩니다.

#### enable_xformers_memory_efficient_attention[[diffusers.StableUnCLIPPipeline.enable_xformers_memory_efficient_attention]]

```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```

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

**매개변수:**

attention_op (`Callable`, *선택 사항*) : xFormers의 [`memory_efficient_attention()`](https://facebookresearch.github.io/xformers/components/ops.html#xformers.ops.memory_efficient_attention) 함수에 `op` 인수로 사용될 때 기본 `None` 연산자를 재정의합니다.

[xFormers](https://facebookresearch.github.io/xformers/)에서 메모리 효율적인 어텐션을 활성화합니다. 이 옵션을 활성화하면 추론 시 GPU 메모리 사용량이 감소하고 속도가 향상될 수 있습니다. 학습 시 속도 향상은 보장되지 않습니다.

> [!WARNING] > ⚠️ memory efficient attention과 sliced attention이 모두 활성화된 경우, memory efficient
attention은 > 우선순위를 가집니다.

예:

```py
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)
```

#### disable_xformers_memory_efficient_attention[[diffusers.StableUnCLIPPipeline.disable_xformers_memory_efficient_attention]]

```python
disable_xformers_memory_efficient_attention()
```

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

[xFormers](https://facebookresearch.github.io/xformers/)에서 메모리 효율적 어텐션을 비활성화합니다.

#### encode_prompt[[diffusers.StableUnCLIPPipeline.encode_prompt]]

```python
encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip.py#L297)

**매개변수:**

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

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

lora_scale (`float`, *선택 사항*) : LoRA 레이어가 로드된 경우 텍스트 인코더의 모든 LoRA 레이어에 적용될 LoRA 스케일입니다.

clip_skip (`int`, *선택 사항*) : 프롬프트 임베딩을 계산할 때 CLIP에서 건너뛸 레이어 수. 값이 1이면 최종 레이어 바로 이전 레이어의 출력을 프롬프트 임베딩 계산에 사용합니다.

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

#### noise_image_embeddings[[diffusers.StableUnCLIPPipeline.noise_image_embeddings]]

```python
noise_image_embeddings(image_embeds: Tensor, noise_level: int, noise: typing.Optional[torch.Tensor] = None, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip.py#L599)

이미지 임베딩에 노이즈를 추가합니다. 노이즈의 양은 `noise_level` 입력으로 제어됩니다. `noise_level`이 높을수록 최종 노이즈 제거된 이미지의 분산이 커집니다.

노이즈는 두 가지 방식으로 적용됩니다:
1. 노이즈 스케줄이 임베딩에 직접 적용됩니다.
2. sinusoidal time embeddings 벡터가 출력에 추가됩니다.

두 경우 모두 노이즈 양은 동일한 `noise_level`로 제어됩니다.

노이즈가 적용되기 전에 임베딩이 정규화되고, 노이즈가 적용된 후에는 비정규화됩니다.

## StableUnCLIPImg2ImgPipeline[[diffusers.StableUnCLIPImg2ImgPipeline]]

#### diffusers.StableUnCLIPImg2ImgPipeline[[diffusers.StableUnCLIPImg2ImgPipeline]]

```python
diffusers.StableUnCLIPImg2ImgPipeline(feature_extractor: CLIPImageProcessorPil, image_encoder: CLIPVisionModelWithProjection, image_normalizer: StableUnCLIPImageNormalizer, image_noising_scheduler: KarrasDiffusionSchedulers, tokenizer: CLIPTokenizer, text_encoder: CLIPTextModel, unet: UNet2DConditionModel, scheduler: KarrasDiffusionSchedulers, vae: AutoencoderKL)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip_img2img.py#L81)

**매개변수:**

feature_extractor (`CLIPImageProcessor`) : 인코딩 전 이미지 전처리를 위한 특징 추출기

image_encoder (`CLIPVisionModelWithProjection`) : 이미지를 인코딩하는 CLIP 비전 모델.

image_normalizer (`StableUnCLIPImageNormalizer`) : 노이즈가 적용되기 전에 예측된 이미지 임베딩을 정규화하고, 노이즈가 적용된 후 이미지 임베딩을 역정규화하는 데 사용됩니다.

image_noising_scheduler (`KarrasDiffusionSchedulers`) : 예측된 이미지 임베딩에 노이즈를 추가하기 위한 노이즈 스케줄입니다. 추가할 노이즈의 양은 `noise_level`에 의해 결정됩니다.

tokenizer (`~transformers.CLIPTokenizer`) : A [`~transformers.CLIPTokenizer`)].

text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTextModel)) : 고정된 [CLIPTextModel](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTextModel) 텍스트 인코더.

unet ([UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) : 인코딩된 이미지 라텐트에서 노이즈를 제거하기 위한 [UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

scheduler (`KarrasDiffusionSchedulers`) : `unet`와 함께 사용하여 인코딩된 이미지 latents의 노이즈를 제거하는 데 사용되는 스케줄러입니다.

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

stable unCLIP을 사용한 텍스트 기반 이미지-이미지 생성을 위한 Pipeline

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

파이프라인은 다음 로딩 메서드도 상속합니다:
- 텍스트 인버전 임베딩을 로드하는 [load_textual_inversion()](/docs/diffusers/main/ko/api/loaders/textual_inversion#diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion)
- 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)

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

```python
__call__(image: typing.Union[torch.Tensor, PIL.Image.Image] = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 20, guidance_scale: float = 10, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int = 1, cross_attention_kwargs: dict[str, typing.Any] | None = None, noise_level: int = 0, image_embeds: typing.Optional[torch.Tensor] = None, clip_skip: int | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip_img2img.py#L624)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 이미지 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`가 사용되거나 prompt가 `""`로 초기화됩니다.

image (`torch.Tensor` 또는 `PIL.Image.Image`) : `Image` 또는 이미지 배치を表すテンソル. 이미지는 `unet`의 조건으로 사용되는 CLIP 임베딩으로 인코딩됩니다. 이 이미지는 표준 Stable Diffusion 텍스트 기반 이미지 변형 프로세스에서와 달리 `vae`로 인코딩되어 디노이징 과정의 잠재 변수(latents)로 사용되지 _않습니다_.

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

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

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

guidance_scale (`float`, *선택 사항*, 기본값 10.0) : guidance scale 값이 높을수록 모델은 이미지 품질이 낮아지는 대신 텍스트 `prompt`와 밀접하게 연결된 이미지를 생성하도록 유도됩니다. `guidance_scale > 1`일 때 guidance scale이 활성화됩니다.

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

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

eta (`float`, *선택 사항*, 기본값 0.0) : [DDIM](https://huggingface.co/papers/2010.02502) 논문에서 정의한 파라미터 eta (η)에 해당합니다. [DDIMScheduler](/docs/diffusers/main/ko/api/schedulers/ddim#diffusers.DDIMScheduler)에만 적용되며, 다른 스케줄러에서는 무시됩니다.

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

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

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

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

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

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 [ImagePipelineOutput](/docs/diffusers/main/ko/api/pipelines/consistency_models#diffusers.ImagePipelineOutput)을 반환할지 여부.

callback (`Callable`, *선택 사항*) : 추론 중 `callback_steps` 단계마다 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다: `callback(step: int, timestep: int, latents: torch.Tensor)`.

callback_steps (`int`, *선택 사항*, 기본값 1) : `callback` 함수가 호출되는 주기입니다. 지정하지 않으면 모든 단계에서 콜백이 호출됩니다.

cross_attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [`self.processor`](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

noise_level (`int`, *선택 사항*, 기본값 `0`) : 이미지 임베딩에 추가할 노이즈의 양입니다. `noise_level`이 높을수록 최종 노이즈 제거된 이미지의 분산이 증가합니다. 자세한 내용은 [StableUnCLIPPipeline.noise_image_embeddings()](/docs/diffusers/main/ko/api/pipelines/stable_unclip#diffusers.StableUnCLIPPipeline.noise_image_embeddings)을 참조하세요.

image_embeds (`torch.Tensor`, *선택 사항*) : `unet`에 조건으로 사용할 사전 생성된 CLIP 임베딩입니다. 이 잠재 변수는 노이즈 제거 과정에서 사용되지 않습니다. 사전 생성된 잠재 변수를 제공하려면 `__call__`에 `latents`로 전달하세요.

clip_skip (`int`, *선택 사항*) : 프롬프트 임베딩을 계산할 때 CLIP에서 건너뛸 레이어 수. 값이 1이면 최종 레이어 바로 이전 레이어의 출력을 프롬프트 임베딩 계산에 사용합니다.

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

`return_dict`가 True이면 `~ pipeline_utils.ImagePipelineOutput`, 그렇지 않으면 `tuple`입니다. tuple을 반환하는 경우 첫 번째 요소는 생성된 이미지의 목록입니다.

생성을 위한 pipeline의 호출 함수.

예:
```py
>>> import requests
>>> import torch
>>> from PIL import Image
>>> from io import BytesIO

>>> from diffusers import StableUnCLIPImg2ImgPipeline

>>> pipe = StableUnCLIPImg2ImgPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-2-1-unclip-small", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"

>>> response = requests.get(url)
>>> init_image = Image.open(BytesIO(response.content)).convert("RGB")
>>> init_image = init_image.resize((768, 512))

>>> prompt = "A fantasy landscape, trending on artstation"

>>> images = pipe(init_image, prompt).images
>>> images[0].save("fantasy_landscape.png")
```

#### enable_attention_slicing[[diffusers.StableUnCLIPImg2ImgPipeline.enable_attention_slicing]]

```python
enable_attention_slicing(slice_size: str | int = 'auto')
```

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

**매개변수:**

slice_size (`str` 또는 `int`, *선택 사항*, 기본값 `"auto"`) : `"auto"`인 경우 attention heads에 전달되는 입력을 절반으로 줄여 attention을 두 단계로 계산합니다. `"max"`인 경우 한 번에 하나의 슬라이스만 실행하여 최대의 메모리를 절약합니다. 숫자가 제공되면 `attention_head_dim // slice_size`만큼의 슬라이스를 사용합니다. 이 경우 `attention_head_dim`은 `slice_size`의 배수여야 합니다.

슬라이스된 어텐션 계산을 활성화합니다. 이 옵션이 활성화되면 어텐션 모듈은 입력 텐서를 슬라이스로 분할하여 여러 단계에 걸쳐 어텐션을 계산합니다. 어텐션 헤드 하나가 넘는 경우, 각 헤드를 순차적으로 계산합니다. 이는 속도가 약간 감소하는 대신 메모리를 절약하는 데 유용합니다.

> [!WARNING] > ⚠️ 이미 `scaled_dot_product_attention`(SDPA)를 사용 중이라면 attention slicing을 활성화하지 마세요
from PyTorch > 2.0 or xFormers. 이러한 attention 계산은 이미 메모리 효율성이 매우 높아 이 기능을 활성화할 필요가 없습니다. SDPA 또는 xFormers와 함께 attention slicing을 활성화하면 심각한 성능 저하가 발생할 수 있습니다!

예:

```py
>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]
```

#### disable_attention_slicing[[diffusers.StableUnCLIPImg2ImgPipeline.disable_attention_slicing]]

```python
disable_attention_slicing()
```

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

슬라이스된 어텐션 계산 기능을 비활성화합니다. `enable_attention_slicing`가 이전에 호출된 경우, 어텐션은 한 번에 계산됩니다.

#### enable_xformers_memory_efficient_attention[[diffusers.StableUnCLIPImg2ImgPipeline.enable_xformers_memory_efficient_attention]]

```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```

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

**매개변수:**

attention_op (`Callable`, *선택 사항*) : xFormers의 [`memory_efficient_attention()`](https://facebookresearch.github.io/xformers/components/ops.html#xformers.ops.memory_efficient_attention) 함수에 `op` 인수로 사용될 때 기본 `None` 연산자를 재정의합니다.

[xFormers](https://facebookresearch.github.io/xformers/)에서 메모리 효율적인 어텐션을 활성화합니다. 이 옵션을 활성화하면 추론 시 GPU 메모리 사용량이 감소하고 속도가 향상될 수 있습니다. 학습 시 속도 향상은 보장되지 않습니다.

> [!WARNING] > ⚠️ memory efficient attention과 sliced attention이 모두 활성화된 경우, memory efficient
attention은 > 우선순위를 가집니다.

예:

```py
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)
```

#### disable_xformers_memory_efficient_attention[[diffusers.StableUnCLIPImg2ImgPipeline.disable_xformers_memory_efficient_attention]]

```python
disable_xformers_memory_efficient_attention()
```

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

[xFormers](https://facebookresearch.github.io/xformers/)에서 메모리 효율적 어텐션을 비활성화합니다.

#### encode_prompt[[diffusers.StableUnCLIPImg2ImgPipeline.encode_prompt]]

```python
encode_prompt(prompt, device, num_images_per_prompt, do_classifier_free_guidance, negative_prompt = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip_img2img.py#L259)

**매개변수:**

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

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

lora_scale (`float`, *선택 사항*) : LoRA 레이어가 로드된 경우 텍스트 인코더의 모든 LoRA 레이어에 적용될 LoRA 스케일입니다.

clip_skip (`int`, *선택 사항*) : 프롬프트 임베딩을 계산할 때 CLIP에서 건너뛸 레이어 수. 값이 1이면 최종 레이어 바로 이전 레이어의 출력을 프롬프트 임베딩 계산에 사용합니다.

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

#### noise_image_embeddings[[diffusers.StableUnCLIPImg2ImgPipeline.noise_image_embeddings]]

```python
noise_image_embeddings(image_embeds: Tensor, noise_level: int, noise: typing.Optional[torch.Tensor] = None, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_diffusion/pipeline_stable_unclip_img2img.py#L578)

이미지 임베딩에 노이즈를 추가합니다. 노이즈의 양은 `noise_level` 입력으로 제어됩니다. `noise_level`이 높을수록 최종 노이즈 제거된 이미지의 분산이 커집니다.

노이즈는 두 가지 방식으로 적용됩니다:
1. 노이즈 스케줄이 임베딩에 직접 적용됩니다.
2. sinusoidal time embeddings 벡터가 출력에 추가됩니다.

두 경우 모두 노이즈 양은 동일한 `noise_level`로 제어됩니다.

노이즈가 적용되기 전에 임베딩이 정규화되고, 노이즈가 적용된 후에는 비정규화됩니다.

## ImagePipelineOutput[[diffusers.ImagePipelineOutput]]

#### diffusers.ImagePipelineOutput[[diffusers.ImagePipelineOutput]]

```python
diffusers.ImagePipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

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

**매개변수:**

images (`List[PIL.Image.Image]` 또는 `np.ndarray`) : `batch_size` 길이의 노이즈 제거된 PIL 이미지 목록 또는 `(batch_size, height, width, num_channels)` 모양의 NumPy 배열.

이미지 파이프라인의 출력 클래스입니다.