# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721)는 이미지로 diffusion model을 프롬프팅할 수 있게 해주는 경량 어댑터입니다. 이 방법은 이미지와 텍스트 특징의 cross-attention 레이어를 분리합니다. 이미지 특징은 이미지 인코더에서 생성됩니다.

> [!TIP]
> [IP-Adapter](../../using-diffusers/ip_adapter) 가이드에서 IP-Adapter 체크포인트와 이미지를 로드하고 사용하는 방법을 배워보세요.

## IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

#### diffusers.loaders.IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

```python
diffusers.loaders.IPAdapterMixin()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L55)

IP Adapter를 처리하기 위한 Mixin입니다.

#### load_ip_adapter[[diffusers.loaders.IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | list[str] | dict[str, torch.Tensor], subfolder: str | list[str], weight_name: str | list[str], image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L58)

**매개변수:**

pretrained_model_name_or_path_or_dict (`str` 또는 `list[str]` 또는 `os.PathLike` 또는 `list[os.PathLike]` 또는 `dict` 또는 `list[dict]`) : 다음 중 하나일 수 있습니다:  - Hub에 호스팅된 사전 학습 모델의 *model id* 문자열 (예: `google/ddpm-celebahq-256`). - [ModelMixin.save_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.save_pretrained)로 저장된 모델 가중치가 포함된 *디렉터리* 경로 (예: `./my_model_directory`). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` 또는 `list[str]`) : Hub 또는 로컬의 더 큰 모델 저장소 내에서 모델 파일의 서브폴더 위치입니다. 리스트가 전달되면 `weight_name`과 동일한 길이를 가져야 합니다.

weight_name (`str` 또는 `list[str]`) : 로드할 가중치 파일의 이름입니다. 리스트가 전달되면 `subfolder`와 동일한 길이를 가져야 합니다.

image_encoder_folder (`str`, *선택 사항*, 기본값은 `image_encoder`) : Hub 또는 로컬의 더 큰 모델 저장소 내에서 이미지 인코더의 서브폴더 위치입니다. 이미지 인코더를 로드하지 않으려면 `None`을 전달하세요. 이미지 인코더가 `subfolder` 안의 폴더에 있는 경우, 이미지 인코더 가중치를 포함하는 폴더의 이름만 전달하면 됩니다. 예를 들어 `image_encoder_folder="image_encoder"`입니다. 이미지 인코더가 `subfolder`가 아닌 다른 폴더에 있는 경우, 이미지 인코더 가중치를 포함하는 폴더의 경로를 전달해야 합니다. 예를 들어 `image_encoder_folder="different_subfolder/image_encoder"`입니다.

cache_dir (`str | os.PathLike`, *선택 사항*) : 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성이 캐시되는 디렉터리의 경로입니다.

force_download (`bool`, *선택 사항*, 기본값 `False`) : 캐시된 버전이 존재하더라도 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부.

proxies (`dict[str, str]`, *선택 사항*) : 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`와 같습니다. 각 요청에 프록시가 사용됩니다.

local_files_only (`bool`, *선택 사항*, 기본값 `False`) : 로컬 모델 가중치와 구성 파일만 로드할지 여부를 지정합니다. `True`로 설정하면 Hub에서 모델을 다운로드하지 않습니다.

token (`str` 또는 *bool*, *선택 사항*) : 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. `True`인 경우, `diffusers-cli login`에서 생성된 토큰(`~/.huggingface`에 저장됨)이 사용됩니다.

revision (`str`, *선택 사항*, 기본값 `"main"`) : 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다.

low_cpu_mem_usage (`bool`, *선택 사항*, torch 버전이 1.9.0 이상이면 기본값은 `True`, 그 외에는 `False`) : 가중치를 초기화하지 않고 사전 학습된 가중치만 로드하여 모델 로딩 속도를 높입니다. 모델 로딩 시 CPU 메모리(피크 메모리 포함)를 모델 크기의 1배를 초과하지 않도록 시도합니다. PyTorch 1.9.0 이상에서만 지원됩니다. PyTorch의 이전 버전을 사용하는 경우 이 인수를 `True`로 설정하면 오류가 발생합니다.

#### set_ip_adapter_scale[[diffusers.loaders.IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale)
```

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

