Hugging Face's logo

PEFT documentation

AdaMSS

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

AdaMSS

AdaMSS (AdaMSS: Adaptive Multi-Subspace Approach for Parameter-Efficient Fine-Tuning) adalah metode fine-tuning yang efisien secara parameter, yang menguraikan matriks bobot menggunakan SVD dan mengelompokkan ruang yang diuraikan tersebut menjadi beberapa subspace yang dapat dilatih. Setiap subspace mempelajari pembaruan ber-rank rendah yang independen, sementara bobot asli tetap dibekukan. AdaMSS juga mendukung Adaptive Subspace Allocation (ASA), yang memangkas subspace yang kurang penting secara dinamis selama pelatihan berdasarkan informasi gradien.

Abstrak dari makalah tersebut adalah:

Kami mengusulkan AdaMSS, sebuah pendekatan multi-subruang adaptif untuk penyesuaian halus (fine-tuning) yang efisien parameter pada model besar. Berbeda dengan metode penyesuaian halus efisien parameter tradisional yang beroperasi di dalam satu subruang besar dari bobot jaringan, AdaMSS memanfaatkan segmentasi subruang untuk memperoleh beberapa subruang yang lebih kecil dan secara adaptif mengurangi jumlah parameter yang dapat dilatih selama pelatihan, pada akhirnya hanya memperbarui parameter yang terkait dengan subset kecil subruang yang paling relevan untuk tugas hilir (downstream) target. Dengan menggunakan representasi peringkat terendah (lowest-rank), AdaMSS mencapai ekspresivitas yang lebih ringkas dan penyesuaian yang lebih halus pada parameter model. Analisis teoretis menunjukkan bahwa AdaMSS memiliki jaminan generalisasi yang lebih baik daripada LoRA, PiSSA, dan metode berbasis peringkat rendah (low-rank) subruang tunggal lainnya. Eksperimen ekstensif di berbagai tugas klasifikasi gambar, pemahaman bahasa alami, dan generasi bahasa alami menunjukkan bahwa AdaMSS mencapai kinerja yang sebanding dengan penyesuaian halus penuh (full fine-tuning) dan melampaui metode penyesuaian halus efisien parameter lainnya dalam kebanyakan kasus, semuanya sambil membutuhkan lebih sedikit parameter yang dapat dilatih. Secara khusus, pada model ViT-Large, AdaMSS mencapai akurasi rata-rata 4,7% lebih tinggi daripada LoRA di tujuh tugas, dengan hanya menggunakan 15,4% dari parameter yang dapat dilatih. Pada RoBERTa-Large, AdaMSS melampaui PiSSA dengan 7% dalam akurasi rata-rata di enam tugas sambil mengurangi jumlah parameter yang dapat dilatih sekitar 94,4%. Hasil-hasil ini menunjukkan efektivitas AdaMSS dalam penyesuaian halus yang efisien parameter. Kode untuk AdaMSS tersedia di https: //github.com/jzheng20/AdaMSS.

Saat ini, AdaMSS memiliki batasan berikut:

  • Hanya lapisan nn.Linear yang didukung.
  • Memerlukan scikit-learn untuk langkah pengelompokan KMeans.

Jika batasan-batasan ini tidak sesuai dengan kasus penggunaan Anda, pertimbangkan metode lain sebagai gantinya.

Ikhtisar benchmark

API

AdamssConfig

kelas peft.AdamssConfig

< >

( 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 = 100num_subspaces: int = 5subspace_rank: int = 1target_modules: Optional[Union[list[str], str]] = Noneinit_weights: Optional[Literal['orthogonal']] = 'orthogonal'modules_to_save: Optional[list[str]] = Nonelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Noneuse_asa: bool = Falseasa_target_subspaces: int = 50init_warmup: int = 50final_warmup: int = 1000mask_interval: int = 100asa_importance_beta: float = 0.85asa_uncertainty_beta: float = 0.85asa_schedule_exponent: float = 3.0use_dynamic_rank: bool = Falsesvd_threshold: float = 0.1random_seed: int = 0 )

