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, önceden eğitilmiş ağırlık sütun vektörlerinin geometrik ilişkilerini koruyarak performans ile parametre sayısı, bellek kullanımı ve hesaplama maliyeti gibi çok boyutlu verimlilik arasında dengeli bir ödünleşim sağlayan, Ortogonal İnce Ayar (OFT) tabanlı parametre-verimli ince ayar yöntemidir. Ortogonal dönüşümleri, önceden eğitilmiş ağırlıklardan türetilen düşük rütbeli bir ana alt uzaya kısıtlayarak PSOFT, LoRA ile OFT arasındaki boşluğu kapatmakta ve hem teorik garantiler hem de pratik uyumluluk sağlamaktadır. Etkinliği, GLUE, VTAB-1K, GSM8K, MATH ve ortak duygu akıl yürütme kriterleri dahil olmak üzere çeşitli kriterler üzerinde yapılan kapsamlı değerlendirmelerle doğrulanmıştır.

  • Yalnızca nn.Linear katmanları desteklenir.
  • Kantize katmanlar desteklenmez.

Makalenin özeti şudur:

Model parametrelerindeki hızlı büyüme sayesinde, kısıtlı hesaplama kaynakları altında büyük modelleri çeşitli aşağı akış görevlerine uyarlamak için parametre-verimli ince ayar (PEFT) vazgeçilmez hale gelmiştir. Bu paradigma içinde, dik (orthogonal) ince ayar ve türevleri, önceden eğitilmiş modellerin anlamsal temsillerini korur; ancak parametre sayısı, bellek ve hesaplama açısından hem ifade gücünü hem de verimliliği aynı anda sağlamakta zorlanır. Bu sınırlamayı aşmak için, dik dönüşümleri önceden eğitilmiş ağırlıkların ana alt uzayına (principal subspace) kısıtlayan, Ana Alt Uzay Uyarlamalı Verimli Dik İnce Ayar'ı (PSOFT) öneriyoruz. Özellikle PSOFT, uyumlu dönüşümleri mümkün kılmak için bu alt uzayı matris ayrıştırması yoluyla oluşturur, temel anlamsal koruma için bu alt uzayın geometrisini katı bir şekilde koruyan teorik bir koşul belirler ve eğitimin ilerleyen aşamalarında dikliği kademeli olarak gevşeterek uyumluluğu artıran verimli ayarlanabilir vektörler sunar. Dört temsilci model üzerinde 35 NLP ve CV görevinde yapılan kapsamlı deneyler, PSOFT'un PEFT'de anlamsal koruma, ifade gücü ve çok boyutlu verimliliği aynı anda sağlamak için pratik ve ölçeklenebilir bir çözüm sunduğunu göstermektedir.

PSOFT Nasıl Çalışır

PSOFT, her ağırlık matrisini WpreW_{pre} şeklinde WpriW_{pri} ve WresW_{res} bileşenlerine SVD kullanarak ayrıştırır: Wpre=USV⊤W_{\text{pre}} = U S V^\top

Ana alt uzay Wpri=UrSrVr⊤=ABW_{\text{pri}} = U_r S_r V_r^\top = AB en üstteki $r$ tekil bileşenlerden oluşturulur:

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, katı diklik ile

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: gevşetilmiş diklik koşuluyla PSOFT

Eğitim sırasında $A$, $B$ ve WresW_{\text{res}} donurulur ve yalnızca RR (veya RR ile α\alpha ve $\beta$) eğitilebilir.

PEFT çerçevesiyle (eklemeli ağırlık güncellemeleri bekleyen) uyumluluk için PSOFT, aşağıdaki eklemeli formda uygulanır: Wps-tuned=Wpre+A(R−Ir)BW_{\text{ps-tuned}} = W_{\text{pre}} + A (R - I_r) B

Eğitilebilir Parametreler

PSOFT uygulandıktan sonra:

  • Orijinal model ağırlıkları ($A$, $B$ ve $W_{\text{res}}$) dondurulur.
  • Yalnızca ortogonal matris RR (ve isteğe bağlı olarak $\alpha$, $\beta$) eğitilebilir.
  • Ek sapma parametreleri eklenmez.

Temel Kullanım

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)

Yapılandırma Seçenekleri

Farklı Mod

(PSOFT-SO: Katı diklikli PSOFT)

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

(PSOFT-RO: gevşetilmiş diklik ile PSOFT)

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

