Hugging Face's logo

PEFT documentation

PSOFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

PSOFT

PSOFT adalah metode fine-tuning yang efisien secara parameter berbasis Orthogonal Fine-Tuning (OFT) yang mempertahankan hubungan geometris dari vektor kolom bobot pre-trained sambil mencapai keseimbangan antara kinerja dan efisiensi multi-dimensi, termasuk jumlah parameter, penggunaan memori, dan biaya komputasi. Dengan membatasi transformasi ortogonal pada subruang utama ber-rank rendah yang diturunkan dari bobot pre-trained, PSOFT menjembatani kesenjangan antara LoRA dan OFT, menyediakan jaminan teoretis sekaligus adaptabilitas praktis. Efektivitasnya divalidasi melalui evaluasi ekstensif pada berbagai benchmark, termasuk GLUE, VTAB-1K, GSM8K, MATH, dan benchmark penalaran umum.

  • Hanya lapisan nn.Linear yang didukung.
  • Lapisan terkuantisasi tidak didukung.

Abstrak dari makalah tersebut adalah:

Dipicu oleh pertumbuhan pesat jumlah parameter model, penyesuaian halus yang efisien secara parameter (PEFT) telah menjadi esensial untuk mengadaptasi model besar ke berbagai tugas turunan di bawah sumber daya komputasi yang terbatas. Dalam paradigma ini, penyesuaian halus ortogonal dan variasinya mempertahankan representasi semantik dari model pra-terlatih, tetapi kesulitan mencapai ekspresivitas dan efisiensi sekaligus dalam hal jumlah parameter, memori, dan komputasi. Untuk mengatasi keterbatasan ini, kami mengusulkan Penyesuaian Halus Ortogonal yang Efisien dengan Adaptasi Subruang Utama (PSOFT), yang membatasi transformasi ortogonal pada subruang utama dari bobot pra-terlatih. Secara spesifik, PSOFT membangun subruang ini melalui dekomposisi matriks untuk memungkinkan transformasi yang kompatibel, menetapkan kondisi teoretis yang secara ketat mempertahankan geometri subruang ini untuk preservasi semantik yang esensial, dan memperkenalkan vektor yang dapat disetel secara efisien yang secara bertahap melonggarkan ortogonalitas selama pelatihan untuk meningkatkan kemampuan adaptasi. Eksperimen ekstensif pada 35 tugas NLP dan CV di empat model representatif menunjukkan bahwa PSOFT menawarkan solusi yang praktis dan dapat diskalakan untuk mencapai preservasi semantik, ekspresivitas, dan efisiensi multi-dimensi secara simultan dalam PEFT.

Cara Kerja PSOFT

PSOFT menguraikan setiap matriks bobot WpreW_{pre} menjadi WpriW_{pri} dan WresW_{res} menggunakan SVD: Wpre=USV⊤W_{\text{pre}} = U S V^\top

Subruang utama Wpri=UrSrVr⊤=ABW_{\text{pri}} = U_r S_r V_r^\top = AB dibangun dari komponen singular teratas-$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 dengan ortogonalitas ketat

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 dengan ortogonalitas yang dilonggarkan

Selama pelatihan, $A$, $B$, dan WresW_{\text{res}} dibekukan, dan hanya RR (atau RR dengan α\alpha dan $\beta$) yang dapat dilatih.

Untuk kompatibilitas dengan kerangka kerja PEFT (yang mengharapkan pembaruan bobot aditif), PSOFT diimplementasikan dalam bentuk aditif berikut: Wps-tuned=Wpre+A(R−Ir)BW_{\text{ps-tuned}} = W_{\text{pre}} + A (R - I_r) B

Parameter yang Dapat Dilatih

Setelah menerapkan PSOFT:

  • Bobot model asli ($A$, $B$, dan $W_{\text{res}}$) dibekukan.
  • Hanya matriks ortogonal RR (dan opsional $\alpha$, $\beta$) yang dapat dilatih.
  • Tidak ada parameter bias tambahan yang diperkenalkan.

Penggunaan Dasar

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)

Opsi Konfigurasi

Mode Berbeda

(PSOFT-SO: PSOFT dengan ortogonalitas ketat)

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

(PSOFT-RO: PSOFT dengan ortogonalitas yang longgar)

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

