PEFT documentation

PSOFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

PSOFT

PSOFTは、事前学習済み重みの列ベクトルの幾何学的関係を保持しつつ、パラメータ数、メモリ使用量、計算コストといった多次元的な効率性との間でバランスの取れたトレードオフを実現する、直交ファインチューニング(OFT)に基づくパラメータ効率の良いファインチューニング手法です。直交変換を事前学習済み重みから導出される低ランクの主部分空間に限定することで、PSOFTはLoRAとOFTの間のギャップを埋め、理論的な保証と実用的な適応性の両方を提供します。その有効性は、GLUE、VTAB-1K、GSM8K、MATH、および常識推論ベンチマークを含む多様なベンチマークにおける広範な評価を通じて検証されています。

  • サポートされているのはnn.Linearレイヤーのみです。
  • 量子化レイヤーはサポートされていません。

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

モデルのパラメータの急速な増加に伴い、計算リソースが制約された環境で大規模モデルを多様な下流タスクに適応させるために、パラメータ効率の良いファインチューニング(PEFT)が不可欠になっています。このパラダイムにおいて、直交ファインチューニングとその変種は事前学習モデルの意味的表現を保持しますが、パラメータ数、メモリ、計算量という観点から表現力と効率性の両立に苦戦しています。この限界を克服するために、本研究では、事前学習重みの主部分空間に直交変換を限定する効率的な直交ファインチューニング、PSOFT(Principal Subspace adaptation)を提案します。具体的には、PSOFTは行列分解を用いてこの部分空間を構築し、互換性のある変換を可能にするとともに、本質的な意味の保持のためにこの部分空間の幾何学的構造を厳密に維持する理論的条件を確立し、さらに訓練中に直交性を徐々に緩和して適応性を高める効率的な調整可能ベクトルを導入します。4つの代表的なモデルにおける35のNLPおよびCVタスクに対する広範な実験により、PSOFTがPEFTにおいて意味の保持、表現力、多次元的な効率性を同時に達成するための実用的かつスケーラブルなソリューションを提供することが示されました。

PSOFTの仕組み

PSOFT は各重み行列 WpreW_{pre} を WpriW_{pri} と WresW_{res} SVD を用いて分解します: Wpre=USV⊤W_{\text{pre}} = U S V^\top

主部分空間 Wpri=UrSrVr⊤=ABW_{\text{pri}} = U_r S_r V_r^\top = AB は上位 $r$ 個の固有成分から構成されます:

Wpre=Wpri+Wres=AB+Wres,W_{\text{pre}} = W_{\text{pri}} + W_{\text{res}} = AB + W_{\text{res}},