IP-Adapter 스케일을 트랜스포머 블록별로 설정합니다. 입력 `scale`은 단일 설정 또는 각 IP-Adapter 동작을 세밀하게 제어하기 위한 설정 목록일 수 있습니다. 설정은 float 또는 딕셔너리일 수 있습니다.

예:

```py
# To use original IP-Adapter
scale = 1.0
pipeline.set_ip_adapter_scale(scale)

# To use style block only
scale = {
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style+layout blocks
scale = {
    "down": {"block_2": [0.0, 1.0]},
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style and layout from 2 reference images
scales = [{"down": {"block_2": [0.0, 1.0]}}, {"up": {"block_0": [0.0, 1.0, 0.0]}}]
pipeline.set_ip_adapter_scale(scales)
```

#### unload_ip_adapter[[diffusers.loaders.IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L312)

IP Adapter 가중치를 언로드합니다

예:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

#### diffusers.loaders.SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

```python
diffusers.loaders.SD3IPAdapterMixin()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L904)

StableDiffusion 3 IP Adapters를 처리하는 Mixin입니다.

#### is_ip_adapter_active[[diffusers.loaders.SD3IPAdapterMixin.is_ip_adapter_active]]

```python
is_ip_adapter_active()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L907)

**반환값:** `bool`

IP-Adapter가 로드되고 어떤 레이어의 scale 값이 0보다 큰 경우 true입니다.

IP-Adapter가 로드되어 있는지 및 scale > 0인지 확인합니다.

IP-Adapter scale은 이미지 프롬프트와 텍스트 프롬프트 간의 상대적 영향을 제어합니다. 이 값이 0으로 설정되면 이미지 컨텍스트는 관련이 없습니다.

#### load_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor], weight_name: str = 'ip-adapter.safetensors', subfolder: str | None = None, image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L925)

**매개변수:**

pretrained_model_name_or_path_or_dict (`str` 또는 `os.PathLike` 또는 `dict`) : 다음 중 하나일 수 있습니다: - Hub에 호스팅된 사전 학습 모델의 *model id*(예: `google/ddpm-celebahq-256`) 문자열. - [ModelMixin.save_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.save_pretrained)로 저장된 모델 가중치를 포함하는 *디렉터리* 경로(예: `./my_model_directory`). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`, 기본값 "ip-adapter.safetensors") : 로드할 가중치 파일의 이름입니다. 리스트가 전달되면 `subfolder`와 동일한 길이를 가져야 합니다.

subfolder (`str`, *선택 사항*) : Hub 또는 로컬의 더 큰 모델 저장소 내에서 모델 파일의 서브폴더 위치입니다. 리스트가 전달되면 `weight_name`과 동일한 길이를 가져야 합니다.

image_encoder_folder (`str`, *선택 사항*, 기본값은 `image_encoder`) : Hub 또는 로컬의 더 큰 모델 저장소 내에서 이미지 인코더의 서브폴더 위치입니다. 이미지 인코더를 로드하지 않으려면 `None`을 전달하세요. 이미지 인코더가 `subfolder` 안의 폴더에 있는 경우, 이미지 인코더 가중치를 포함하는 폴더의 이름만 전달하면 됩니다. 예를 들어 `image_encoder_folder="image_encoder"`입니다. 이미지 인코더가 `subfolder`가 아닌 다른 폴더에 있는 경우, 이미지 인코더 가중치를 포함하는 폴더의 경로를 전달해야 합니다. 예를 들어 `image_encoder_folder="different_subfolder/image_encoder"`입니다.

cache_dir (`str | os.PathLike`, *선택 사항*) : 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성이 캐시되는 디렉터리의 경로입니다.

force_download (`bool`, *선택 사항*, 기본값 `False`) : 캐시된 버전이 존재하더라도 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부.

proxies (`dict[str, str]`, *선택 사항*) : 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`와 같습니다. 각 요청에 프록시가 사용됩니다.