Praktik Terbaik

  1. Pilihan Rank: Rank yang lebih kecil (misalnya, 32–128) cocok untuk tugas yang lebih sederhana, sedangkan rank yang lebih besar (misalnya, 64–256) memberikan ekspresivitas yang lebih besar untuk tugas yang lebih kompleks dengan biaya peningkatan parameter dan komputasi.
  2. Scaling Factor: Faktor skala biasanya diatur ke rr di PSOFT.
  3. Learning Rate: Gunakan learning rate standar (misalnya, 1e-4 hingga 5e-3) untuk pelatihan yang stabil.
  4. Inisialisasi SVD: Opsi lowrank lebih hemat memori dan komputasi dibandingkan full, sehingga lebih cocok untuk model besar.
  5. Aproximasi Cayley–Neumann: Ketika rank besar, mengaktifkan aproksimasi Cayley–Neumann dapat meningkatkan efisiensi komputasi secara signifikan, sementara manfaatnya kurang terlihat untuk rank kecil. Dalam praktiknya, sejumlah kecil suku deret Neumann (biasanya 5) umumnya memberikan keseimbangan yang baik antara akurasi dan efisiensi.

Ikhtisar benchmark

API

PsoftConfig

kelas 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 )

Parameter

  • r (int) — Nilai default adalah 32. PSOFT rank (r) mengontrol kapasitas adapter melalui transformasi r*r R. Rank yang lebih kecil 32-128 biasanya sudah cukup untuk tugas sederhana, sedangkan tugas yang lebih kompleks mungkin diuntungkan oleh 64-256, meningkatkan ekspresivitas dengan biaya tambahan parameter dan komputasi. Lihat makalah untuk pengaturan yang telah divalidasi secara empiris: https://openreview.net/forum?id=FSHrinMArK.
  • target_modules (Optional[Union[List[str], str]]) — Nama-nama modul yang akan diterapkan adapter-nya. Jika ini ditentukan, hanya modul dengan nama yang ditentukan yang akan diganti. Saat meneruskan string, pencocokan regex akan dilakukan. Saat meneruskan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul diakhiri dengan salah satu string yang diteruskan. Jika ini ditentukan sebagai ‘all-linear’, maka semua modul linear/Conv1D akan dipilih (jika modelnya adalah PreTrainedModel, lapisan output dikecualikan). Jika ini tidak ditentukan, modul akan dipilih sesuai dengan arsitektur model. Jika arsitekturnya tidak diketahui, error akan dilempar — dalam kasus ini, Anda harus menentukan modul target secara manual.
  • exclude_modules (Optional[Union[List[str], str]]) — Nama-nama modul yang tidak akan diterapkan adapter. Saat melewatkan string, pencocokan regex akan dilakukan. Saat melewatkan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul berakhiran dengan salah satu string yang dilewatkan.
  • psoft_alpha (int) — Bawaan 32. Mengontrol faktor penskalaan PSOFT. Semantik yang sama dengan alpha LoRA.
  • psoft_dropout (float) — Defaultnya 0.0. Dropout untuk jalur PSOFT. Semantik yang sama dengan dropout LoRA.
  • fan_in_fan_out (bool) — Atur ini ke True jika layer yang akan diganti menyimpan bobot seperti (fan_in, fan_out). Misalnya, gpt-2 menggunakan Conv1D yang menyimpan bobot seperti (fan_in, fan_out) sehingga ini harus diatur ke True.
  • ab_svd_init (Literal["psoft_init", "pissa_init"]) — Bawaan ‘psoft_init’. Strategi inisialisasi untuk A dan B yang digunakan untuk membangun subruang utama dalam PSOFT. ‘psoft_init’: inisialisasi berbasis SVD dengan A ortogonal-baris, memastikan ortogonalitas ketat (PSOFT). ‘pissa_init’: inisialisasi berbasis SVD dengan A dan B simetris (PiSSA standar).
  • psoft_svd (Literal["full", "lowrank"]) — Bawaan adalah ‘full’. Backend SVD untuk inisialisasi: ‘full’ menggunakan torch.linalg.svd; ‘lowrank’ menggunakan torch.svd_lowrank.
  • psoft_svd_lowrank_niter (int) — Hanya digunakan saat psoft_svd=‘lowrank’. Defaultnya adalah 10. Jumlah iterasi power yang digunakan oleh torch.svd_lowrank ketika psoft_svd=‘lowrank’.
  • psoft_orth (bool) — Bawaan ‘True’. Jika True, membatasi R agar ortogonal melalui parameterisasi Cayley, sehingga menjaga hubungan geometris di antara kolom dari vektor bobot yang telah dilatih sebelumnya. Jika False, R adalah matriks bebas tanpa batasan ortogonalitas.
  • psoft_mag_b (bool) — Bawaan ‘True’. Jika True, mempelajari vektor penskalaan diagonal di sisi ‘output’ dari R. Umumnya dipasangkan dengan psoft_mag_a untuk meningkatkan kemampuan adaptasi tugas, dengan sedikit distorsi pada geometri pra-latih.
  • psoft_mag_a (bool) — Bawaan ‘True’. Jika True, mempelajari vektor penskalaan diagonal di sisi ‘input’ dari R. Umumnya dipasangkan dengan psoft_mag_b untuk meningkatkan kemampuan adaptasi tugas, dengan sedikit distorsi pada geometri pra-latih.
  • use_cayley_neumann (bool) — Bawaan ‘False’. Apakah akan menggunakan formulasi Cayley-Neumann dari PSOFT atau tidak. Atur ke True untuk meningkatkan efisiensi komputasi, namun dengan biaya kesalahan aproksimasi yang lebih besar untuk ortogonalitas.
  • num_cayley_neumann_terms (int) — Bawaan adalah 5. Hanya digunakan saat use_cayley_neumann=True. Jumlah suku Cayley-Neumann yang akan digunakan. Angka yang lebih tinggi menghasilkan kesalahan aproksimasi yang lebih kecil untuk ortogonalitas.
  • cayley_neumann_eps (optional[float]) — Bawaan adalah ‘None’. Hanya digunakan ketika use_cayley_neumann=True. Batas norma Frobenius opsional untuk matriks generator Q dalam aproksimasi Cayley-Neumann. Jika None (bawaan), tidak ada penskalaan ulang yang diterapkan. Jika diatur ke nilai dalam (0, 1) (misalnya, 0.9), Q akan diskala ulang setiap kali ||Q||_F melampaui ambang batas untuk meningkatkan stabilitas numerik. Lihat https://spherelab.ai/oftv2/ untuk detailnya.
  • init_weights (bool) — Bawaan adalah ‘True’. Apakah akan menginisialisasi bobot dari lapisan PSOFT dengan inisialisasi bawaannya. Jangan ubah pengaturan ini, kecuali Anda tahu persis apa yang Anda lakukan.
  • modules_to_save (List[str]) — Daftar modul selain lapisan adapter yang akan diatur sebagai dapat dilatih dan disimpan dalam checkpoint akhir.
  • layers_to_transform (Union[List[int], int]) — Indeks layer yang akan ditransformasi. Jika daftar int yang dilewatkan, adapter akan diterapkan pada indeks layer yang ditentukan dalam daftar ini. Jika satu integer yang dilewatkan, transformasi akan diterapkan pada layer di indeks ini.
  • layers_pattern (Optional[Union[List[str], str]]) — Nama pola layer, hanya digunakan jika layers_to_transform berbeda dari None. Ini harus menargetkan nn.ModuleList dari model, yang sering disebut 'layers' atau 'h'.

