diffusers/main/ja/api/loaders/peft.md

PEFT

Diffusersは、PeftAdapterMixinクラスを用いることで、PEFTライブラリによるLoRAなどのアダプターの読み込みをサポートしています。これにより、UNet2DConditionModelやSD3Transformer2DModelといったDiffusersのモデリングクラスが、アダプターを併用して動作するようになります。

DiffusersでPEFTを使用して推論を行う方法の概要については、Inference with PEFTチュートリアルを参照してください。

PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

diffusers.loaders.PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

diffusers.loaders.PeftAdapterMixin()

ソース

PEFT ライブラリでサポートされているアダプター重みの読み込みと使用に関するすべての関数を含むクラスです。アダプターおよびベースモデルへの注入の詳細については、PEFT の ドキュメントを参照してください。

PEFTの最新バージョンをインストールし、このミックスインを使用して、次のことを実行します。

• モデルに新しいアダプターをアタッチします。
• 複数のアダプターをアタッチし、それらを反復的にアクティブ化/非アクティブ化します。
• モデルからすべてのアダプターを有効化/無効化します。
• アクティブなアダプターのリストを取得します。

active_adapters[[diffusers.loaders.PeftAdapterMixin.active_adapters]]

active_adapters()

ソース

モデルの現在アクティブなアダプターの一覧を取得します。

アダプターやPEFT手法に詳しくない場合は、PEFTのドキュメントで詳しくお読みください。

add_adapter[[diffusers.loaders.PeftAdapterMixin.add_adapter]]

add_adapter(adapter_config, adapter_name: str = 'default')

ソース

パラメータ:

adapter_config ([~peft.PeftConfig]) : 追加するアダプターの設定。サポートされているアダプターは、non-prefix tuning と adaption prompt の手法です。

adapter_name (str、任意、デフォルトは"default") : 追加するアダプターの名前です。名前が指定されない場合、アダプターにデフォルトの名前が割り当てられます。

現在のモデルに学習用の新しいアダプターを追加します。アダプター名が指定されない場合、PEFTライブラリの慣例に従って、アダプターにデフォルトの名前が割り当てられます。

アダプターやPEFT手法に詳しくない場合は、PEFTのドキュメントで詳しくお読みください。

delete_adapters[[diffusers.loaders.PeftAdapterMixin.delete_adapters]]

delete_adapters(adapter_names: list[str] | str)

ソース

パラメータ:

adapter_names (list[str, str]) : 削除するアダプターの名前（単一の文字列または文字列のリスト）。

アダプターのLoRA層を基盤モデルから削除します。

例:

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_names="cinematic"
)
pipeline.unet.delete_adapters("cinematic")

disable_adapters[[diffusers.loaders.PeftAdapterMixin.disable_adapters]]

disable_adapters()

ソース

モデルにアタッチされているすべてのアダプターを無効化し、ベースモデルのみで推論を実行するようにフォールバックします。

アダプターやPEFT手法に詳しくない場合は、PEFTのドキュメントで詳しくお読みください。

disable_lora[[diffusers.loaders.PeftAdapterMixin.disable_lora]]

disable_lora()

ソース

基盤モデルのアクティブなLoRAレイヤーを無効にします。

例:

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.disable_lora()

enable_adapters[[diffusers.loaders.PeftAdapterMixin.enable_adapters]]

enable_adapters()

ソース

モデルにアタッチされたアダプターを有効にします。モデルはself.active_adapters()を使用して、有効にするアダプターのリストを取得します。

アダプターやPEFT手法に詳しくない場合は、PEFTのドキュメントで詳しくお読みください。

enable_lora[[diffusers.loaders.PeftAdapterMixin.enable_lora]]

enable_lora()

ソース

基盤モデルのアクティブなLoRAレイヤーを有効にします。

例:

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.enable_lora()

enable_lora_hotswap[[diffusers.loaders.PeftAdapterMixin.enable_lora_hotswap]]

