# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) adalah adapter ringan yang memungkinkan pemromptan model difusi dengan gambar. Metode ini memisahkan lapisan cross-attention untuk fitur gambar dan teks. Fitur gambar dihasilkan dari image encoder.

> [!TIP]
> Pelajari cara memuat dan menggunakan checkpoint serta gambar IP-Adapter dalam panduan [IP-Adapter](../../using-diffusers/ip_adapter).

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

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L54)

Mixin untuk menangani IP Adapters.

#### 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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L57)

**Parameter:**

pretrained_model_name_or_path_or_dict (`str` atau `list[str]` atau `os.PathLike` atau `list[os.PathLike]` atau `dict` atau `list[dict]`) : Bisa berupa salah satu dari:  - String, *model id* (misalnya `google/ddpm-celebahq-256`) dari model pretrained yang dihosting di Hub. - Path ke *directory* (misalnya `./my_model_directory`) yang berisi bobot model yang disimpan dengan [ModelMixin.save_pretrained()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.save_pretrained). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` atau `list[str]`) : Lokasi subfolder dari file model di dalam repositori model yang lebih besar di Hub atau secara lokal. Jika daftar yang diberikan, panjangnya harus sama dengan `weight_name`.

weight_name (`str` atau `list[str]`) : Nama file bobot yang akan dimuat. Jika daftar yang diberikan, panjangnya harus sama dengan `subfolder`.

image_encoder_folder (`str`, *opsional*, defaultnya `image_encoder`) : Lokasi subfolder dari image encoder di dalam repositori model yang lebih besar di Hub atau secara lokal. Berikan `None` untuk tidak memuat image encoder. Jika image encoder berada di dalam folder di dalam `subfolder`, Anda hanya perlu memberikan nama folder yang berisi bobot image encoder, misalnya `image_encoder_folder="image_encoder"`. Jika image encoder berada di folder selain `subfolder`, Anda harus memberikan path ke folder yang berisi bobot image encoder, misalnya `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *opsional*) : Path ke direktori tempat konfigurasi model pretrained yang diunduh di-cache jika cache standar tidak digunakan.

force_download (`bool`, *opsional*, defaultnya `False`) : Apakah akan memaksa (mengunduh ulang) bobot model dan file konfigurasi, menimpa versi yang di-cache jika ada.

proxies (`dict[str, str]`, *opsional*) : Kamus server proxy yang akan digunakan berdasarkan protokol atau endpoint, misalnya `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Proxy digunakan pada setiap permintaan.

local_files_only (`bool`, *opsional*, defaultnya `False`) : Apakah hanya memuat bobot model dan file konfigurasi lokal atau tidak. Jika diatur ke `True`, model tidak akan diunduh dari Hub.

token (`str` atau *bool*, *opsional*) : Token yang digunakan sebagai otorisasi bearer HTTP untuk file jarak jauh. Jika `True`, token yang dihasilkan dari `diffusers-cli login` (disimpan di `~/.huggingface`) akan digunakan.

revision (`str`, *opsional*, defaultnya `"main"`) : Versi model spesifik yang akan digunakan. Bisa berupa nama branch, nama tag, id commit, atau identifikasi apa pun yang diizinkan oleh Git.

low_cpu_mem_usage (`bool`, *opsional*, defaultnya `True` jika versi torch >= 1.9.0 selain itu `False`) : Mempercepat pemuatan model dengan hanya memuat bobot pretrained dan tidak menginisialisasi bobot. Ini juga berusaha untuk tidak menggunakan lebih dari 1x ukuran model di memori CPU (termasuk memori puncak) saat memuat model. Hanya didukung untuk PyTorch >= 1.9.0. Jika Anda menggunakan versi PyTorch yang lebih lama, mengatur argumen ini ke `True` akan memicu error.

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

```python
set_ip_adapter_scale(scale)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L252)

Set IP-Adapter menskalakan per blok transformer. Input `scale` dapat berupa satu config atau daftar config untuk kontrol granular atas perilaku masing-masing IP-Adapter. Sebuah config dapat berupa float atau dictionary.

Contoh:

```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()
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L305)

Memuat ulang bobot IP Adapter

Contoh:

```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()
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L885)

Mixin untuk menangani IP Adapter StableDiffusion 3.

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

```python
is_ip_adapter_active()
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L888)

**Mengembalikan:** `bool`

Benar ketika IP-Adapter dimuat dan lapisan mana pun memiliki scale > 0.

Memeriksa apakah IP-Adapter dimuat dan scale > 0.

IP-Adapter scale mengontrol pengaruh prompt gambar dibandingkan dengan prompt teks. Ketika nilai ini diatur ke 0, konteks gambar tidak relevan.

#### 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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L906)

**Parameter:**

pretrained_model_name_or_path_or_dict (`str` atau `os.PathLike` atau `dict`) : Bisa berupa: - String, *model id* (misalnya `google/ddpm-celebahq-256`) dari model pretrained yang dihosting di Hub. - Path ke *directory* (misalnya `./my_model_directory`) yang berisi bobot model yang disimpan dengan [ModelMixin.save_pretrained()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.save_pretrained). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`, defaultnya "ip-adapter.safetensors") : Nama file bobot yang akan dimuat. Jika daftar yang diberikan, panjangnya harus sama dengan `subfolder`.

