# C3A: 円周畳み込みによるパラメータ効率の良いファインチューニング

[C3A](https://huggingface.co/papers/2407.19342)は、Circular Convolutionを活用して、合理的なリソースの範囲内で高ランクの適応を実現するパラメータ効率の良いファインチューニング手法です。

C3Aでは、他の手法よりもはるかに大きな学習率（LR）を使用する必要があります。例えば、C3AのLRは1e-1が適切な出発点です。また、はるかに小さいウェイトディケイを使用すべきです。詳細については、`method_comparison`フォルダを参照してください。

`block_size`は、調整可能なパラメータおよびパフォーマンスに影響します。まず、このタスクで使用するLoRAのランクを $r$ とすると、$\frac{\sqrt{d_1 \times d_2}}{r}$ に近い $\mathrm{gcd}(d_1,d_2)$ を選択できます。

C3Aには現在、以下の制約があります:

- サポートされているのは`nn.Linear`レイヤーのみです。
- 量子化レイヤーはサポートされていません。
- ブロックサイズは、対象レイヤーの入力サイズと出力サイズの両方の共通約数である必要があります。

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

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

> Low-Rank Adaptation (LoRA)は、低ランク行列 $\mathbf{A}$ と $\mathbf{B}$ を利用して重みの変化（すなわち $\Delta \mathbf{W} = \mathbf{B} \mathbf{A}$）を表現することで、大規模な基盤モデルのファインチューニングにおいて人気を博しています。この手法は、 $\mathbf{A}$ と $\mathbf{B}$ をアクティベーションと逐次的に掛け合わせることで、学習可能なパラメータを削減し、フルデルタ行列に伴う重いメモリ消費を軽減します。その成功にもかかわらず、本質的な低ランク特性がパフォーマンスを制限する可能性があります。この問題に対処するためにいくつかのバリアントが提案されていますが、それらはしばしばLoRAがもたらす重要な計算効率とメモリ効率を見落としています。本論文では、Circular Convolution Adaptation (C3A)を提案します。C3Aは、パフォーマンスを向上させた高ランク適応を実現するだけでなく、計算能力とメモリ利用の両面でも優れた性能を発揮します。広範な実験により、C3Aはさまざまなファインチューニングタスクにおいて、LoRAとそのバリアントを一貫して上回るパフォーマンスを示すことが実証されました。

## ベンチマーク概要

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

# API

## C3AConfig[[peft.C3AConfig]]

#### peft.C3AConfig[[peft.C3AConfig]]

```python
peft.C3AConfig(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, block_size: int = 256, target_modules: Optional[Union[list[str], str]] = None, bias: str = 'none', modules_to_save: Optional[list[str]] = None, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, block_size_pattern: Optional[dict] = <factory>, init_weights: Optional[Union[bool, Literal['gaussian', 'kaiming_uniform', 'xavier_uniform']]] = 'xavier_uniform')
```

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

**パラメータ:**

block_size (`int`) : C3Aのブロックサイズです。ターゲット層の入力サイズおよび出力サイズの両方で割り切れる必要があります。block_sizeにどの値を設定すべきか分からない場合は、ターゲット層すべての入力サイズと出力サイズの最大公約数に設定してください。この値を大きくすると、パラメータ数が減少します。

target_modules (`Union[list[str],str]`) : C3Aを適用するモジュールの名前。

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

modules_to_save (`list[str]`) -- C3A層を除き、最終チェックポイントに保存されるように学習可能に設定するモジュールのリスト。

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

layers_pattern (`str`) : レイヤーパターン名。`layers_to_transform`が`None`と異なり、かつレイヤーパターンが共通のレイヤーパターンに含まれない場合にのみ使用されます。

block_size_pattern (`dict`) : 既定値と異なるブロックサイズを持つ、レイヤー名または正規表現からblock_sizeへのマッピング。例えば、`{"model.decoder.layers.0.encoder_attn.k_proj": 1280`}

init_weights (`Union[bool, Literal["gaussian", "kaiming_uniform", "xavier_uniform"]]`) : デフォルトは 'xavier_uniform' です。`False` に設定した場合も 'xavier_uniform' が使用されます。重みをゼロに設定して C3A を何もしない状態（no-op）にするには、値を `True` に設定してください。

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

## C3AModel[[peft.C3AModel]]

#### peft.C3AModel[[peft.C3AModel]]

```python
peft.C3AModel(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/c3a/model.py#L29)

**パラメータ:**

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

config ([C3AConfig](/docs/peft/main/ja/package_reference/c3a#peft.C3AConfig)) : C3Aモデルの設定です。

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

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

C3Aモデル。

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

この手法の詳細は、https://huggingface.co/papers/2407.19342 に記載されています。

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