enable_lora_hotswap(target_rank: int = 128, check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error')

ソース

パラメータ:

target_rank (int、任意、デフォルトは128) : 読み込まれるすべてのアダプターの中で最も高いランク。

check_compiled (str、任意、デフォルトは"error") : モデルがすでにコンパイルされている場合の処理方法です。一般的にはこれを避けるべきです。オプションは以下の通りです: - "error" (デフォルト): エラーを送出 - "warn": 警告を出力 - "ignore": 何もしない

LoRAアダプターをホットスワップする機能を有効にします。

このメソッドを呼び出す必要があるのは、アダプターをホットスワップする場合で、かつモデルがコンパイルされているか、読み込まれたアダプターのランクが異なる場合のみです。

load_lora_adapter[[diffusers.loaders.PeftAdapterMixin.load_lora_adapter]]

load_lora_adapter(pretrained_model_name_or_path_or_dict, prefix = 'transformer', hotswap: bool = False, **kwargs)

ソース

パラメータ:

pretrained_model_name_or_path_or_dict (str または os.PathLike または dict) : 以下のいずれかです。 - Hub にホストされている事前学習済みモデルの model id（例: google/ddpm-celebahq-256）を示す文字列。 - ModelMixin.save_pretrained() で保存されたモデルの重みを格納した ディレクトリ へのパス（例: ./my_model_directory）。 - torch state dict。

prefix (str, 任意) : state dict をフィルタリングするためのプレフィックス。

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 ベアラ認証に使用するトークン。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存）が使用されます。

revision (str、任意、デフォルトは"main") : 使用する特定のモデルバージョンです。ブランチ名、タグ名、コミット ID、または Git で許可されている任意の識別子を使用できます。

subfolder (str、任意、デフォルトは "") : Hub またはローカル上のより大きなモデルリポジトリ内での、モデルファイルのサブフォルダの場所。

network_alphas (dict[str, float]) : 安定した学習とアンダーフローの防止に使用されるネットワークアルファの値です。この値は、kohya-ss トレーナースクリプトの --network_alpha オプションと同じ意味を持ちます。このリンクを参照してください。

low_cpu_mem_usage (bool, 省略可) : ランダムな重みの初期化を行わず、事前学習済み LoRA 重みのみを読み込むことで、モデルの読み込みを高速化します。

hotswap : (bool, 任意) デフォルト値は False です。既存の (LoRA) アダプターを、新しく読み込まれたアダプターでその場で置き換えるかどうかを指定します。つまり、追加のアダプターを読み込むのではなく、既存のアダプター重みを新しいアダプターの重みで置き換えます。これにより、より高速かつメモリ効率の高い処理が可能になります。ただし、ホットスワップの主な利点は、モデルが torch.compile でコンパイルされている場合、新しいアダプターを読み込んでもモデルの再コンパイルが不要になる点です。ホットスワップを使用する場合は、渡す adapter_name は、すでに読み込まれているアダプターの名前である必要があります。 新しいアダプターと古いアダプターでランクと/または LoRA alpha (すなわちスケーリング) が異なる場合、アダプターを読み込む前に追加のメソッドを呼び出す必要があります: py pipeline = ... # load diffusers pipeline max_rank = ... # the highest rank among all LoRAs that you want to load # call *before* compiling and loading the LoRA adapter pipeline.enable_lora_hotswap(target_rank=max_rank) pipeline.load_lora_weights(file_name) # optionally compile the model now テキストエンコーダーのアダプターのホットスワップは、まだサポートされていません。この技術にはいくつかの制限があり、以下にドキュメント化されています: https://huggingface.co/docs/peft/main/en/package_reference/hotswap

metadata : LoRA アダプターのメタデータ。指定された場合、state dict 経由で推定されたメタデータは LoraConfig の初期化には使用されません。

LoRAアダプターを基盤モデルに読み込みます。

save_lora_adapter[[diffusers.loaders.PeftAdapterMixin.save_lora_adapter]]

save_lora_adapter(save_directory, adapter_name: str = 'default', upcast_before_saving: bool = False, safe_serialization: bool = True, weight_name: str | None = None)

ソース

パラメータ:

save_directory (str または os.PathLike) : LoRA パラメータを保存するディレクトリ。存在しない場合は作成されます。

adapter_name : (str、デフォルトは "default"): シリアライズするアダプタの名前です。基盤モデルに複数のアダプタが読み込まれている場合に便利です。

upcast_before_saving (bool、デフォルトはFalse) : シリアライズ前に、基盤となるモデルをtorch.float32にキャストするかどうか。

safe_serialization (bool、任意、デフォルトはTrue) : モデルをsafetensorsで保存するか、pickleを用いた従来の PyTorch の方法で保存するかどうかを指定します。

weight_name : (str、任意、デフォルトはNone): state dict をシリアライズするファイルの名前。

ベースモデルに対応する LoRA パラメータを保存します。

set_adapter[[diffusers.loaders.PeftAdapterMixin.set_adapter]]

set_adapter(adapter_name: str | list[str])

ソース

パラメータ:

adapter_name (str | list[str])) : 設定するアダプターのリスト、または単一のアダプターの場合はアダプター名。

特定のアダプターを設定し、モデルがそのアダプターのみを使用するよう強制して、他のアダプターを無効にします。

アダプターやPEFT手法に詳しくない場合は、PEFTのドキュメントで詳しくお読みください。

set_adapters[[diffusers.loaders.PeftAdapterMixin.set_adapters]]

set_adapters(adapter_names: list[str] | str, weights: float | dict | list[float] | list[dict] | list[None] | None = None)

ソース

パラメータ:

adapter_names (list[str] または str) : 使用するアダプターの名前。

weights (Union[List[float], float]、任意) : UNet で使用するアダプター重みです。None の場合、すべてのアダプターの重みは 1.0 に設定されます。

拡散ネットワーク（unet、transformer など）で使用するために、現在アクティブなアダプターを設定します。

例:

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.load_lora_weights("nerijs/pixel-art-xl", weight_name="pixel-art-xl.safetensors", adapter_name="pixel")
pipeline.unet.set_adapters(["cinematic", "pixel"], weights=[0.5, 0.5])