# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) là một adapter nhẹ cho phép đưa prompt là hình ảnh vào mô hình khuếch tán. Phương pháp này tách rời các lớp cross-attention của đặc trưng hình ảnh và đặc trưng văn bản. Các đặc trưng hình ảnh được tạo ra từ một image encoder.

> [!TIP]
> Tìm hiểu cách tải và sử dụng checkpoint và hình ảnh IP-Adapter trong hướng dẫn [IP-Adapter](../../using-diffusers/ip_adapter).

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

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

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L54)

Mixin để xử lý 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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L57)

**Tham số:**

pretrained_model_name_or_path_or_dict (`str` hoặc `list[str]` hoặc `os.PathLike` hoặc `list[os.PathLike]` hoặc `dict` hoặc `list[dict]`) : Có thể là một trong các dạng sau:  - Một chuỗi, *model id* (ví dụ `google/ddpm-celebahq-256`) của một mô hình được huấn luyện trước có trên Hub. - Một đường dẫn đến *thư mục* (ví dụ `./my_model_directory`) chứa trọng số mô hình được lưu bằng [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/vi/api/models/overview#diffusers.ModelMixin.save_pretrained). - Một [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` hoặc `list[str]`) : Vị trí thư mục con của tệp mô hình trong một kho lưu trữ mô hình lớn hơn trên Hub hoặc cục bộ. Nếu truyền một danh sách, nó phải có cùng độ dài với `weight_name`.

weight_name (`str` hoặc `list[str]`) : Tên của tệp trọng số cần nạp. Nếu truyền vào một danh sách, nó phải có cùng độ dài với `subfolder`.

image_encoder_folder (`str`, *tùy chọn*, mặc định là `image_encoder`) : Vị trí thư mục con của image encoder trong một kho lưu trữ model lớn hơn trên Hub hoặc cục bộ. Truyền `None` để không nạp image encoder. Nếu image encoder nằm trong một thư mục bên trong `subfolder`, bạn chỉ cần truyền tên của thư mục chứa trọng số image encoder, ví dụ `image_encoder_folder="image_encoder"`. Nếu image encoder nằm trong một thư mục khác với `subfolder`, bạn nên truyền đường dẫn đến thư mục chứa trọng số image encoder, ví dụ `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *tùy chọn*) : Đường dẫn đến thư mục nơi cấu hình mô hình được huấn luyện trước đã tải xuống được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn.

force_download (`bool`, *tùy chọn*, mặc định là `False`) : Xác định có nên ép buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình hay không, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại.

proxies (`dict[str, str]`, *tùy chọn*) : Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Các proxy được sử dụng cho mỗi yêu cầu.

local_files_only (`bool`, *tùy chọn*, mặc định là `False`) : Xác định xem có chỉ tải trọng số và tệp cấu hình của mô hình cục bộ hay không. Nếu đặt thành `True`, mô hình sẽ không được tải xuống từ Hub.

token (`str` hoặc *bool*, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu là `True`, token được tạo từ `diffusers-cli login` (được lưu trong `~/.huggingface`) sẽ được sử dụng.

revision (`str`, *tùy chọn*, mặc định là `"main"`) : Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ, id commit, hoặc bất kỳ định danh nào được Git cho phép.

low_cpu_mem_usage (`bool`, *tuỳ chọn*, mặc định là `True` nếu phiên bản torch >= 1.9.0, ngược lại là `False`) : Tăng tốc quá trình tải mô hình bằng cách chỉ tải các trọng số được huấn luyện trước và không khởi tạo các trọng số. Đồng thời, tham số này cũng cố gắng không sử dụng quá 1 lần kích thước mô hình trong bộ nhớ CPU (bao gồm cả bộ nhớ đỉnh) trong khi tải mô hình. Chỉ hỗ trợ cho PyTorch >= 1.9.0. Nếu bạn đang sử dụng phiên bản PyTorch cũ hơn, việc đặt tham số này thành `True` sẽ gây ra lỗi.

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

```python
set_ip_adapter_scale(scale)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L252)

Đặt thang đo IP-Adapter cho từng khối transformer. Đầu vào `scale` có thể là một cấu hình duy nhất hoặc một danh sách các cấu hình để kiểm soát chi tiết hành vi của từng IP-Adapter. Một cấu hình có thể là một số float hoặc một từ điển.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L305)

Gỡ tải trọng số IP Adapter

Ví dụ:

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L885)

Mixin để xử lý IP Adapters cho StableDiffusion 3.

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

```python
is_ip_adapter_active()
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L888)

**Trả về:** `bool`

Đúng khi IP-Adapter được tải và bất kỳ lớp nào có scale > 0.

Kiểm tra xem IP-Adapter đã được tải và scale > 0 hay chưa.

IP-Adapter scale kiểm soát mức độ ảnh hưởng của prompt hình ảnh so với prompt văn bản. Khi giá trị này được đặt thành 0, ngữ cảnh hình ảnh sẽ không còn liên quan.

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L906)

**Tham số:**

pretrained_model_name_or_path_or_dict (`str` hoặc `os.PathLike` hoặc `dict`) : Có thể là một trong các dạng sau: - Một chuỗi, *model id* (ví dụ `google/ddpm-celebahq-256`) của một mô hình được huấn luyện trước có trên Hub. - Một đường dẫn đến *thư mục* (ví dụ `./my_model_directory`) chứa trọng số mô hình được lưu bằng [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/vi/api/models/overview#diffusers.ModelMixin.save_pretrained). - Một [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`, mặc định là "ip-adapter.safetensors") : Tên của tệp trọng số cần nạp. Nếu truyền vào một danh sách, danh sách đó phải có cùng độ dài với `subfolder`.

