# LoHa

    

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

低ランク・ハダマード積（[LoHa](https://huggingface.co/papers/2108.06098)）は、LoRAと同様ですが、大きな重み行列をより多くの低ランク行列で近似し、それらをハダマード積で結合します。この手法はLoRAよりもさらにパラメータ効率が高く、同等の性能を実現します。LoHaは元々分散学習（FedPara）のために提案されましたが、汎用的なPEFT手法としても機能し、Stable Diffusionなどの画像生成モデルのファインチューニングにおいて特に人気があります。

> **注:** LoHaは[LyCORIS](./adapter_utils)アダプターファミリーの一部です。その近親である[LoKr](./lokr)は、Hadamard積ではなくKronecker積を使用します。

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

*本研究では、頻繁なモデルのアップロードおよびダウンロードに伴う負担を克服するために、連合学習（FL）向けの通信効率に優れたパラメータ化手法 FedPara を提案する。本手法は、低ランクの重みを用いた層の重みパラメータの再パラメータ化を行い、その後 Hadamard 積を適用する。従来の低ランクパラメータ化と比較して、FedPara は低ランク制約に制限されないため、はるかに大きな容量を持つ。この特性により、元の層を持つモデルと比較して 3 倍から 10 倍低い通信コストで同等の性能を達成できるが、これは従来の低ランク手法では実現できない。本手法の効率性は、他の効率的な FL オプティマイザと組み合わせることでさらに向上させることができる。さらに、本手法をパーソナライズド FL 応用に拡張し、パラメータをグローバルとローカルに分離する pFedPara を提案する。pFedPara は、競合するパーソナライズド FL 手法よりも 3 倍以上少ないパラメータ数で優れた性能を発揮することを示す。*

低ランク分解は、重みの更新が低ランク空間に限定されるため、モデルの表現能力を制約し、パフォーマンスに影響を与える可能性があります。ただし、ランクを大きくすると学習可能なパラメータ数が増加するため、必ずしも大きなランクを使用すべきではありません。この問題を解決するために、多様な画像を生成する能力が重要な考慮事項となる拡散モデルに LoHa が適用されました。LoHa は一般的なモデルタイプでも動作するはずですが、埋め込み層へのサポートは現在 PEFT に実装されていません。

LoHaは、行列積の代わりに[ハダマード積](https://en.wikipedia.org/wiki/Hadamard_product_(matrices))（要素ごとの積）を使用します。$\Delta W$は、LoRAと同様に2つの行列ではなく4つの小さな行列で表現され、これらの低ランク行列の各ペアはハダマード積で結合されます。その結果、$\Delta W$は学習可能なパラメータ数が同じであっても、より高いランクと表現力を持つことができます。

## LoHaを使用するタイミング

LoHaが適切な選択肢となるのは、次のような場合です：

- 最も広く利用されている、**画像生成モデル**（Stable Diffusion UNetまたはテキストエンコーダー）のファインチューニングを行う場合です。
- 同じ数の学習可能パラメータに対して、LoRAよりも**より高い有効ランク**が得られることを望みます。2つの低ランク行列のHadamard積は、単一の低ランク積よりも大きな部分空間を張るためです。
- 推論時に[`PeftMixedModel`](./peft_model#peft.PeftMixedModel)を使用して、例えばLoHaとLoKrのように**異なるPEFT手法を組み合わせたい**場合。

LoHaは線形層とConv2d層をサポートしています。埋め込み層の適応も必要となるタスクには、代わりに[LoRA](./lora)をご検討ください。

## 使用方法

```python
from diffusers import StableDiffusionPipeline
from peft import LoHaConfig, get_peft_model

config_unet = LoHaConfig(
    r=8,
    alpha=8,
    target_modules=[
        "to_k",
        "to_q",
        "to_v",
        "to_out.0",
        "proj_in",
        "proj_out",
    ],
    rank_dropout=0.0,
    module_dropout=0.0,
    use_effective_conv2d=True,
)

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
pipeline.unet = get_peft_model(pipeline.unet, config_unet)
pipeline.unet.print_healthcheck()
```

## ベンチマーク概要

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

# API

## LoHaConfig[[peft.LoHaConfig]]

#### peft.LoHaConfig[[peft.LoHaConfig]]

```python
peft.LoHaConfig(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, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, init_weights: bool = 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/loha/config.py#L24)

**パラメータ:**

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

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

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

module_dropout (`float`) : 学習中にLoHaモジュールを無効にするドロップアウト確率。

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

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

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

init_weights (`bool`) : アダプター重みの初期化を実行するかどうか。デフォルトは`True`です。`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]]`) : アダプタ層を除き、最終チェックポイントで学習可能かつ保存されるように設定するモジュールのリスト。

これは、[LoHaModel](/docs/peft/v0.22.0/ja/package_reference/loha#peft.LoHaModel)の設定を保存するための設定クラスです。

## LoHaModel[[peft.LoHaModel]]

#### peft.LoHaModel[[peft.LoHaModel]]

```python
peft.LoHaModel(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/loha/model.py#L27)

**パラメータ:**

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

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

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

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

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

LoHaモデル。

https://huggingface.co/papers/2108.06098 に部分的に説明されている手法に基づき、事前学習済みモデルから Low-Rank Hadamard Product モデルを作成します。現在の実装は、https://github.com/KohakuBlueleaf/LyCORIS/blob/eb460098187f752a5d66406d3affade6f0a07ece/lycoris/modules/loha.py を大きく参照しています。

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

>>> config_te = LoHaConfig(
...     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 = LoHaConfig(
...     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** ([LoHaConfig](/docs/peft/v0.22.0/ja/package_reference/loha#peft.LoHaConfig)): LoHaモデルの設定です。

