# PaCA: Partial Connection Adaptation

[PaCA](https://huggingface.co/papers/2503.01905)（ICLR 2025）は、学習速度とアクティベーションメモリをターゲットとするPEFT手法です。各ターゲットとなる事前学習済み重みの、ランダムに選択された`r`個の入力列（「部分接続」）をファインチューニングします。学習可能なパラメータはこれらの列の更新のみであり、LoRAとは異なり、PaCAは追加の低ランク行列を一切加えません。

LoRAのような手法は、事前学習済みレイヤーの隣に小さな低ランクのブランチを実行します。このブランチはFLOPsをほとんど必要としませんが、事前学習済みレイヤーと逐次実行され、バックワードパスのために入力活性化の独自のコピーを保持します。PaCAはこれら両方を回避します：

- **レイヤーごとに1回のGEMM。** 適応された列は、事前学習済み重数のmatmul直前に書き込まれ、直後に復元されるため、フォワードとバックワードはそれぞれ単一のmatmulを実行し、凍結されたベースレイヤーと完全に同じ動作になります。
- **部分活性化。**適応された列の勾配は、対応する`r`個の入力チャネルにのみ依存するため、バックワードパスでは完全な入力の代わりに、それらのチャネルのみが保存されます。

結果として得られる重みの観点では、PaCA アダプターは、`A` 行列が固定された列セレクターであるランク `r` の LoRA アダプターと同等です: `W' = W + delta @ S`。ここで `S` は `r` 列を選択します。したがって、[convert_to_lora()](/docs/peft/main/ja/package_reference/lora_conversion#peft.convert_to_lora) を使用して、例えば LoRA 推論スタックでサーブするために、損失なくランク `r` の LoRA アダプターに変換できます。

PaCAを使用するタイミング:

- LoRAレベルの精度を維持しつつ、より高速なファインチューニングステップと低いアクティベーションメモリを必要とする場合（例: 同じGPU上でより長いシーケンスやより大きなバッチを処理したい場合）に適用します。
- ベースの重みに正確にマージされるアダプター（更新が通常の列更新である）が必要です。

現在の制約:

- サポートされているのは`nn.Linear`レイヤー（量子化された線形レイヤーを含む）のみです。
- PaCAはベースレイヤーの`forward`を呼び出すのではなく、matmul自体を実行するため、ベースレイヤーに登録されたforwardフックは呼び出されません（警告が出力されます）。代わりに、PaCAレイヤーにフックを登録してください。
- ミックスされたアダプターバッチ(`adapter_names`引数)はサポートされていません。
- sharded weights（FSDP、DeepSpeed ZeRO-3）を用いたトレーニングは、まだテストされていません。
- `torch.compile` はサポートされています。コンパイル下では、カラムスワップ、matmul、およびリストアが不透明なカスタムオペレーション（`torch.ops.peft.paca_linear_forward`/`_backward`）として実行されるため、コンパイラはベースの重みをコピーしません。これには `torch.library.custom_op`（PyTorch >= 2.4）が必要です。それ以外の場合は、eager 実装がトレースされます。
- `paca_alpha / r`はカラムの更新をスケーリングするため、実質的な学習率の乗数として機能します。
- 推論では、アダプタをマージしてください（`merge_and_unload()`）。マージされていない forward は、呼び出しのたびにカラムを切り替えます。

## 使用方法

```python
from transformers import AutoModelForCausalLM
from peft import PacaConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-3B")
config = PacaConfig(r=16, paca_alpha=16, target_modules="all-linear", random_seed=0)
model = get_peft_model(model, config)
model.print_trainable_parameters()
```

デフォルトでは、対象の各レイヤーは`r`列をランダムに選択してファインチューニングします。論文では、この方法は重みのノルムまたは累積勾配に基づいて列を選択する方法と同等の性能を示しました。別の選択戦略を試す場合や、レイヤーごとの列数を異なるものにする場合は、`paca_indices_pattern`を渡します。そのキーは、LoRAの`rank_pattern`と同様に、レイヤー名または正規表現です。

```python
config = PacaConfig(
    r=16,
    paca_alpha=16,
    target_modules=["q_proj", "v_proj"],
    paca_indices_pattern={"layers.0.self_attn.q_proj": [0, 2, 4, 6], "layers.1.self_attn.v_proj": list(range(32))},
)
```

キーに一致するレイヤーは指定された列をファインチューニングし、その他の対象レイヤーは`r`個のランダムな列を選択します。スケーリングは`paca_alpha / r`であり、すべてのレイヤーで設定の`r`を使用するため、`paca_alpha`はすべてのレイヤーで同じ意味を持ちます。

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

> 従来のパラメータ効率型ファインチューニング（PEFT）アルゴリズムは、モデル全体ではなく、追加の少数のアダプタパラメータのみを学習させることで、大規模ニューラルネットワークモデルのファインチューニングにおけるメモリ使用量と計算コストを削減します。しかし、PEFTによる計算コストの削減が必ずしもトレーニング時間の短縮に直結するとは限りません。アダプタ層の計算コストは事前学習済み層よりもはるかに小さいものの、これら2種類の層はGPU上で逐次処理されることが広く知られており、これが大きなレイテンシオーバーヘッドを生み出します。LoRAとそのバリアントは、推論時に低ランクのアダプタ行列を事前学習済み重みとマージすることで、このレイテンシオーバーヘッドを回避します。ただし、トレーニング中は事前学習済み重みを凍結したまま低ランクのアダプタ行列を継続的に更新する必要があるため、これらの層をマージすることはできません。さらに、LoRAとそのバリアントは、最初の低ランクアダプタ行列が重み勾配の計算に事前学習済み重みの入力活性化を必要とするため、活性化メモリを削減しません。この問題を緩和するために、私たちは、モデルにアダプタ層を導入するのではなく、事前学習済み重み内のランダムに選択された部分接続をファインチューニングする Partial Connection Adaptation (PaCA) を提案します。PaCA は、アダプタ層と事前学習済み層の逐次処理による時間オーバーヘッドを排除することでトレーニング速度を向上させるだけでなく、勾配計算のためにフル活性化ではなく部分活性化のみを保存すればよいため、活性化メモリも削減します。LoRA と比較して、PaCA は MMLU データセットでのファインチューニングや Oasst1 データセットでのインストラクションチューニングなど、さまざまなファインチューニングシナリオにおいて同等の精度を維持しながら、トレーニング時間を 22%、総メモリ使用量を 16% 削減します。また、PaCA は量子化と組み合わせることができ、LLaMA3.1-70B のような大規模モデルのファインチューニングを可能にします。さらに、LoRA と比較して、PaCA は NVIDIA A100 GPU および INTEL Gaudi2 HPU の両方で、シーケンス長を 23% 長くしてトレーニングでき、スループットを 16% 向上させます。

## ベンチマーク概要

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

# API

## PacaConfig[[peft.PacaConfig]]

#### peft.PacaConfig[[peft.PacaConfig]]

```python
peft.PacaConfig(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, paca_alpha: int = 8, target_modules: list[str] | str | None = None, exclude_modules: list[str] | str | None = None, layers_to_transform: list[int] | int | None = None, layers_pattern: list[str] | str | None = None, random_seed: int | None = None, paca_indices_pattern: dict | None = <factory>, init_weights: bool = True, modules_to_save: list[str] | None = None)
```

[ソース](https://github.com/huggingface/peft/blob/main/src/peft/tuners/paca/config.py#L23)

**パラメータ:**

r (`int`、*optional*、デフォルトは`8`) : 各対象レイヤーでファインチューニングされる入力列（部分接続）の数。形状が`(out_features, in_features)`の重みに対して、PaCAは`r * out_features`個のパラメータを学習します。これは、ランク`r`のLoRAアダプタの`B`行列のパラメータ数と同じです。`in_features`を超えることはできません。

paca_alpha (`int`、*任意*、デフォルトは`8`) : スケーリング係数。選択されたカラムの更新量は`paca_alpha / r * delta`です。`lora_alpha`と同様に、アダプタの有効な学習率の乗数として機能します。

target_modules (`Union[list[str], str]`, *任意*) : PaCA に置き換えるモジュール名のリスト、またはモジュール名の正規表現です。例えば、`['q_proj', 'v_proj']`や`'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'`などです。これを`'all-linear'`として指定すると、出力層を除くすべての線形モジュールが選択されます。サポートされるのは`nn.Linear`レイヤーのみです。

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

layers_to_transform (`Union[list[int], int]`, *オプション*) : 変換するレイヤーのインデックスです。この引数が指定されている場合、PEFT はこのリスト内で指定されたレイヤーインデックスのみを変換します。単一の整数が渡された場合、PEFT はそのインデックスのレイヤーのみを変換します。

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

random_seed (`int`, *任意*, デフォルトは `None`) : 部分接続を選択するために使用されるシード。各レイヤーは、このシードとレイヤー名から導出された異なる選択を使用します。`None` の場合、グローバルな torch ランダム数生成器が使用されます。選択されたインデックスは常にアダプターチェックポイントに保存されるため、学習済みアダプターを読み込む際にシードは必要ありません。

paca_indices_pattern (`dict`, *任意*) : レイヤー名または正規表現から、ランダムに選択される `r` 列の代わりに、一致するレイヤーでファインチューニングされる入力列のインデックスへの任意のマッピングです。例えば `{'^model.layers.0.self_attn.q_proj': [0, 2, 4]}` のように指定できます。これにより、レイヤーごとに異なる数の列を指定することも可能です。レイヤーのインデックスは一意で、かつ `in_features` より小さい必要があります。スケーリングは、指定されたインデックスの数に関係なく、すべてのレイヤーでこの設定の `r` を用いて `paca_alpha / r` となります。キーに一致しないターゲットレイヤーでは、`r` 列がランダムに選択されます。

init_weights (`bool`、*任意*、デフォルトは`True`) : `True`の場合、選択されたカラムの更新がゼロに初期化され、つまり適応されたモデルは初期化時点でベースモデルと同一になります。`False`に設定すると、ランダムな値で初期化されます。これはテスト目的でのみ使用することを意図しています。

modules_to_save (`list[str]`, *任意*) : PaCA層を除き、最終チェックポイントで学習可能かつ保存されるように設定するモジュールのリストです。例えば、シーケンス分類やトークン分類タスクでは、最終層の`classifier/score`がランダムに初期化されるため、学習可能かつ保存される必要があります。

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

PaCA (Partial Connection Adaptation, https://huggingface.co/papers/2503.01905) は、対象となる事前学習済み重みの各々からランダムに選択された `r` 個の入力列（部分接続）をファインチューニングします。学習可能なパラメータはこれらの列の更新のみであり、LoRA とは異なり、PaCA は追加の低ランク行列を一切加えません。行列積の直前に適応された列が事前学習済み重みにスワップインされ、直後に元に戻されるため、フォワードパスとバックワードパスのそれぞれで単一の GEMM が実行され、バックワードパスでは選択された `r` 個の入力チャネルのみがメモリに保持されます。

## PacaModel[[peft.PacaModel]]

#### peft.PacaModel[[peft.PacaModel]]

```python
peft.PacaModel(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/main/src/peft/tuners/paca/model.py#L38)

**パラメータ:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : 適応させる対象のモデル。

config ([PacaConfig](/docs/peft/main/ja/package_reference/paca#peft.PacaConfig)) : PaCAモデルの設定です。

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

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

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

PaCAモデル。

事前学習済みモデルからPartial Connection Adaptation (PaCA)モデルを作成します。この手法はhttps://huggingface.co/papers/2503.01905に記載されています。

例:

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import PacaConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = PacaConfig(r=16, paca_alpha=16, target_modules="all-linear")
>>> model = get_peft_model(base_model, config)
```

**属性**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- 適応させる対象のモデル。
- **peft_config** ([PacaConfig](/docs/peft/main/ja/package_reference/paca#peft.PacaConfig)): PaCAモデルの設定です。