En İyi Uygulamalar

  1. Sıra Seçimi: Daha küçük sıralar (ör. 32–128) daha basit görevler için uygunken, daha büyük sıralar (ör. 64–256) daha karmaşık görevler için artan parametre ve hesaplama maliyeti karşılığında daha yüksek ifade gücü sağlar.
  2. Scaling Factor: Ölçekleme faktörü genellikle rr PSOFT'ta olarak ayarlanır.
  3. Öğrenme Hızı: Kararlı eğitim için standart öğrenme hızlarını (ör. 1e-4 ile 5e-3 arası) kullanın.
  4. SVD Başlatma: lowrank seçeneği, full'e kıyasla bellek ve hesaplama açısından daha verimli olduğundan büyük modeller için daha uygundur.
  5. Cayley–Neumann Yaklaşımı: Sıra (rank) büyük olduğunda, Cayley–Neumann yaklaşımını etkinleştirmek hesaplama verimliliğini önemli ölçüde artırabilir; ancak küçük sıralarda bu fayda daha az belirgindir. Uygulamada, Neumann serisinin küçük bir terim sayısı (genellikle 5) genellikle doğruluk ve verimlilik arasında iyi bir denge sağlar.

Karma performans değerlendirmesi genel bakış

API

PsoftConfig

sınıf 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 )

Parametreler

  • r (int) — Varsayılan değeri 32'dir. PSOFT rütbesi (r), r*r dönüşümü R aracılığıyla adaptör kapasitesini kontrol eder. Basit görevler için genellikle 32-128 aralığındaki daha düşük rütbeler yeterlidir; daha karmaşık görevler, ek parametre ve hesaplama maliyeti karşılığında ifade gücünü artırarak 64-256 aralığından faydalanabilir. Deneysel olarak doğrulanmış ayarlar için makaleye bakın: https://openreview.net/forum?id=FSHrinMArK.
  • target_modules (Optional[Union[List[str], str]]) — Uyarlamanın (adapter) uygulanacağı modüllerin adları. Bu parametre belirtilirse, yalnızca belirtilen adlara sahip modüller değiştirilir. Bir dize (string) geçirildiğinde, bir regex eşleşmesi yapılır. Dize listesi geçirildiğinde, tam bir eşleşme yapılır veya modül adının, geçirilen dizelerden herhangi biriyle sona erip ermediği kontrol edilir. Bu parametre ‘all-linear’ olarak belirtilirse, tüm linear/Conv1D modülleri seçilir (model bir PreTrainedModel ise, çıktı katmanı hariç tutulur). Bu parametre belirtilmezse, modüller model mimarisine göre seçilir. Mimari bilinmiyorsa bir hata oluşturulur — bu durumda, hedef modülleri manuel olarak belirtmelisiniz.
  • exclude_modules (Optional[Union[List[str], str]]) — Uyarlamanın (adapter) uygulanmaması istenen modüllerin adları. Bir dize geçirildiğinde, bir regex eşleşmesi yapılır. Bir dize listesi geçirildiğinde, tam bir eşleşme yapılır veya modül adının, geçirilen dizelerden herhangi biriyle sonlanıp sonlanmadığı kontrol edilir.
  • psoft_alpha (int) — Varsayılan olarak 32'dir. PSOFT ölçekleme çarpanını kontrol eder. LoRA alpha ile aynı anlamsal yapıya sahiptir.
  • psoft_dropout (float) — Varsayılan olarak 0.0. PSOFT yolu için dropout. LoRA dropout ile aynı anlamsal yapıya sahiptir.
  • fan_in_fan_out (bool) — Değiştirilecek katman ağırlıkları (fan_in, fan_out) biçiminde saklıyorsa bunu True olarak ayarlayın. Örneğin, gpt-2 ağırlıkları (fan_in, fan_out) biçiminde saklayan Conv1D kullanır ve bu nedenle bu değer True olarak ayarlanmalıdır.
  • ab_svd_init (Literal["psoft_init", "pissa_init"]) — Varsayılan olarak ‘psoft_init’ değerini alır. PSOFT içindeki ana alt uzayı oluşturmak için A ve B matrislerinde kullanılan başlatma stratejisidir. ‘psoft_init’: Satır-ortogonal A matrisi ile SVD tabanlı başlatma, kesin ortogonallik sağlar (PSOFT). ‘pissa_init’: Simetrik A ve B matrisleri ile SVD tabanlı başlatma (standart PiSSA).
  • psoft_svd (Literal["full", "lowrank"]) — Varsayılan olarak ‘full’ kullanılır. Başlatma için SVD arka ucu: ‘full’, torch.linalg.svd kullanır; ‘lowrank’, torch.svd_lowrank kullanır.
  • psoft_svd_lowrank_niter (int) — Yalnızca psoft_svd=‘lowrank’ olduğunda kullanılır. Varsayılan değeri 10'dur. psoft_svd=‘lowrank’ olduğunda torch.svd_lowrank tarafından kullanılan kuvvet iterasyonlarının sayısı.
  • psoft_orth (bool) — Varsayılan değeri ‘True’dur. True ise, R, Cayley parametrelendirmesi aracılığıyla ortogonal olacak şekilde kısıtlanır ve önceden eğitilmiş ağırlık vektörlerinin sütunları arasındaki geometrik ilişkiler korunur. False ise, R, ortogonallik kısıtlamaları olmadan serbest bir matristir.
  • psoft_mag_b (bool) — Varsayılan değeri ‘True’dur. True ise, R’nin ‘output’ tarafında çaprazal bir ölçekleme vektörü öğrenir. Genellikle psoft_mag_a ile birlikte kullanılır; görev uyumluluğunu artırır, ancak önceden eğitilmiş geometride hafif bir bozulmaya yol açar.
  • psoft_mag_a (bool) — Varsayılan olarak ‘True’. True ise, R’nin ‘input’ tarafında çaprazal bir ölçekleme vektörü öğrenir. Genellikle, önceden eğitilmiş geometride hafif bir bozulma pahasına görev uyumluluğunu artırmak için psoft_mag_b ile birlikte kullanılır.
  • use_cayley_neumann (bool) — Varsayılan olarak ‘False’. PSOFT’un Cayley-Neumann formülasyonunun kullanılıp kullanılmayacağını belirtir. Hesaplama verimliliğini artırmak için True olarak ayarlayın ancak bunun, diklik için daha büyük bir yaklaşım hatası maliyeti vardır.
  • num_cayley_neumann_terms (int) — Varsayılan değeri 5'tir. Yalnızca use_cayley_neumann=True olduğunda kullanılır. Kullanılacak Cayley-Neumann terimlerinin sayısı. Daha yüksek bir sayı, ortogonallik için daha az yaklaşıklık hatası sonucunu verir.
  • cayley_neumann_eps (optional[float]) — Varsayılan değeri ‘None’dir. Yalnızca use_cayley_neumann=True olduğunda kullanılır. Cayley-Neumann yaklaşımında Q jeneratör matrisi için isteğe bağlı Frobenius norm sınırı. None (varsayılan) ise yeniden ölçekleme uygulanmaz. (0, 1) aralığında bir değere (ör. 0,9) ayarlanırsa, sayısal kararlılığı artırmak için ||Q||_F eşik değeri aştığında Q yeniden ölçeklenir. Ayrıntılar için https://spherelab.ai/oftv2/ adresine bakın.
  • init_weights (bool) — Varsayılan olarak ‘True’. PSOFT katmanlarının ağırlıklarının varsayılan başlatma yöntemiyle başlatılıp başlatılmayacağını belirtir. Bu ayarı, ne yaptığınızı tam olarak biliyorsanız değiştirin.
  • modules_to_save (List[str]) — Son kontrol noktasında kaydedilecek ve eğitilebilir olarak ayarlanacak, adaptör katmanları dışındaki modüllerin listesi.
  • layers_to_transform (Union[List[int], int]) — Dönüştürülecek katman indeksleri. Bir int listesi geçirilirse, adaptör bu listede belirtilen katman indekslerine uygulanır. Tek bir tamsayı geçirilirse, dönüşümler bu indeksteki katmana uygulanır.
  • layers_pattern (Optional[Union[List[str], str]]) — Katman desen adı, yalnızca layers_to_transform None'den farklıysa kullanılır. Bu, genellikle 'layers' veya 'h' olarak adlandırılan modelin nn.ModuleList'ini hedeflemelidir.

