Hugging Face's logo

Diffusers documentation

IP-Adapter

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

lớp diffusers.loaders.IPAdapterMixin

< >

( )

Mixin để xử lý IP Adapters.

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 )

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 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ó sẵn trên Hub.
    • Đường dẫn đến một thư mục (ví dụ ./my_model_directory) chứa các 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 bên trong một kho lưu trữ mô hình lớn hơn trên Hub hoặc cục bộ. Nếu một danh sách được truyền vào, 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, danh sách đó phải có cùng độ dài với subfolder.
  • image_encoder_folder (str, tuỳ chọn, mặc định là image_encoder) — Vị trí của thư mục con chứa image encoder trong một kho mô hình 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, chẳng hạn 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) — Có nên buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
  • proxies (dict[str, str], tuỳ 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 này đượ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 có chỉ tải trọng số và tệp cấu hình của mô hình từ 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 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, tùy 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 trọng số được huấn luyện trước mà không khởi tạo trọng số. Điều này cũng cố gắng không sử dụng nhiều hơn 1 lần kích thước mô hình trong bộ nhớ CPU (bao gồm 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

< >

( scale )

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

< >

( )

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

lớp diffusers.loaders.SD3IPAdapterMixin

< >

( )

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

is_ip_adapter_active

< >

( ) → bool

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 là 0, bối cảnh hình ảnh sẽ không còn liên quan.

load_ip_adapter

< >

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

Tham số

  • pretrained_model_name_or_path_or_dict (str hoặc os.PathLike hoặc dict) — Có thể là:
    • 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ó sẵn trên Hub.
    • Đường dẫn đến một thư mục (ví dụ ./my_model_directory) chứa các 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 kho mô hình lớn hơn trên Hub hoặc cục bộ. Nếu một danh sách được truyền vào, nó phải có cùng độ dài với weight_name.
  • image_encoder_folder (str, tuỳ chọn, mặc định là image_encoder) — Vị trí của thư mục con chứa image encoder trong một kho mô hình 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, chẳng hạn 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) — Có nên buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại hay không.
  • proxies (dict[str, str], tuỳ 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 này đượ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 có chỉ tải trọng số và tệp cấu hình của mô hình từ 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 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, tùy 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 trọng số được huấn luyện trước mà không khởi tạo trọng số. Điều này cũng cố gắng không sử dụng nhiều hơn 1 lần kích thước mô hình trong bộ nhớ CPU (bao gồm 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

< >

( scale: float )

Tham số

  • scale (float) — Thang IP-Adapter cần thiết lập.

Đặt IP-Adapter scale, tham số kiểm soát điều kiện của image prompt. Giá trị 1.0 có nghĩa là mô hình chỉ được điều kiện bởi image prompt, còn 0.0 chỉ được điều kiện bởi text prompt. 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 image prompt.

Ví dụ:

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

unload_ip_adapter

< >

( )

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

lớp diffusers.IPAdapterMaskProcessor

< >

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Falsedo_binarize: bool = Truedo_convert_grayscale: bool = True )

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 (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, tùy chọn, 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 ảnh về khoảng [-1,1] hay không.
  • do_binarize (bool, tùy chọn, mặc định là True) — Có nên 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) — Có chuyển đổi các 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

< >

( mask: Tensorbatch_size: intnum_queries: intvalue_embed_dim: int ) → torch.Tensor

Tham số

  • mask (torch.Tensor) — Tensor mask đầu vào được tạo bằng IPAdapterMaskProcessor.preprocess().
  • batch_size (int) — Kích thước lô.
  • num_queries (int) — Số lượng truy vấn.
  • value_embed_dim (int) — Số chiều 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.

Update on GitHub

←Guiders LoRA→