diffusers/main/vi/api/loaders/ip_adapter.md

IP-Adapter

IP-Adapter 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.

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.

IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

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

diffusers.loaders.IPAdapterMixin()

Nguồn

Mixin để xử lý IP Adapters.

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

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

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(). - Một torch 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]]

set_ip_adapter_scale(scale)

Nguồn

Đặ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ụ:

# 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]]

unload_ip_adapter()

Nguồn

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

Ví dụ:

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

SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

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

diffusers.loaders.SD3IPAdapterMixin()

Nguồn

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

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

is_ip_adapter_active()

Nguồn

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]]

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

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(). - Một torch 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]]

set_ip_adapter_scale(scale: float)

Nguồn

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ụ:

>>> # 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]]

unload_ip_adapter()

Nguồn

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

Ví dụ:

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

IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

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

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]]

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

Nguồn

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.