Wps-tuned=ARB+Wres.W_{\text{ps-tuned}} = ARB + W_{\text{res}}. (PSOFT-SO: 厳密な直交性を備えた PSOFT

Wps-tuned=A diag(α) R diag(β) B+Wres.W_{\text{ps-tuned}} = A \, \mathrm{diag}(\alpha) \, R \, \mathrm{diag}(\beta) \, B + W_{\text{res}}. (PSOFT-RO: 直交性を緩和した PSOFT

学習中、$A$、$B$、および WresW_{\text{res}} は凍結され、 RR (または RR の α\alpha および $\beta$ を持つ $R$) のみが学習可能です。

PEFT フレームワーク(加法的な重み更新を想定している)との互換性のために、PSOFT は以下の加法的な形式で実装されています: Wps-tuned=Wpre+A(R−Ir)BW_{\text{ps-tuned}} = W_{\text{pre}} + A (R - I_r) B

学習可能なパラメータ

PSOFTを適用した後:

  • 元のモデルの重み($A$、$B$、および$W_{\text{res}}$)は固定されます。
  • 直交行列 RR (および任意の $\alpha$、$\beta$ のみが学習可能です。
  • 追加のバイアスパラメータは導入されません。

基本的な使用方法

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PsoftConfig, get_peft_model

# Load base model
model_id = "facebook/opt-125m"
model = AutoModelForCausalLM.from_pretrained(model_id)

# Configure PSOFT
config = PsoftConfig(
    r=32,                                   # the dimension of trainable matrix R,
    psoft_alpha=32,                         # scaling factor (typically set to r in PSOFT),
    target_modules=["q_proj", "v_proj"],    # target attention projection layers
    ab_svd_init="psoft_init",        # principal subspace initialization
    psoft_svd="full",                       # SVD method
    psoft_orth=True,                        # enable orthogonal R (Cayley parameterization)
    psoft_mag_a=True,                       # enable tunable vector alpha
    psoft_mag_b=True,                       # enable tunable vector beta
    use_cayley_neumann=False,               # disable Cayley–Neumann approximation
    num_cayley_neumann_terms=5,             # number of Neumann series terms
    cayley_neumann_eps=None,                # improve numerical stability
)

# Apply PSOFT
model = get_peft_model(model, config)
model.train()

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

# Train
inputs = tokenizer("Hello world", return_tensors="pt", padding=True)
loss = model(**inputs, labels=inputs["input_ids"]).loss
loss.backward()

trainable = [p for p in model.parameters() if p.requires_grad]
optimizer = torch.optim.AdamW(trainable, lr=5e-4)
optimizer.step()
optimizer.zero_grad(set_to_none=True)

設定オプション

異なるモード

(PSOFT-SO: 厳密な直交性を持つ PSOFT)

config = PsoftConfig(psoft_orth=True,psoft_mag_a=False,psoft_mag_b=False)

(PSOFT-RO: 直交性の制約を緩和したPSOFT)

config = PsoftConfig(psoft_orth=True,psoft_mag_a=True,psoft_mag_b=True)

ベストプラクティス

  1. ランクの選択: 単純なタスクには小さいランク(例: 32–128)が適していますが、より複雑なタスクでは、パラメータ数と計算量の増加を代償に、より高い表現力をもたらす大きいランク(例: 64–256)が有効です。
  2. Scaling Factor: スケーリングファクターは通常、 rr PSOFTでは に設定されます。
  3. 学習率: 安定した学習のために、標準的な学習率(例: 1e-4 から 5e-3)を使用します。
  4. SVD 初期化: lowrank オプションは full よりもメモリと計算効率が良いため、大規模モデルに適しています。
  5. Cayley–Neumann Approximation: ランクが大きい場合、Cayley–Neumann近似を有効にすると計算効率を大幅に向上させることができますが、ランクが小さい場合はその効果が限定的です。実際には、Neumann級数の少数の項(通常5)を使用することで、精度と効率の間に良好なバランスを実現できます。

ベンチマーク概要

API

PsoftConfig

クラス peft.PsoftConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 32target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonepsoft_alpha: int = 32psoft_dropout: float = 0.0fan_in_fan_out: bool = Falseab_svd_init: Literal['psoft_init', 'pissa_init'] = 'psoft_init'psoft_svd: Literal['full', 'lowrank'] = 'full'psoft_svd_lowrank_niter: int = 10random_seed: int = 0psoft_orth: bool = Truepsoft_mag_b: bool = Truepsoft_mag_a: bool = Trueuse_cayley_neumann: bool = Falsenum_cayley_neumann_terms: int = 5cayley_neumann_eps: Optional[float] = Nonemodules_to_save: Optional[list[str]] = Noneinit_weights: bool = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = None )

パラメータ

  • r (int) — デフォルト値は 32 です。PSOFT ランク (r) は、r*r 変換 R を通じてアダプタの容量を制御します。単純なタスクには通常、32〜128 の小さいランクで十分ですが、より複雑なタスクでは 64〜256 を使用することで、追加のパラメータと計算コストを代償に表現力を高めることができます。実証的に検証された設定については、論文を参照してください: https://openreview.net/forum?id=FSHrinMArK。
  • target_modules (Optional[Union[List[str], str]]) — アダプタを適用するモジュールの名前です。このパラメータが指定されている場合、指定された名前のモジュールのみが置き換えられます。文字列を渡す場合、正規表現によるマッチングが行われます。文字列のリストを渡す場合、完全一致が行われるか、モジュール名が渡された文字列のいずれかで終わるかがチェックされます。このパラメータが ‘all-linear’ として指定されている場合、すべての linear/Conv1D モジュールが選択されます(モデルが PreTrainedModel の場合、出力層は除外されます)。このパラメータが指定されていない場合、モデルのアーキテクチャに基づいてモジュールが選択されます。アーキテクチャが不明な場合、エラーが発生します — この場合、ターゲットモジュールを手動で指定する必要があります。
  • exclude_modules (Optional[Union[List[str], str]]) — アダプタを適用しないモジュールの名前。文字列を渡す場合、正規表現によるマッチングが行われます。文字列のリストを渡す場合、完全一致が行われるか、モジュール名が渡された文字列のいずれかで終わるかがチェックされます。
  • psoft_alpha (int) — デフォルト値は 32 です。PSOFT のスケーリング係数を制御します。LoRA の alpha と同じ意味論です。
  • psoft_dropout (float) — デフォルト値は 0.0 です。PSOFT パス用の Dropout。LoRA の Dropout と同じセマンティクスです。
  • fan_in_fan_out (bool) — 置き換えるレイヤーが重みを (fan_in, fan_out) の形式で保存している場合は、これを True に設定してください。例えば、gpt-2 は重みを (fan_in, fan_out) の形式で保存する Conv1D を使用しているため、これを True に設定する必要があります。
  • ab_svd_init (Literal["psoft_init", "pissa_init"]) — デフォルトは ‘psoft_init’ です。PSOFT で主部分空間を構築するために A と B に使用される初期化戦略です。‘psoft_init’: 行直交な A を持つ SVD ベースの初期化で、厳密な直交性を保証します (PSOFT)。‘pissa_init’: 対称な A と B を持つ SVD ベースの初期化 (標準的な PiSSA)。
  • psoft_svd (Literal["full", "lowrank"]) — デフォルトは ‘full’ です。初期化に使用する SVD バックエンドを指定します。‘full’ は torch.linalg.svd を使用し、‘lowrank’ は torch.svd_lowrank を使用します。
  • psoft_svd_lowrank_niter (int) — psoft_svd=‘lowrank’ の場合のみ使用されます。デフォルト値は 10 です。psoft_svd=‘lowrank’ の場合、torch.svd_lowrank によって使用されるべき乗反復の回数です。
  • psoft_orth (bool) — デフォルト値は ‘True’ です。True の場合、Cayley パラメータ化を用いて R が直交行列であることを制約し、事前学習済み重みベクトルの各列間の幾何学的な関係を保持します。False の場合、R は直交性の制約なしの自由行列となります。
  • psoft_mag_b (bool) — デフォルト値は ‘True’ です。True の場合、R の ‘output’ 側に対角スケーリングベクトルを学習します。事前学習された幾何構造にわずかな歪みが生じますが、タスクへの適応性を高めるために psoft_mag_a と組み合わせて使用されることが一般的です。
  • psoft_mag_a (bool) — デフォルト値は ‘True’ です。True の場合、R の ‘input’ 側で対角スケーリングベクトルを学習します。事前学習された幾何構造にわずかな歪みが生じますが、タスクへの適応性を高めるために psoft_mag_b と組み合わせて使用されることが一般的です。
  • use_cayley_neumann (bool) — デフォルト値は ‘False’ です。PSOFT の Cayley-Neumann 表現を使用するかどうかを指定します。True に設定すると計算効率を向上させることができますが、直交性に対する近似誤差が大きくなるというコストが発生します。
  • num_cayley_neumann_terms (int) — デフォルト値は5です。use_cayley_neumann=Trueの場合にのみ使用されます。使用するCayley-Neumann項の数です。数値を大きくすると、直交性に対する近似誤差が小さくなります。
  • cayley_neumann_eps (optional[float]) — デフォルト値は ‘None’ です。use_cayley_neumann=True の場合にのみ使用されます。Cayley-Neumann 近似における生成行列 Q の Frobenius ノルムの上限をオプションで指定します。None (デフォルト) の場合、リスケールは適用されません。(0, 1) の値 (例: 0.9) に設定した場合、||Q||_F が閾値を超えた際に Q がリスケールされ、数値的安定性が向上します。詳細は https://spherelab.ai/oftv2/ を参照してください。
  • init_weights (bool) — デフォルト値は ‘True’ です。PSOFT 層の重みをデフォルトの初期化で初期化するかどうかを指定します。正確に意図している場合を除き、この設定を変更しないでください。
  • modules_to_save (List[str]) — 最終チェックポイントに保存されるよう、学習可能に設定するアダプタ層以外のモジュールのリスト。
  • layers_to_transform (Union[List[int], int]) — 変換対象のレイヤーのインデックスです。int のリストが渡された場合、このリストに指定されたレイヤーのインデックスにアダプターが適用されます。単一の整数が渡された場合、そのインデックスのレイヤーに変換が適用されます。
  • layers_pattern (Optional[Union[List[str], str]]) — layers_to_transform が None と異なる場合にのみ使用されるレイヤーパターン名です。これはモデルの nn.ModuleList を対象とすべきで、通常は 'layers' または 'h' と呼ばれます。

PSOFT(Principal Subspace Adaptationによる効率的な直交ファインチューニング)の設定。

PSOFTは、低ランク行列AとBの間にr*rの直交変換Rを挿入します。これにより、低ランク更新はΔW = B @ (R-I) @ Aとなります。学習されるのはR(および任意の調整可能なベクトル)のみで、AとBはpsoft_init(SVDベース、行直交のA)で初期化され、固定されます。

PsoftModel

クラス peft.PsoftModel

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

パラメータ

  • model — 適応させるモデル。
  • config — PsoftConfig。
  • adapter_name — アダプター名。デフォルトは “default” です。
  • low_cpu_mem_usage — メタデバイス上に空のアダプター重みを生成します。

PSOFT (Principal Subspace Adaptationによる効率的な直交ファインチューニング)モデル。

低ランクのAとBの間にr*rの直交(またはスケーリング)変換Rを挿入します: ΔW = B @ (R-I) @ A。 ab_svd_init=“psoft_init” を使用してA/BをSVDから初期化し、それらを凍結して、R(および任意のmagnitudeベクトル)のみを学習します。

Update on GitHub