PSOFT (Principal Subspace Adaptation ile Verimli Ortogonal İnce Ayar) yapılandırması.

PSOFT, düşük rütbeli A ve B matrisleri arasına r*r ortogonal bir dönüşüm R yerleştirir, böylece düşük rütbeli güncelleme ΔW = B @ (R-I) @ A olur. Yalnızca R (ve isteğe bağlı ayarlanabilir vektörler) eğitilir; A ve B, psoft_init (SVD tabanlı, satır-ortogonal A) ile başlatılır ve dondurulur.

PsoftModel

sınıf peft.PsoftModel

< >

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

Parametreler

  • model — Uyarlanacak model.
  • config — PsoftConfig.
  • adapter_name — Adaptör adı, varsayılan “default”.
  • low_cpu_mem_usage — Meta cihazında boş adaptör ağırlıkları oluşturun.

PSOFT (Principal Subspace Adaptation ile Verimli Ortogonal İnce Ayar) modeli.

Düşük rütbeli A ve B arasına r*r ortogonal (veya ölçekli) bir dönüşüm R yerleştirir: ΔW = B @ (R-I) @ A. A/B'yi SVD'den başlatmak ve dondurmak, yalnızca R'yi (ve isteğe bağlı büyüklük vektörlerini) eğitmek için ab_svd_init="psoft_init" kullanın.

Update on GitHub

←Polytropon PVeRA→