Konfigurasi untuk PSOFT (Fine-Tuning Ortogonal Efisien dengan Adaptasi Subruang Utama).

PSOFT menyisipkan transformasi ortogonal r*r R di antara matriks ber-rank rendah A dan B, sehingga pembaruan ber-rank rendah adalah ΔW = B @ (R-I) @ A. Hanya R (dan vektor yang dapat disetel secara opsional) yang dilatih; A dan B diinisialisasi dengan psoft_init (berdasarkan SVD, A ortogonal per baris) dan dibekukan.

PsoftModel

kelas peft.PsoftModel

< >

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

Parameter

  • model — Model yang akan diadaptasi.
  • config — PsoftConfig.
  • adapter_name — Nama adapter, default “default”.
  • low_cpu_mem_usage — Buat bobot adapter kosong di perangkat meta.

Model PSOFT (Efficient Orthogonal Fine-Tuning with Principal Subspace Adaptation).

Menyisipkan transformasi ortogonal (atau berskala) r*r R antara A dan B ber-rank rendah: ΔW = B @ (R-I) @ A. Gunakan ab_svd_init="psoft_init" untuk menginisialisasi A/B dari SVD dan membekukannya, sehingga hanya R (dan vektor magnitudo opsional) yang dilatih.

Update on GitHub

←Polytropon PVeRA→