subfolder (`str`, *opsional*) : Lokasi subfolder dari file model di dalam repositori model yang lebih besar di Hub atau secara lokal. Jika daftar yang diberikan, panjangnya harus sama dengan `weight_name`.

image_encoder_folder (`str`, *opsional*, defaultnya `image_encoder`) : Lokasi subfolder dari image encoder di dalam repositori model yang lebih besar di Hub atau secara lokal. Berikan `None` untuk tidak memuat image encoder. Jika image encoder berada di dalam folder di dalam `subfolder`, Anda hanya perlu memberikan nama folder yang berisi bobot image encoder, misalnya `image_encoder_folder="image_encoder"`. Jika image encoder berada di folder selain `subfolder`, Anda harus memberikan path ke folder yang berisi bobot image encoder, misalnya `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *opsional*) : Path ke direktori tempat konfigurasi model pretrained yang diunduh di-cache jika cache standar tidak digunakan.

force_download (`bool`, *opsional*, defaultnya `False`) : Apakah akan memaksa (mengunduh ulang) bobot model dan file konfigurasi, menimpa versi yang di-cache jika ada.

proxies (`dict[str, str]`, *opsional*) : Kamus server proxy yang akan digunakan berdasarkan protokol atau endpoint, misalnya `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Proxy digunakan pada setiap permintaan.

local_files_only (`bool`, *opsional*, defaultnya `False`) : Apakah hanya memuat bobot model dan file konfigurasi lokal atau tidak. Jika diatur ke `True`, model tidak akan diunduh dari Hub.

token (`str` atau *bool*, *opsional*) : Token yang digunakan sebagai otorisasi bearer HTTP untuk file jarak jauh. Jika `True`, token yang dihasilkan dari `diffusers-cli login` (disimpan di `~/.huggingface`) akan digunakan.

revision (`str`, *opsional*, defaultnya `"main"`) : Versi model spesifik yang akan digunakan. Bisa berupa nama branch, nama tag, id commit, atau identifikasi apa pun yang diizinkan oleh Git.

low_cpu_mem_usage (`bool`, *opsional*, defaultnya `True` jika versi torch >= 1.9.0 selain itu `False`) : Mempercepat pemuatan model dengan hanya memuat bobot pretrained dan tidak menginisialisasi bobot. Ini juga berusaha untuk tidak menggunakan lebih dari 1x ukuran model di memori CPU (termasuk memori puncak) saat memuat model. Hanya didukung untuk PyTorch >= 1.9.0. Jika Anda menggunakan versi PyTorch yang lebih lama, mengatur argumen ini ke `True` akan memicu error.

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L1054)

**Parameter:**

scale (float) : skala IP-Adapter yang akan diatur.

Set skala IP-Adapter, yang mengontrol kondisioning prompt gambar. Nilai 1.0 berarti model hanya dikondisikan oleh prompt gambar, dan 0.0 hanya dikondisikan oleh prompt teks. Menurunkan nilai ini mendorong model untuk menghasilkan gambar yang lebih beragam, tetapi gambar tersebut mungkin tidak selaras dengan prompt gambar.

Contoh:

```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()
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/ip_adapter.py#L1077)

Memuat ulang bobot IP Adapter.

Contoh:

```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)
```

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

**Parameter:**

do_resize (`bool`, *opsional*, defaultnya `True`) : Apakah akan menurunkan skala dimensi (tinggi, lebar) gambar menjadi kelipatan dari `vae_scale_factor`.

vae_scale_factor (`int`, *opsional*, defaultnya `8`) : Faktor skala VAE. Jika `do_resize` adalah `True`, gambar akan di-resize secara otomatis menjadi kelipatan dari faktor ini.

resample (`str`, *opsional*, defaultnya `lanczos`) : Filter resampling yang digunakan saat mengubah ukuran gambar.

do_normalize (`bool`, *opsional*, defaultnya `False`) : Apakah akan menormalisasi gambar ke [-1,1].

do_binarize (`bool`, *opsional*, defaultnya `True`) : Apakah akan mbinerisasi gambar menjadi 0/1.

do_convert_grayscale (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengonversi gambar ke format grayscale.

Pemroses gambar untuk masker gambar IP Adapter.

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

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

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

**Parameter:**

mask (`torch.Tensor`) : Tensor mask input yang dihasilkan dengan `IPAdapterMaskProcessor.preprocess()`.

batch_size (`int`) : Ukuran batch.

num_queries (`int`) : Jumlah query.

value_embed_dim (`int`) : Dimensi dari value embeddings.

**Mengembalikan:** `torch.Tensor`

Tensor mask yang telah di-downsample.

Menurunkan sampel tensor mask yang diberikan agar sesuai dengan dimensi yang diharapkan untuk scaled dot-product attention. Jika rasio aspek mask tidak cocok dengan rasio aspek gambar keluaran, peringatan akan diterbitkan.