# DeLoRA: Decoupled Low-rank Adaptation
[DeLoRA](https://huggingface.co/papers/2503.18225)は、学習可能な低ランク行列を正規化およびスケーリングすることで、事前学習済み重みに対するFrobenius境界を暗黙的に維持するパラメータ効率の良いファインチューニング手法です。これにより、重み更新の方向（BA項）と大きさ（境界項）の学習が効果的に分離され、適応済み重みの急激な変化を回避し、ハイパーパラメータ選択に対する頑健性が向上します。

注:
- use a learning rate 10-100x larger than for standard LoRA variants (typical values from 1e-3/1e-2/..)
- 初期境界パラメータ lambda が小さすぎないことを確認してください（典型的な値は 10/15/.. 程度です）。異なるレイヤーに異なる lambda を設定することは可能です。

DeLoRAには現在、以下の制約があります:
- サポートされているのはnn.Linearレイヤーのみです。
- 量子化レイヤーはサポートされていません。

これらの制約が使用ケースに合わない場合は、他の方法を検討してください。

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

> Parameter-Efficient FineTuning (PEFT) 手法は、大規模事前学習モデルの普及により最近大きく注目されています。これらの手法は、最小限の計算コストで下流タスクへの迅速な適応を可能にします。しかし、LoRA などの一般的なファインチューニング手法は、ハイパーパラメータの選択や長期の学習設定に対して頑健性が限られており、そのままの状態で最適なパフォーマンスを発揮することができません。一方、ETHER などの有界アプローチはより高い頑健性を提供しますが、極めて低ランクの適応と固定強度の変換に限定されるため、適応の表現力が低下します。本研究では、学習可能な低ランク行列を正規化およびスケーリングする新しいファインチューニング手法である Decoupled Low-rank Adaptation (DeLoRA) を提案します。変換の距離に上限を設けることで、DeLoRA は角度方向の学習と適応強度を効果的に分離し、パフォーマンスを損なうことなく頑健性を高めます。サブジェクト駆動型画像生成、自然言語理解、および指示チューニングにおける評価を通じて、DeLoRA は競合する PEFT 手法と同等以上のパフォーマンスを示すとともに、より強い頑健性を有することを示しました。

## ベンチマーク概要

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

# API

## DeloraConfig[[peft.DeloraConfig]]

#### peft.DeloraConfig[[peft.DeloraConfig]]

```python
peft.DeloraConfig(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, r: int = 8, delora_lambda: int = 15, module_dropout: float = 0.0, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, bias: Literal['none', 'all', 'delora_only'] = 'none', init_weights: bool = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, rank_pattern: Optional[dict] = <factory>, lambda_pattern: Optional[dict] = <factory>, modules_to_save: Optional[list[str]] = None)
```

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

**パラメータ:**

r (`int`) : DeLoRA アダプターのランク。

delora_lambda (`int`) : DeLoRA アダプターの境界の初期値です。この変数は、重み変更のフロベニウスノルムに上限を設定し、ファインチューニングされたモデルが元のモデルから大きく逸脱することを防ぎます。

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

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

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

bias (`str`) : DeLoRAのバイアスタイプです。'none'、'all'、または'delora_only'を指定できます。'all'または'delora_only'を指定した場合、対応するバイアスが学習中に更新されます。この設定により、アダプターを無効にしても、適応なしのベースモデルが生成する出力と同じ結果は得られない点にご注意ください。

init_weights (`bool`) : アダプター重みの初期化を実行するかどうか。`True`（デフォルト）の場合、A は kaiming uniform 初期化、B はゼロで初期化されます。`False`の場合、A と B の両方が kaiming uniform で初期化され、直ちにゼロでないデルタを寄与します。通常の用途では、この設定は一般的に推奨されません。

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}`。

lambda_pattern (`dict`) : `delora_lambda` で指定されるデフォルトのラムダと異なるラムダを、レイヤー名または正規表現にマッピングする辞書です。例えば、`{'^model.decoder.layers.0.encoder_attn.k_proj': 16}` のように指定します。

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

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

## DeloraModel[[peft.DeloraModel]]

#### peft.DeloraModel[[peft.DeloraModel]]

```python
peft.DeloraModel(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/delora/model.py#L28)

**パラメータ:**

model (`torch.nn.Module`) : 適応させる対象のモデル。

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

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

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

DeLoRAモデル。

事前学習済みのTransformersモデルからDeLoRAモデルを作成します。

この手法の詳細は、[DeLoRA: Decoupled Low-rank Adaptation](https://huggingface.co/papers/2503.18225)に記載されています。

**属性**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) -- 適応させる対象のモデル。
- **peft_config** ([DeloraConfig](/docs/peft/v0.22.0/ja/package_reference/delora#peft.DeloraConfig)): DeLoRAモデルの設定です。