subfolder (`str`, *tùy chọn*) : Vị trí thư mục con của tệp mô hình trong một kho lưu trữ mô hình lớn hơn trên Hub hoặc cục bộ. Nếu truyền vào một danh sách, nó phải có cùng độ dài với `weight_name`.

image_encoder_folder (`str`, *tùy chọn*, mặc định là `image_encoder`) : Vị trí thư mục con của image encoder trong một kho lưu trữ model lớn hơn trên Hub hoặc cục bộ. Truyền `None` để không nạp image encoder. Nếu image encoder nằm trong một thư mục bên trong `subfolder`, bạn chỉ cần truyền tên của thư mục chứa trọng số image encoder, ví dụ `image_encoder_folder="image_encoder"`. Nếu image encoder nằm trong một thư mục khác với `subfolder`, bạn nên truyền đường dẫn đến thư mục chứa trọng số image encoder, ví dụ `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *tùy chọn*) : Đường dẫn đến thư mục nơi cấu hình mô hình được huấn luyện trước đã tải xuống được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn.

force_download (`bool`, *tùy chọn*, mặc định là `False`) : Xác định có nên ép buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình hay không, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại.

proxies (`dict[str, str]`, *tùy chọn*) : Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Các proxy được sử dụng cho mỗi yêu cầu.

local_files_only (`bool`, *tùy chọn*, mặc định là `False`) : Xác định xem có chỉ tải trọng số và tệp cấu hình của mô hình cục bộ hay không. Nếu đặt thành `True`, mô hình sẽ không được tải xuống từ Hub.

token (`str` hoặc *bool*, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu là `True`, token được tạo từ `diffusers-cli login` (được lưu trong `~/.huggingface`) sẽ được sử dụng.

revision (`str`, *tùy chọn*, mặc định là `"main"`) : Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ, id commit, hoặc bất kỳ định danh nào được Git cho phép.

low_cpu_mem_usage (`bool`, *tuỳ chọn*, mặc định là `True` nếu phiên bản torch >= 1.9.0, ngược lại là `False`) : Tăng tốc quá trình tải mô hình bằng cách chỉ tải các trọng số được huấn luyện trước và không khởi tạo các trọng số. Đồng thời, tham số này cũng cố gắng không sử dụng quá 1 lần kích thước mô hình trong bộ nhớ CPU (bao gồm cả bộ nhớ đỉnh) trong khi tải mô hình. Chỉ hỗ trợ cho PyTorch >= 1.9.0. Nếu bạn đang sử dụng phiên bản PyTorch cũ hơn, việc đặt tham số này thành `True` sẽ gây ra lỗi.

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

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1054)

**Tham số:**

scale (float) : Thang độ IP-Adapter cần thiết lập.

Đặt thang đo IP-Adapter, kiểm soát việc điều kiện hóa theo prompt hình ảnh. Giá trị 1.0 có nghĩa là mô hình chỉ được điều kiện hóa bởi prompt hình ảnh, và 0.0 chỉ được điều kiện hóa bởi prompt văn bản. Giảm giá trị này khuyến khích mô hình tạo ra các hình ảnh đa dạng hơn, nhưng chúng có thể không khớp với prompt hình ảnh bằng.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1077)

Gỡ tải trọng số của IP Adapter.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1277)

**Tham số:**

do_resize (`bool`, *tùy chọn*, mặc định là `True`) : Có nên giảm kích thước (chiều cao, chiều rộng) của ảnh xuống các bội số của `vae_scale_factor` hay không.

vae_scale_factor (`int`, *optional*, mặc định là `8`) : Hệ số tỷ lệ của VAE. Nếu `do_resize` là `True`, hình ảnh sẽ được tự động thay đổi kích thước thành bội số của hệ số này.

resample (`str`, *tùy chọn*, mặc định là `lanczos`) : Bộ lọc lấy mẫu lại (resampling filter) được sử dụng khi thay đổi kích thước ảnh.

do_normalize (`bool`, *tùy chọn*, mặc định là `False`) : Có nên chuẩn hóa hình ảnh về [-1,1] hay không.

do_binarize (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có nhị phân hóa ảnh thành 0/1 hay không.

do_convert_grayscale (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có chuyển đổi hình ảnh sang định dạng đen trắng hay không.

Bộ xử lý ảnh cho mặt nạ ảnh IP Adapter.

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

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1318)

**Tham số:**

mask (`torch.Tensor`) : Tensor mặt nạ đầu vào được tạo bằng `IPAdapterMaskProcessor.preprocess()`.

batch_size (`int`) : Kích thước lô (batch size).

num_queries (`int`) : Số lượng truy vấn.

value_embed_dim (`int`) : Độ cao của các vector nhúng giá trị.

**Trả về:** `torch.Tensor`

Tensor mặt nạ đã được giảm mẫu.

Thực hiện giảm mẫu (downsample) tensor mask được cung cấp để khớp với các kích thước mong đợi cho scaled dot-product attention. Nếu tỷ lệ khung hình (aspect ratio) của mask không khớp với tỷ lệ khung hình của ảnh đầu ra, một cảnh báo sẽ được phát ra.