Parameter

  • r (int) — Total rank untuk dekomposisi SVD (dilambangkan sebagai R dalam makalah). Nilai ini menentukan berapa banyak vektor singular yang digunakan untuk merepresentasikan matriks bobot sebelum pengelompokan. Nilai yang lebih tinggi menangkap lebih banyak informasi dari bobot asli tetapi memerlukan lebih banyak komputasi dan memori. Nilai yang lebih rendah memberikan regularisasi yang lebih kuat. Nilai tipikal berkisar dari 50 hingga 500. Nilai default adalah 100.
  • num_subspaces (int) — Jumlah subspace (K) untuk mengklasterkan ruang yang didekomposisi SVD. Setiap subspace mempelajari pembaruan ber-rank rendah yang independen. Meningkatkan nilai ini memungkinkan adaptasi yang lebih rinci, tetapi meningkatkan jumlah parameter yang dapat dilatih secara proporsional. Saat menggunakan ASA (Adaptive Subspace Allocation), nilai ini menentukan jumlah subspace awal sebelum pruning. Nilai tipikal berkisar dari 3 hingga 10. Nilai default adalah 5.
  • subspace_rank (int) — Rank (r_i) untuk setiap subspace yang dapat dilatih. Ini mengontrol kapasitas setiap subspace untuk mempelajari adaptasi. Nilai yang lebih tinggi meningkatkan ekspresivitas tetapi juga meningkatkan jumlah parameter yang dapat dilatih. Total parameter yang dapat dilatih berskala sebagai O(num_subspaces subspace_rank (in_dim + out_dim) / num_subspaces). Untuk sebagian besar tugas, nilai 1-4 bekerja dengan baik. Default adalah 1.
  • target_modules (Optional[Union[list[str], str]]) — Nama-nama modul yang akan diterapkan AdaMSS. Jika ditentukan, hanya modul-modul ini yang akan diadaptasi. Dapat berupa daftar nama modul yang persis atau ekspresi regex. Misalnya, ['q_proj', 'v_proj'] untuk lapisan attention, atau '.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$' untuk pencocokan regex.
  • modules_to_save (Optional[list[str]]) — Daftar modul di luar lapisan AdaMSS yang akan diset sebagai trainable dan disimpan dalam checkpoint akhir. Modul-modul ini akan di-fine-tune secara penuh (bukan hanya low-rank). Diperlukan untuk head yang diinisialisasi secara acak seperti classifier atau score dalam tugas klasifikasi.
  • init_weights (Literal["orthogonal"]) — Metode inisialisasi untuk bobot yang dapat dilatih pada AdaMSS. Saat ini hanya “orthogonal” yang didukung, yang menggunakan inisialisasi ortogonal untuk matriks B (proyeksi output). Matriks A diinisialisasi ke nol untuk memastikan model dimulai dari bobot pretrained. Atur ke None untuk melewati inisialisasi saat memuat dari checkpoint. Default adalah “orthogonal”.
  • layers_to_transform (Optional[Union[list[int], int]]) — Indeks lapisan spesifik untuk menerapkan AdaMSS. Jika ditentukan, hanya lapisan-lapisan ini yang akan diadaptasi, berguna untuk mencoba lapisan mana yang paling diuntungkan dari adaptasi. Dapat berupa satu bilangan bulat atau daftar bilangan bulat.
  • layers_pattern (Optional[Union[list[str], str]]) — Pola untuk mencocokkan nama layer ketika layers_to_transform ditentukan. Digunakan untuk mengekstrak indeks layer dari nama modul yang tidak mengikuti pola umum.
  • use_asa (bool) — Apakah akan mengaktifkan Adaptive Subspace Allocation (ASA). Saat diaktifkan, ASA secara dinamis memangkas subspace yang kurang penting selama pelatihan berdasarkan informasi gradien, mengurangi jumlah parameter efektif sambil mempertahankan kinerja. Memerlukan integrasi dengan callback pelatihan. Default adalah False.
  • asa_target_subspaces (int) — Total target jumlah subspace aktif di semua lapisan ketika ASA diaktifkan. ASA akan memangkas subspace secara bertahap hingga target ini tercapai. Nilai yang lebih rendah menghasilkan pemangkasan yang lebih agresif dan jumlah parameter yang dapat dilatih lebih sedikit. Harus kurang dari num_subspaces * num_target_modules. Nilai tipikal berkisar dari 20 hingga 100 tergantung pada ukuran model. Default adalah 50. Harus berupa bilangan bulat positif ketika use_asa=True.
  • init_warmup (int) — Jumlah langkah pelatihan yang harus ditunggu sebelum memulai pemangkasan ASA. Selama warmup, semua subspace tetap aktif untuk memungkinkan skor kepentingan menstabilkan. Nilai yang lebih tinggi memberikan waktu lebih lama untuk estimasi kepentingan yang akurat tetapi menunda pemangkasan. Nilai tipikal berkisar dari 50 hingga 200. Default adalah 50. Harus lebih kecil dari final_warmup ketika use_asa=True.
  • final_warmup (int) — Langkah pelatihan di mana ASA menyelesaikan pemangkasan dan mencapai asa_target_subspaces subruang aktif. Pemangkasan didistribusikan antara init_warmup dan final_warmup. Sebaiknya diatur berdasarkan total langkah pelatihan; biasanya 1/3 hingga 1/2 dari total langkah pelatihan. Nilai default adalah 1000. Harus lebih besar dari init_warmup ketika use_asa=True.
  • mask_interval (int) — Jumlah langkah pelatihan antara pembaruan mask ASA. Nilai yang lebih rendah memungkinkan adaptasi lebih sering tetapi meningkatkan overhead. Nilai yang lebih tinggi memberikan estimasi kepentingan yang lebih stabil antar pembaruan. Nilai tipikal berkisar dari 50 hingga 200. Default adalah 100. Harus berupa bilangan bulat positif ketika use_asa=True.
  • asa_importance_beta (float) — Koefisien exponential moving average (EMA) untuk menghaluskan skor pentingnya subspace. Nilai yang lebih tinggi (mendekati 1.0) memberikan bobot lebih besar pada pentingnya historis, sehingga memberikan stabilitas. Nilai yang lebih rendah membuat pentingnya lebih responsif terhadap gradien terbaru. Nilai tipikal berkisar dari 0,8 hingga 0,95. Nilai default adalah 0,85.
  • asa_uncertainty_beta (float) — Koefisien EMA untuk menghaluskan estimasi ketidakpastian kepentingan. Mengontrol seberapa cepat ketidakpastian beradaptasi terhadap varians gradien. Mirip dengan asa_importance_beta, nilai yang lebih tinggi memberikan estimasi yang lebih stabil. Nilai tipikal berkisar dari 0,8 hingga 0,95. Nilai default adalah 0,85.
  • asa_schedule_exponent (float) — Eksponen jadwal yang mengontrol laju peluruhan dari total subspace ke asa_target_subspaces selama ASA warmup. Nilai yang lebih tinggi menghasilkan pemangkasan awal yang lebih cepat (pengurangan awal yang lebih agresif), sedangkan nilai yang lebih rendah memberikan peluruhan yang lebih bertahap, mirip linear. Rumusnya adalah: current_active_subspaces = asa_target_subspaces + (asa_total_subspaces - asa_target_subspaces) * (progress ** exponent). Nilai tipikal berkisar dari 1.0 (linear) hingga 5.0 (agresif). Nilai default adalah 3.0. Harus berupa angka positif saat use_asa=True (eksponen nol atau negatif akan mendegenerasi jadwal menjadi no-op permanen atau, begitu progress mencapai tepat 0.0, akan memicu ZeroDivisionError).
  • use_dynamic_rank (bool) — Apakah akan menentukan rank subspace secara dinamis berdasarkan magnitudo nilai singular. Jika True, rank setiap subspace ditentukan dengan menghitung nilai singular di atas ambang batas, sehingga subspace yang berbeda dapat memiliki rank efektif yang berbeda. Jika False, semua subspace menggunakan subspace_rank yang tetap. Nilai default adalah False.
  • svd_threshold (float) — Rasio ambang untuk pemilihan rank dinamis, hanya digunakan saat use_dynamic_rank=True. Nilai singular dianggap signifikan jika melebihi threshold * max_singular_value. Nilai yang lebih tinggi menghasilkan rank efektif yang lebih rendah (truncasi yang lebih agresif). Nilai tipikal berkisar dari 0,05 hingga 0,2. Nilai default adalah 0,1 (10% dari maksimum).

