# LoKr

    

テキストから画像への生成のカスタマイズをナビゲートする：LyCORISのファインチューニングからモデル評価まで

低ランク・クロネッカー積（[LoKr](https://hf.co/papers/2309.14859)）は、LoRAのバリアントであり、大きな重み行列を2つの低ランク行列で近似し、[クロネッカー積](https://en.wikipedia.org/wiki/Kronecker_product)で結合します。LoKrは、ファインチューニング時の制御をより良くするために、任意の第3の低ランク行列も提供します。重み更新行列をクロネッカー積の分解として表現し、ブロック行列を作成することで、LoKrは元の重み行列のランクを保持できます。小さな行列のサイズは、その*rank*または`r`によって決定されます。クロネッカー積のもう一つの利点は、行列の列をスタックすることでベクトル化できることです。これにより、∆Wを完全に再構築することを避けるため、処理が高速化されます。

論文の抄録は以下の通りです:

*テキストから画像を生成する生成モデルは、テキストプロンプトから高忠実度の画像を生成できる能力により、多大な注目を集めています。これらのモデルの中で、Stable Diffusion は、この急速に成長している分野における主要なオープンソースモデルとして際立っています。しかし、これらのモデルのファインチューニングには、新しい手法の統合から体系的な評価に至るまで、複数の課題が存在します。これらの問題に対処するため、本論文では、Stable Diffusion 向けの幅広いファインチューニング手法を提供するオープンソースライブラリである LyCORIS [Lora beYond Conventional methods, Other Rank adaptation Implementations for Stable diffusion](https://github.com/KohakuBlueleaf/LyCORIS) を紹介します。さらに、多様なファインチューニング技術の体系的な評価のための包括的なフレームワークを提示します。このフレームワークは、多様な指標のセットを用い、ハイパーパラメータの調整や、さまざまな概念カテゴリにわたる異なるプロンプトタイプを用いた評価など、ファインチューニングの複数の側面に深く掘り下げています。この包括的なアプローチを通じて、私たちの研究は、ファインチューニングパラメータの微妙な影響に関する重要な洞察を提供し、最先端の研究と実用的な応用の間のギャップを埋めます。*

## 使用方法

```py
from peft import LoKrConfig, get_peft_model

config = LoKrConfig(
    r=16,
    alpha=16,
    target_modules=["query", "value"],
    module_dropout=0.1,
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()
```

## ベンチマーク概要

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=LOKR" frameborder="0" width="850" height="1000"
>

# API

## LoKrConfig[[peft.LoKrConfig]]

#### peft.LoKrConfig[[peft.LoKrConfig]]

```python
peft.LoKrConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, rank_pattern: Optional[dict] = <factory>, alpha_pattern: Optional[dict] = <factory>, r: int = 8, alpha: int = 8, rank_dropout: float = 0.0, module_dropout: float = 0.0, use_effective_conv2d: bool = False, decompose_both: bool = False, decompose_factor: int = -1, rank_dropout_scale: bool = False, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, init_weights: Union[bool, Literal['lycoris']] = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, modules_to_save: Optional[list[str]] = None)
```

[ソース](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lokr/config.py#L24)

**パラメータ:**

r (`int`) : LoKr のランク。

alpha (`int`) : LoKrのスケーリング用のalphaパラメータ。

rank_dropout (`float`) : 学習中のランク次元におけるdropoutの確率。

module_dropout (`float`) : 学習中にLoKrモジュールを無効にするためのdropout確率。

use_effective_conv2d (`bool`) : ksize > 1 の Conv2d (および Conv1d) に対して、パラメータの効率的な分解を使用します (FedPara 論文の「Proposition 3」)。

decompose_both (`bool`) : 左クロネッカー積行列のランク分解を実行します。

decompose_factor (`int`) : クローネッカー積の分解係数。

rank_dropout_scale ('bool) : 学習中にランクドロップアウトをスケーリングするかどうか。デフォルトは`False`です。

target_modules (`Optional[Union[List[str], str]]`) : アダプタを適用するモジュールの名前です。これを指定した場合、指定された名前のモジュールのみが置き換えられます。文字列を渡す場合は、正規表現によるマッチングが行われます。文字列のリストを渡す場合は、完全一致が行われるか、モジュールの名前が渡された文字列のいずれかで終わるかがチェックされます。'all-linear' として指定した場合、出力層を除くすべての linear/Conv1D モジュールが選択されます。指定しない場合、モデルのアーキテクチャに基づいてモジュールが選択されます。アーキテクチャが不明な場合はエラーが発生します。この場合、ターゲットモジュールを手動で指定する必要があります。

exclude_modules (`Optional[Union[List[str], str]]`) : アダプタを適用しないモジュールの名前。文字列を渡す場合、正規表現によるマッチングが行われます。文字列のリストを渡す場合、完全一致が行われるか、モジュールの名前が渡された文字列のいずれかで終わるかがチェックされます。

init_weights (`bool`) : アダプター重みの初期化を実行するかどうか。デフォルトは`True`です。LYCORISリポジトリのスタイルで重みを初期化するには"lycoris"を指定します。`False`を渡すことは推奨されません。

layers_to_transform (`Union[List[int], int]`) : 変換を適用するレイヤーのインデックスです。int のリストが渡された場合、このリストで指定されたレイヤーのインデックスにアダプターを適用します。単一の整数が渡された場合、そのインデックスのレイヤーに変換を適用します。

layers_pattern (`Optional[Union[List[str], str]]`) : `layers_to_transform`が`None`と異なる場合にのみ使用されるレイヤーパターン名です。これはモデルの`nn.ModuleList`をターゲットとすべきで、通常`'layers'`または`'h'`と呼ばれます。

rank_pattern (`dict`) : `r`で指定されたデフォルトのランクと異なるランクを持つ、レイヤー名または正規表現からランクへのマッピングです。例えば、`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。

alpha_pattern (`dict`) : `alpha`で指定されるデフォルト値と異なる値を持つ、レイヤー名または正規表現からalphaへのマッピングです。例えば、`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}`。

modules_to_save (`Optional[List[str]]`) : アダプタ層を除き、最終チェックポイントで学習可能かつ保存されるように設定するモジュールのリスト。

[LoKrModel](/docs/peft/v0.22.0/ja/package_reference/lokr#peft.LoKrModel)の設定クラスです。

## LoKrModel[[peft.LoKrModel]]

#### peft.LoKrModel[[peft.LoKrModel]]

```python
peft.LoKrModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[ソース](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lokr/model.py#L27)

**パラメータ:**

model (`torch.nn.Module`) : アダプタチューナー層が接続されるモデル。

config ([LoKrConfig](/docs/peft/v0.22.0/ja/package_reference/lokr#peft.LoKrConfig)) : LoKrモデルの設定です。

adapter_name (`str`) : アダプターの名前。デフォルトは`"default"`です。

low_cpu_mem_usage (`bool`、`optional`、デフォルトは`False`) : メタデバイス上に空のアダプター重みを生成します。読み込みプロセスを高速化するために有用です。

**戻り値:** `torch.nn.Module`

LoKrモデル。

https://huggingface.co/papers/2108.06098 および https://huggingface.co/papers/2309.14859 に、元の手法が部分的に説明されています。現在の実装は、https://github.com/KohakuBlueleaf/LyCORIS/blob/eb460098187f752a5d66406d3affade6f0a07ece/lycoris/modules/lokr.py を大きく参照しています。

例:
```py
>>> from diffusers import StableDiffusionPipeline
>>> from peft import LoKrConfig, get_peft_model

>>> config_te = LoKrConfig(
...     r=8,
...     alpha=32,
...     target_modules=["k_proj", "q_proj", "v_proj", "out_proj", "fc1", "fc2"],
...     rank_dropout=0.0,
...     module_dropout=0.0,
...     init_weights=True,
... )
>>> config_unet = LoKrConfig(
...     r=8,
...     alpha=32,
...     target_modules=[
...         "proj_in",
...         "proj_out",
...         "to_k",
...         "to_q",
...         "to_v",
...         "to_out.0",
...         "ff.net.0.proj",
...         "ff.net.2",
...     ],
...     rank_dropout=0.0,
...     module_dropout=0.0,
...     init_weights=True,
...     use_effective_conv2d=True,
... )

>>> model = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> model.text_encoder = get_peft_model(model.text_encoder, config_te)
>>> model.unet = get_peft_model(model.unet, config_unet)
```

**属性**:
- **model** (`~torch.nn.Module`) -- 適応対象のモデル。
- **peft_config** ([LoKrConfig](/docs/peft/v0.22.0/ja/package_reference/lokr#peft.LoKrConfig)): LoKrモデルの設定。