local_files_only (`bool`, *선택 사항*, 기본값 `False`) : 로컬 모델 가중치와 구성 파일만 로드할지 여부를 지정합니다. `True`로 설정하면 Hub에서 모델을 다운로드하지 않습니다.

token (`str` 또는 *bool*, *선택 사항*) : 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. `True`인 경우, `diffusers-cli login`에서 생성된 토큰(`~/.huggingface`에 저장됨)이 사용됩니다.

revision (`str`, *선택 사항*, 기본값 `"main"`) : 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다.

low_cpu_mem_usage (`bool`, *선택 사항*, torch 버전이 1.9.0 이상이면 기본값은 `True`, 그 외에는 `False`) : 가중치를 초기화하지 않고 사전 학습된 가중치만 로드하여 모델 로딩 속도를 높입니다. 모델 로딩 시 CPU 메모리(피크 메모리 포함)를 모델 크기의 1배를 초과하지 않도록 시도합니다. PyTorch 1.9.0 이상에서만 지원됩니다. PyTorch의 이전 버전을 사용하는 경우 이 인수를 `True`로 설정하면 오류가 발생합니다.

#### set_ip_adapter_scale[[diffusers.loaders.SD3IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale: float)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L1079)

**매개변수:**

scale (float) : 설정할 IP-Adapter 스케일입니다.

이미지 프롬프트 조건화를 제어하는 IP-Adapter 스케일을 설정합니다. 값이 1.0이면 모델은 이미지 프롬프트에만 조건화되고, 0.0이면 텍스트 프롬프트에만 조건화됩니다. 이 값을 낮추면 모델이 더 다양한 이미지를 생성하도록 장려하지만, 이미지 프롬프트와의 정합성이 낮아질 수 있습니다.

예:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.set_ip_adapter_scale(0.6)
>>> ...
```

#### unload_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L1102)

IP Adapter 가중치를 언로드합니다.

예:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

#### diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

```python
diffusers.IPAdapterMaskProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = False, do_binarize: bool = True, do_convert_grayscale: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/image_processor.py#L1277)

**매개변수:**

do_resize (`bool`, *선택 사항*, 기본값 `True`) : 이미지의 (높이, 너비) 차원을 `vae_scale_factor`의 배수로 다운스케일할지 여부.

vae_scale_factor (`int`, *선택 사항*, 기본값 `8`) : VAE 스케일 팩터입니다. `do_resize`가 `True`인 경우, 이미지는 이 팩터의 배수로 자동으로 리사이즈됩니다.

resample (`str`, *선택 사항*, 기본값 `lanczos`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터.

do_normalize (`bool`, *선택 사항*, 기본값 `False`) : 이미지를 [-1,1] 범위로 정규화할지 여부.

do_binarize (`bool`, *선택 사항*, 기본값 `True`) : 이미지를 0/1로 바이너리화할지 여부.

do_convert_grayscale (`bool`, *선택 사항*, 기본값은 `True`) : 이미지를 회색조 형식으로 변환할지 여부.

IP Adapter 이미지 마스크용 이미지 프로세서.

#### 다운샘플링[[diffusers.IPAdapterMaskProcessor.downsample]]

```python
downsample(mask: Tensor, batch_size: int, num_queries: int, value_embed_dim: int)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/image_processor.py#L1318)

**매개변수:**

mask (`torch.Tensor`) : `IPAdapterMaskProcessor.preprocess()`로 생성된 입력 마스크 텐서.

batch_size (`int`) : 배치 크기.

num_queries (`int`) : 쿼리의 개수.

value_embed_dim (`int`) : 값 임베딩의 차원.

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

다운샘플링된 마스크 텐서.

제공된 mask 텐서를 스케일된 dot-product attention에 필요한 차원에 맞게 다운샘플링합니다. mask의 종횡비가 출력 이미지의 종횡비와 일치하지 않으면 경고가 발생합니다.