Kelas konfigurasi untuk metode Adamss (Adaptive Multi-Subspaces).

AdaMSS adalah metode fine-tuning yang efisien secara parameter, yang menguraikan matriks bobot menggunakan SVD dan mengelompokkan ruang yang diuraikan tersebut menjadi beberapa subspace yang dapat dilatih. Metode ini mempelajari pembaruan ber-rank rendah di dalam subspace tersebut sambil mempertahankan bobot asli tetap beku.

AdamssModel

kelas peft.AdamssModel

< >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict] = None ) → torch.nn.Module

Parameter

  • model (torch.nn.Module) — Model yang akan diadaptasi.
  • config (AdamssConfig) — Konfigurasi model Adamss.
  • adapter_name (str) — Nama adapter, secara default "default".

Mengembalikan

torch.nn.Module

Model Adamss.

Membuat model Adamss (Adaptive Multi-Subspaces) dari model pretrained.

Metode ini menguraikan matriks bobot menggunakan SVD dan mengelompokkan ruang yang diuraikan menjadi beberapa subspace yang dapat dilatih untuk fine-tuning yang efisien secara parameter.

Contoh:

>>> from transformers import AutoModelForImageClassification
>>> from peft import AdamssConfig, get_peft_model

>>> config = AdamssConfig(
...     r=500,
...     num_subspaces=5,
...     target_modules=["query", "value"],
... )

>>> model = AutoModelForImageClassification.from_pretrained("google/vit-base-patch16-224")
>>> adamss_model = get_peft_model(model, config)

Atribut:

  • model (~torch.nn.Module) — Model yang akan diadaptasi.
  • peft_config (AdamssConfig): Konfigurasi model Adamss.

update_and_allocate

< >

( global_step: int )

Parameter

  • global_step (int) — Langkah pelatihan saat ini.

Perbarui skor kepentingan dan terapkan masking ASA (jika diaktifkan).

Metode ini harus dipanggil di setiap langkah pelatihan setelah loss.backward() dan sebelum optimizer.zero_grad() ketika ASA diaktifkan. Secara internal, metode ini:

  1. Mengakumulasi skor kepentingan melalui EMA setiap langkah selama periode pemanasan.
  2. Pada interval mask, menerapkan masking top-K global dan mengatur ulang pentingnya.

Ini adalah titik masuk tunggal untuk ASA – menggunakan AdamssAsaCallback dengan Trainer HuggingFace hanya mendelegasikan ke metode ini. Untuk loop pelatihan kustom, panggil metode ini secara langsung alih-alih callback.

Contoh:

for step, batch in enumerate(dataloader):
loss = model(**batch).loss loss.backward() optimizer.step() model.base_model.update_and_allocate(step)
optimizer.zero_grad()
Update on GitHub

←AdaLoRA BOFT→