LoRA

LoRA, PEFT yöntemleri arasında en popüler olanlardan biridir ve PEFT ile yeni başlıyorsanız iyi bir başlangıç noktasıdır. Başlangıçta büyük dil modelleri için geliştirilmiştir ancak verimliliği ve etkinliği sayesinde difüzyon modelleri için son derece popüler bir eğitim yöntemidir.

Düşük Sıralı Uyarlaması (LoRA), büyük bir matrisi iki daha küçük düşük sıralı matrise ayıran bir PEFT yöntemidir. Bu, ince ayar gerektiren parametre sayısını önemli ölçüde azaltır.

Makalenin özeti şudur:

Doğal dil işlemenin önemli bir paradigması, genel alan verilerinde büyük ölçekli ön eğitim ve belirli görevlere veya alanlara uyarlamadan oluşur. Daha büyük modelleri ön eğittikçe, tüm model parametrelerini yeniden eğiten tam ince ayar giderek daha az uygulanabilir hale gelir. GPT-3 175B'yi bir örnek olarak ele alalım — her biri 175B parametreye sahip ince ayarlı modelin bağımsız örneklerini dağıtmak son derece pahalıdır. Düşük Sıra Uyarlaması (Low-Rank Adaptation) veya LoRA'yı öneriyoruz; bu yöntem, ön eğitilmiş model ağırlıklarını dondurur ve Transformer mimarisinin her katmanına eğitilebilir sıra ayrıştırma matrisleri enjekte ederek, aşağı akış görevleri için eğitilebilir parametre sayısını büyük ölçüde azaltır. Adam ile ince ayar yapılmış GPT-3 175B ile karşılaştırıldığında, LoRA eğitilebilir parametre sayısını 10.000 kat, GPU bellek gereksinimini ise 3 kat azaltabilir. LoRA, RoBERTa, DeBERTa, GPT-2 ve GPT-3'te model kalitesi açısından ince ayar kadar iyi veya daha iyi performans gösterir; bu durum, daha az eğitilebilir parametreye sahip olmasına, daha yüksek eğitim verimliliğine ve adaptörlerin aksine ek çıkarım gecikmesi olmamasına rağmen geçerlidir. Ayrıca dil modeli uyarlamasında sıra eksikliğine (rank-deficiency) dair ampirik bir inceleme sunarak LoRA'nın etkinliğine ışık tutuyoruz. LoRA'nın PyTorch modelleriyle entegrasyonunu kolaylaştıran bir paket yayınlıyoruz ve RoBERTa, DeBERTa ve GPT-2 için uygulamalarımızı ve model kontrol noktalarımızı bu https URL adresinde sunuyoruz.

LoRA, ağırlık güncellemelerini $\Delta W$ düşük rütbeli ayrıştırma yoluyla iki daha küçük matrisle (bunlara güncelleme matrisleri) denir) temsil eder. Bu yeni matrisler, genel parametre sayısını düşük tutarken yeni verilere uyum sağlamak için eğitilebilir. Orijinal ağırlık matrisi donmuş kalır ve ek güncelleme almaz. Sonuçları üretmek için orijinal ve ek uyarlama ağırlıkları birleştirilir. Çıkarım gecikmesini ortadan kaldırmak için adaptör ağırlıklarını taban modelle birleştirebilirsiniz.

Bu yaklaşımın bir dizi avantajı vardır:

• LoRA, eğitilebilir parametre sayısını önemli ölçüde azaltarak ince ayarı daha verimli hale getirir.
• Orijinal önceden eğitilmiş ağırlıklar dondurulur; bu, üzerine çeşitli aşağı akış görevleri için birden fazla hafif ve taşınabilir LoRA modeli inşa edebileceğiniz anlamına gelir.
• LoRA, diğer parametre-verimli yöntemlerle ortogonaldir ve bunların çoğuyla birleştirilebilir.
• LoRA kullanılarak ince ayar yapılan modellerin performansı, tamamen ince ayar yapılan modellerin performansıyla karşılaştırılabilir düzeydedir.

İlke olarak, LoRA, eğitilebilir parametre sayısını azaltmak için bir sinir ağının ağırlık matrislerinin herhangi bir alt kümesine uygulanabilir. Ancak basitlik ve ek parametre verimliliği için LoRA, Transformer modellerinde genellikle yalnızca dikkat bloklarına uygulanır - diğer katmanları da hedef almak faydalı olabilir. LoRA modelindeki eğitilebilir parametrelerin sonuçlanan sayısı, büyük ölçüde r derecesi ve orijinal ağırlık matrisinin şekli tarafından belirlenen güncelleme matrislerinin boyutuna bağlıdır.

Düşük rütbeli matrisleri farklı kullanım senaryolarını göz önünde bulundurarak başlatabilirsiniz - görev farkındalığı (CorDA, EVA, Astra), daha hızlı yakınsama (PiSSA), kuantizasyonun azaltılması (LoftQ) - bunlardan sadece birkaçı. Farklı başlatma yöntemleri hakkında aşağıdaki bölümden okuyabilirsiniz. Varsayılan başlatma, LoRA'nın bir no-op (etkisiz işlem) olması ve mevcut modelle çok fazla çelişmeden yeni davranışları kademeli olarak öğrenmesidir.

Kullanım

Düşük rütbeli güncelleme matrislerinin boyutu, rütbe veya r tarafından belirlenir. Daha yüksek bir rütbe, modelin eğitilecek daha fazla parametreye sahip olduğu anlamına gelir, ancak aynı zamanda modelin daha fazla öğrenme kapasitesine sahip olduğu anlamına da gelir. Aşağıdaki örnekte, dikkat bloklarının query ve value matrislerini hedef alacaksınız. Ayarlanması gereken diğer önemli parametreler lora_alpha (ölçekleme faktörü), bias (none, all veya yalnızca LoRA bias parametrelerinin mi eğitileceği) ve modules_to_save (LoRA katmanları dışında eğitilecek ve kaydedilecek modüllerdir). Tüm bu parametreler - ve daha fazlası - LoraConfig içinde bulunur.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

Karma performans değerlendirmesi genel bakış

Başlatma

LoRA ağırlıklarının başlatılması, LoraConfig içindeki init_lora_weights parametresi tarafından kontrol edilir. Varsayılan olarak PEFT, LoRA ağırlıklarını A ağırlığı için Kaiming-uniform, B ağırlığı için sıfırlarla başlatır; bu da bir kimlik dönüşümüne (aynı uygulama ile aynı) yol açar.

transformers.Conv1D katmanları için, örneğin GPT-2 projeksiyonları, ağırlıklar nn.Linear yerleşimi yerine (in_features, out_features) olarak saklandığından fan_in_fan_out=True kullanılmalıdır. Desteklenen ağırlık tabanlı başlatıcılar, ayrıştırma için Linear yerleşimini kullanır ve taban ağırlıkları güncellenirken saklanan yerleşimi geri yükler. LoRA-GA’nın "stable" ölçeklemesi de saklama yerleşiminden bağımsız olarak çıktı boyutunu kullanır.

init_lora_weights="gaussian" parametresini de geçmek mümkündür. İsminden de anlaşılacağı üzere bu, A ağırlığını Gauss dağılımı ile, B ağırlığını ise sıfırlarla başlatır (bu, Diffusers'ın LoRA ağırlıklarını başlatma yöntemidir).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

init_lora_weights=False olarak ayarlanacak bir seçenek de mevcuttur; bu, hata ayıklama ve test için faydalıdır. Bu seçeneği yalnızca bu durumda kullanmalısınız. Bu seçeneği seçtiğinizde, LoRA ağırlıkları, bir kimlik dönüşümüne sonuç vermeyecek şekilde başlatılır.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

Eğitim

Bu bölüm, modele yalnızca düşük rütbeli bir adaptör uygulayıp veri beslemek yerine daha karmaşık eğitim senaryolarının nasıl ele alındığını gösterir.

QLoRA tarzı eğitim

PEFT'teki varsayılan LoRA ayarları, her dikkat bloğunun sorgu ve değer katmanlarına eğitilebilir ağırlıklar ekler. Ancak bir dönüştürücü modelin tüm doğrusal katmanlarına eğitilebilir ağırlıklar ekleyen QLoRA, tamamen ince ayarlanmış bir modelle eşdeğer performans sağlayabilir. QLoRA'da olduğu gibi LoRA'yı tüm doğrusal katmanlara uygulamak için target_modules="all-linear" değerini ayarlayın (mimariye göre değişebilen bireysel modülleri isimle belirtmekten daha kolaydır).

config = LoraConfig(target_modules="all-linear", ...)

PEFT adaptörlerine kuantizasyon uygulamak hakkında daha fazla bilgi için kuantizasyon kılavuzuna bakın.

LoRA ile Bellek Verimli Katman Kopyalama

Model performansını iyileştirmek için kullanılan bir yaklaşım, belirli bir boyuttaki önceden eğitilmiş bir modelden daha büyük bir model oluşturmak için modeldeki katmanları kopyalayarak modeli genişletmektir. Örneğin, SOLAR makalesinde açıklandığı gibi 7B'lik bir modelin 10B'lik bir modele çıkarılması. PEFT LoRA, katmanların kopyalanmasının ardından katmanlara bağlanan LoRA adaptörleri kullanılarak ek ince ayar yapılmasını destekleyen, bu tür genişletmeleri bellek verimli bir şekilde destekler. Kopyalanan katmanlar, altta yatan ağırlıkları paylaştıkları için ek bellek gerektirmez; bu nedenle gereken tek ek bellek, adaptör ağırlıkları için olan bellektir. Bu özelliği kullanmak için layer_replication argümanıyla bir yapılandırma oluşturmanız gerekir.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

Orijinal modelin 5 katmandan oluştuğunu varsayalım [0, 1, 2 ,3, 4], bu durumda [0, 1, 2, 3, 2, 3, 4] şeklinde dizilmiş 7 katmanlı bir model oluşturulur. Bu, mergekit pass through birleştirme kuralını izler; bu kuralda başlangıç dahil, bitiş hariç demetler olarak belirtilen katman dizileri yığılarak nihai model oluşturulur. Nihai modeldeki her katman, kendine özgü bir LoRA adaptör setine sahip olur.

Fewshot-Metamath-OrcaVicuna-Mistral-10B, bu yöntemle Mistral-7B'nin 10B'ye genişletilmiş hali üzerinde eğitilmiş bir model örneğidir. adapter_config.json, bu yöntemi ince ayar için uygulayan örnek bir LoRA adaptör yapılandırmasını gösterir.

Ranks ve alpha (ölçekleme) üzerinde ince ayarlı kontrol

Varsayılan olarak, LoRA ile hedeflenen tüm katmanlar, LoraConfig içinde belirtilenlere bağlı olarak aynı r rütbesine ve aynı lora_alpha değerine (LoRA ölçeklemesini belirleyen) sahip olur. Ancak bazı durumlarda, farklı katmanlar için farklı değerler belirtmek isteyebilirsiniz. Bu, LoraConfig nesnesine rank_pattern ve alpha_pattern argümanlarını iletilebilir. Bu argümanlar, anahtarın katman adı, değerin ise rütbe/alfa değeri olduğu sözlükler olmalıdır. Anahtarlar düzenli ifadeler (regex) olabilir. rank_pattern ve alpha_pattern içinde açıkça belirtilmeyen tüm LoRA katmanları, varsayılan r ve lora_alpha değerlerini alır.

Örnek olarak, aşağıdaki yapıya sahip bir modele sahip olduğumuzu varsayalım:

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42}, tüm 3 foo katmanıyla eşleşir. Ne foobar ne de barfoo eşleşir.
• rank_pattern={"^foo": 42} yalnızca modelin foo katmanıyla eşleşir, ancak ne module.foo ne de module.module.foo ile eşleşmez. Bunun nedeni, düzenli ifadelerde ^ sembolünün “dizinin başı” anlamına gelmesidir ve yalnızca foo "foo" ile başlar; diğer katman adlarının önekleri vardır.
• rank_pattern={"^module.foo": 42} aynı nedenden ötürü yalnızca module.foo ile eşleşir, module.module.foo ile eşleşmez.
• rank_pattern={"module.foo": 42}, hem module.foo hem de module.module.foo ile eşleşir ancak foo ile eşleşmez.
• rank_pattern={"^foo": 42, "^module.module.foo": 55} sırasıyla foo ve module.module.foo ile eşleşir, ancak module.foo ile eşleşmez.
• Eşleşmenin sonunu işaretlemek için $ belirtmenize gerek yoktur, çünkü bu PEFT tarafından otomatik olarak eklenir.

Aynı mantık alpha_pattern için de geçerlidir. Şüphe duyuyorsanız, düzenli ifadelerle uğraşmaya çalışmayın — farklı rank/alpha değerine sahip her modül için ^ önekiyle tam adını iletmeniz yeterlidir.

Uygun hedef modülleri otomatik olarak algıla

peft.helpers.KappaTuneSelector, KappaTune makalesindeki koşul sayısına dayalı hedef seçme stratejisini uygular. Her nn.Linear modülünü tarar; MoE uzman ağırlıklarının füzyonlu 3B nn.Parameter tensörleri olarak saklandığı modellerde (ör. Llama-4, Qwen3-MoE) bu parametreleri de dahil eder, her biri için matris koşul sayısını κ = σ_max / σ_min olarak hesaplar ve en izotropik katmanları (en düşük κ) seçer. Bu izotropik katmanlar, yüksek entropi doğaları sayesinde yeni bilgiyi daha kolay emebildiği için ince ayar için ideal adaylar olarak hizmet eder; bu da uzmanlaşmış, anizotropik katmanların bozulmadan kalmasını sağlayarak sürekli öğrenme sırasında felaketçi unutmayı azaltır.

LoraConfig için en uygun target_modules değerlerini tek satırda almak için peft.helpers.find_kappa_target_modules() işlevini kullanın:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

Tam bir örneği burada görebilirsiniz.

nn.Parameter'ı doğrudan hedefleme

Genel olarak, modülü (ör. nn.Linear) hedeflemek için target_modules kullanmalısınız. Ancak bazı durumlarda bu mümkün değildir. Örneğin, HF Transformers'taki birçok mixture of expert (MoE) katmanında nn.Linear yerine nn.Parameter kullanılır. PEFT, LoRA için normalde forward metodunu yazar, ancak nn.Parameter için böyle bir metot yoktur. Bu nedenle, LoRA'yı bu parametreye uygulamak için target_parameters ile hedeflenmesi gerekir. Örnek olarak, Llama4 için şunu iletebilirsiniz: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

Uzman parametrelerine yönelik hedeflendiğinde, PEFT'in önemli bir çalışma zamanı maliyeti ekleyebileceğini unutmayın. Bunun nedeni, yalnızca küçük bir uzman grubunun gerekli olması durumunda bile PEFT'in her zaman her uzman için LoRA katkısını somutlaştırmasıdır. Eğitim sırasında bu durum daha az önemlidir çünkü dizinin ilerleyişi boyunca, uzmanların genellikle büyük bir kısmı en az bir kez etkinleştirilir. Ancak çıkarım sırasında, normalde bir KV önbelleği kullanılır ve bu nedenle yalnızca son token'ı hesaplamamız gerekir; bu da yalnızca küçük bir uzman grubunun etkinleştirildiği anlamına gelir. Dolayısıyla, MoE katmanlarında LoRA kullanımı, çıkarım sırasında önemli bir yavaşlamaya yol açabilir. Bu nedenle, ağırlıkların birleştirilmesi önerilir (model.merge_adapter() veya model = model.merge_and_unload()). Bu işlem PEFT maliyetini ortadan kaldırır.

Bu konunun daha ayrıntılı incelemesi, MoE optimizasyonu için açılan bu pull request'te bulunabilir.

Dikkat Edilmesi Gerekenler

• Şu anda bu argüman, 2 boyutlu veya 3 boyutlu nn.Parameter hedeflemeye olanak tanır. 3 boyutlu bir parametre durumunda, 0. boyutun uzman (expert) boyutu olduğu varsayılır.
• target_parameters kullanan birden fazla LoRA adaptörü (model.add_adapter veya model.load_adapter ile eklenenler) desteklenir, ancak hepsinin aynı parametre kümesini hedeflemesi gerekir.

MoE uzman parametreleri ve vLLM

Transformers'taki bazı MoE modelleri, uzman ağırlıklarını nn.Parameter tensörleri (genellikle 3B) olarak saklar, nn.Linear modülleri olarak değil. Bu uzmanlara LoRA uygulamak için target_parameters kullanın ve rank_pattern ile katman başına bir rank belirleyin:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

Bu, toplam LoRA parametre bütçesini yoğun katmanlarla benzer tutar (bkz. Schulman ve ark. tarafından yazılan LoRA Without Regret). Uzman olmayan modüller varsayılan r sırasını kullanır.

İnce ayarlı modelle hızlandırılmış çıkarım, örneğin v0.11.2 sürümünden itibaren füzyonlu MoE uzman katmanlarını destekleyen vLLM ile mümkündür.

LoRA ile birlikte tokenleri verimli bir şekilde eğitin

PEFT LoRA adaptörleri, trainable_token_indices parametresi ile yeni token eklemeyi destekler. Bu, belirli katmanların ince ayarının yanı sıra diğer tokenların da ayarlanmasına olanak tanır. Yalnızca belirtilen tokenlar eğitilir ve diğer tüm tokenlara dokunulmaz. Bu, tüm gömme matrisinin eğitilmesinin aksine, mevcut token gömmelerinden öğrenilen bağlamı atmadan bellek tasarrufu sağlar. Bu yöntem, altyapıda TrainableTokensModel katmanını kullanır.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

Aşağıdaki kod parçasında, modele yeni token'lar eklemenin ve bu token'ların modeldeki diğer katmanlarla birlikte nasıl eğitileceğinin gösterilmesini sunuyoruz.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

Token ağırlıkları, LoRA ağırlıklarıyla birlikte adaptör durum sözlüğünün (adapter state dict) bir parçası olarak kaydedilir. Tam ince ayar (full fine-tuning) ve gömme matrisinin (embedding matrix) kaydedilmesi çok daha büyük bir dosya oluştururdu.

Ne kadar VRAM tasarrufu sağlanabileceğine dair bir fikir vermek için, yukarıdaki örnek üzerinde temel bir karşılaştırma yapıldı: gömme matrisinin tamamen eğitilmesi (modules_to_save=["embed_tokens"]), gömme matrisi için LoRA kullanılması (target_modules=[..., "embed_tokens"], rank 32) ve eğitilebilir token'lar (trainable_token_indices=[...], 6 token):

Ağırlık bağlama

Birçok nedensel LM, ağırlık bağlama (weight tying) kullanır; bu yöntemde iki veya daha fazla ağırlık aynı temel parametreleri paylaşır. En yaygın durumda, giriş gömme ağırlıkları (embed_tokens) ve çıktı projeksiyon ağırlıkları (lm_head) aynı tensörü paylaşır. Bunun nedeni, parametre sayısını azaltması ve genellikle model kalitesini korumasıdır.

PEFT’nin, ince ayara hedeflenen bu bağlı ağırlıklarla nasıl başa çıktığı her zaman açık değildir. LoRA için, LoraConfig üzerindeki ensure_weight_tying, PEFT’nin bu katmanlar için adaptör tarafındaki güncellemelerin bağlı kalmasını açıkça sağlayıp sağlamayacağını kontrol eder. Uygulamada bu durum modules_to_save, target_modules ve trainable_token_indices değerlerini etkileyebilir. Katmanların adlandırılması söz konusu olduğunda ("embed_tokens", "lm_head") bu mantığın kısmen bir sözleşmeye dayandığını ve bu sözleşmeler kullanılmadığında düzgün çalışmanın garanti edilemeyeceğini unutmayın.

Aşağıdaki tablolar beklenen davranışı özetler.

modules_to_save

target_modules

trainable_token_indices

Eğitilebilir tokenlar için ek bir karmaşıklık daha vardır: LM başı ve gömlemeler bağlı olsa bile, bir kullanıcı olarak bunlarda farklı tokenları ince ayarlamak isteyebilirim. Aşağıdaki örnek tabloda bu nedenle, aynı tokenların ince ayarı ile farklı tokenların ince ayarı arasında ayrım yapıyoruz.

Kullanıcılar için bu şu anlama gelir:

• Genel olarak, bağlı ağırlıkları ince ayar yapmak ve bağlı kalmalarını sağlamak istiyorsanız ensure_weight_tying=True parametresini iletin.
• Eğer temel modelinizin ağırlıkları bağlı değilse, ensure_weight_tying=True bağlamayı zorlayamaz ve yalnızca bir uyarı verir.
• trainable_token_indices için, ensure_weight_tying=True olduğunda bağlı katmanların aynı token indekslerini kullanması gerekir.

Optimizatörler

LoRA eğitimi, isteğe bağlı olarak özel amaçlı optimizatörler içerebilir. Şu anda PEFT, LoRA-FA, LoRA+ ve Riemannian-preconditioned LoRA'yı destekler.

LoRA-FA Optimizer

LoRA eğitimi, LoRA-FA makalesinde anlatıldığı gibi LoRA-FA kullanılarak daha etkili ve verimli hale getirilebilir. LoRA-FA, A matrisini sabit tutarak ve yalnızca B matrisini ayarlayarak aktivasyon bellek tüketimini azaltır. Eğitim sırasında, B'nin gradyanı, tam parametre ince ayar gradyanını yaklaşık olarak elde edecek şekilde optimize edilir. Ayrıca, LoRA-FA'nın bellek tüketimi ranga duyarlı değildir (çünkü $A$ aktivasyonunu siler); bu nedenle, bellek tüketimini artırmadan lora rangini büyütüp performansı iyileştirebilir.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ optimize edilmiş LoRA

LoRA eğitimi, A ve B adaptör matrisleri için farklı öğrenme oranları kullanan LoRA+ ile optimize edilebilir; bu yöntem, ince ayar hızını 2 katına kadar ve performansı %1-2 oranında artırdığı gösterilmiştir.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

Riemann ön koşullu LoRA

LoRA eğitimi, şu makalede anlatıldığı gibi Riemann ön koşullandırıcısı ile iyileştirilebilir: Riemannian Preconditioned LoRA. Her optimizasyon adımında, LoRA matrislerinin $A$ ve $B$ gradyanları bir $r \times r$ ön koşullandırıcı ile çarpılır. Bu ön koşullandırıcı, düşük rütbeli matris manifoldu üzerindeki Riemann (ölçeklenmiş gradyan) yönüne doğru Öklid gradyanını yeniden ölçeklendirir; bu da güncellemeyi daha iyi koşullandırır ve yakınsamayı iyileştirebilir. Ön koşullandırıcı $r \times r$ boyutunda olduğu için, LoRA rütbesine kıyasla bellek ve çalışma süresi maliyeti küçüktür. create_riemannian_optimizer herhangi bir temel optimizör sınıfını (ör. torch.optim.AdamW veya torch.optim.SGD): sarmalar: LoRA dışındaki parametreler temel optimizör tarafından değiştirilmeden güncellenir ve yalnızca nn.Linear-şeklindeki LoRA katmanları (lora_A / lora_B) ön koşullandırılır.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg terim, tersine çevrilmeden önce $r \times r$ matrisinin köşegenine eklenen bir sönümleme terimidir; bir LoRA faktörü (neredeyse) rütbe eksik olduğunda ön koşullandırıcıyı kararlı hale getirir.

Eğitim Sonrası

Bu bölüm, eğitilmiş adaptörler için olası son işleme yöntemlerini gösterir.

LoRA ağırlıklarını temel modele birleştirin

LoRA, eğitim açısından önemli ölçüde daha küçük ve hızlı olsa da, temel modelin ve LoRA adaptörünün ayrı ayrı yüklenmesi nedeniyle çıkarım sırasında gecikme sorunlarıyla karşılaşabilirsiniz. Gecikmeyi ortadan kaldırmak için adaptör ağırlıklarını temel modelle birleştirmek üzere merge_and_unload() işlevini kullanın. Bu sayede yeni birleştirilen modeli bağımsız bir model olarak kullanabilirsiniz. merge_and_unload() işlevi, adaptör ağırlıklarını bellekte tutmaz.

Aşağıda, LoRA adaptör birleştirme sezgiselini açıklayan bir şema yer almaktadır:

Aşağıdaki kod parçacıklarında bunu PEFT kullanarak nasıl çalıştıracağımızı gösteriyoruz.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

Dönen modeli bir değişkene atamanız ve onu kullanmanız önemlidir, merge_and_unload() yerinde (in-place) bir işlem değildir. Daha sonra adaptörü birleştirmeyi geri almak veya silip farklı adaptörler yüklemek için ağırlıkların bir kopyasını tutmanız gerekiyorsa, bunun yerine merge_adapter() işlevini kullanmalısınız. Şimdi, temel modele dönmek için unmerge_adapter() işlevini kullanma seçeneğiniz var.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

Kantize edilmiş bir modelde birleştirme işlemi tam olarak tersine çevrilemez: birleştirme işlemi temel ağırlığı yeniden kantize eder ve tekrarlanan birleştirme/geri alma döngüleri yuvarlama hatasının birikmesine neden olabilir. Kantize edilmiş ağırlıklara adaptörlerin birleştirilmesi bölümüne bakın.

Birden fazla adaptör etkinse ve bunlardan yalnızca bazıları birleştiriliyorsa, birleştirilmeyen adaptörler sessizce uygulanmaz. Bu davranış PEFT v1.0'da değişecektir. Yalnızca etkin adaptörlerin bir kısmının birleştirilmesi bölümüne bakın.

weights parametresinde kullanıcı tarafından sağlanan bir ağırlıklandırma şemasına göre birden fazla LoRA'yı yeni bir adaptöre birleştirmek için add_weighted_adapter() fonksiyonu kullanışlıdır. Aşağıda uçtan uca bir örnek bulunmaktadır.

Önce temel modeli yükleyin:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

Ardından ilk adaptörü yükleriz:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

Ardından farklı bir adaptör yükleyin ve birincisiyle birleştirin:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

combination_type için birkaç desteklenen yöntem bulunmaktadır. Daha fazla ayrıntı için belgelere bakın. Veri tipi olarak torch.float16 veya torch.bfloat16 kullanıldığında, combination_type olarak “svd” desteklenmez.

Şimdi, çıkarım (inference) işlemini gerçekleştirin:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

İstila boyutunun azaltılması yoluyla temel model performansının geri kazanılması

LoRA vs Full Fine-tuning: An Illusion of Equivalence makalesi, LoRA eğitiminin ağırlıklara, halihazırda öğrenilmiş ağırlıklarla çok az ortak noktası olan ve öğrenilmiş bilgilerin unutulmasına yol açan ek boyutlar eklediğini savunmaktadır. PEFT, peft.tuners.lora.intruders.reduce_intruder_dimension() içinde önerilen azaltma yöntemini uygular.

Müdahale, yüklü bir LoRA içeren bir PEFT modelini alır ve mevcut adaptörün yanı sıra yüklenen ve artık etkin olan yeni, değiştirilmiş bir adaptör oluşturur.

Örnek kullanım:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

Müdahalenin etkinliğini ayarlamak için kullanılabilecek birkaç hiper-parametre vardır; ancak makalenin 8. Şeklinde de gösterildiği üzere, adaptörün öğrendiği görev doğruluğu ile temel modelin bilgisinin unutulması arasında her zaman bir ödünleşim olacaktır. Müdahale, önceki bilgilerin unutulması üzerindeki etkiyi azaltmak için adaptörden bilgiyi kaldırır; ancak bu da adaptörün öğrendiği görevle ilgili bazı bilgilerin de kaybedildiği anlamına gelir.

Varsayılan değerler, bu iki faktör arasında iyi bir denge sunacak şekilde ayarlanmış olsa da, varsayılanların adaptörünüz, modeliniz ve verileriniz için geçerli olacağı garanti edilemez; bu nedenle, etkiyi ölçmek için bir referans testi (benchmark) hazırlamakta fayda vardır.

Adaptörleri yükle

Adapters, ağırlıkları birleştirilmemiş farklı adapterları denemek için faydalı olan load_adapter() ile önceden eğitilmiş bir modele yüklenebilir. Aktif adapter ağırlıklarını set_adapter() fonksiyonuyla ayarlayın.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

Temel modeli geri getirmek için tüm LoRA modüllerini yüklemeyi kaldırmak üzere unload() veya adaptörü tamamen silmek üzere delete_adapter() kullanabilirsiniz. unload() yerinde bir işlem değildir; döndürülen modeli bir değişkene atayıp onu kullanmayı unutmayın.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Tensor Paralelliği

LoRA, Transformers tarafından sağlanan Tensor Parallelism (TP) özelliğini destekler. Bir temel model tp_plan ile yüklendiğinde, PEFT her hedef modülün TP yapılandırmasını otomatik olarak algılar ve LoRA adaptör ağırlıklarına uygun kancaları ekleyerek bunların tensor-parallel hesaplamaya doğru şekilde katılmasını sağlar.

LoRA için Tensor Parallelism desteği transformers >= 5.4.0 gerektirir. DTensor tabanlı Tensor Parallelism API'si peft >= 0.21.1 ve transformers >= 5.17.0 gerektirir.

Kullanım, standart LoRA iş akışıyla aynıdır — PEFT ile sarmalamadan önce temel modeli tp_plan ile yüklemeniz yeterlidir:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

Kaydetme ve yükleme, save_pretrained / from_pretrained üzerinden normal şekilde çalışır. PEFT, kaydetmeden önce parçalı adaptör ağırlıklarını tam tensörlere geri toplar; bu sayede kontrol noktaları taşınabilir olur ve eğitim sırasında kullanılan cihaz sayısından bağımsızdır.

TP plan olmadan tensor paralelliği uygularsanız, örneğin PyTorch’un parallelize_module ile, PEFT; ağırlığın cihaz ızgarasında "tp" adında bir boyut varsa parçalanmış bir nn.Linear’in LoRA ağırlıklarını yerel parçasına, aksi halde tam katman biçimine (FSDP2’de olduğu gibi) boyutlandırır. PEFT, bu LoRA ağırlıklarına TP kancaları eklemez veya kaydetme sırasında onları bir araya getirmez. TP ızgara boyutunuzun adı farklıysa, PEFT modelini oluşturmadan önce onu ekleyin:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

Çıkarım

Bu bölüm, LoRA ile çıkarım sırasında yapabileceklerinizi, örneğin adaptörün ayrıştırılmasını göstermektedir.

Aktif LoRA (aLoRA)

Aktif LoRA (aLoRA), nedensel LM'ler için mevcut taban model KV önbelleğini yeniden kullanarak daha verimli çıkarım sağlayan düşük rütbeli bir adaptör mimarisidir. Bu yaklaşım, çoğu görev/üretim için taban modele bağımlı olan, ancak zincir içindeki uzmanlaşmış görev(ler)i gerçekleştirmek için aLoRA adaptör(ler)i kullanan çıkarım hatları için en uygunudur. Örneğin, taban modelinin üretilen çıktıları kontrol etmek veya düzeltmek. Bu ayarlarda, çıkarım süreleri bir on kat veya daha fazla hızlandırılabilir. aLoRA hakkında daha fazla bilgi ve birçok örnek kullanım senaryosu için aLoRA makalesine bakın.

Bu teknik, her girdide çağrı dizisinin (alora_invocation_tokens) son oluşumunu tarar (bu, 1 token kadar kısa olabilir). Adaptör ağırlıkları, çağrı dizisinin başlangıcından itibaren tokenlarda etkinleştirilir. Çağrı dizisinden sonraki tüm girdiler de adapte edilir ve üretilen tüm tokenlar adapte edilmiş ağırlıkları kullanır. Önceki tokenlardaki ağırlıklar adapte edilmeden bırakılır; bu da nedensel LM'lerdeki nedensel dikkat maskesi nedeniyle bu tokenların önbelleğinin temel model önbelleğiyle değiştirilebilir olmasını sağlar. Kullanım, standart LoRA ile çok benzerdir. Temel fark, adaptör oluşturulurken çağrı dizisinin belirtilmesi gerektiğidir:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

alora_invocation_tokens` bir tamsayıl token kimliği listesidir. İstenen bir çağrı dizesi verildiğinde, bu şu şekilde elde edilebilir:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Tokenizer, taban modelin tokenizer'ıdır. Arama dizimize SOS/EOS token'larını eklememek için (bu büyük olasılıkla aramanın başarısız olmasına neden olur) add_special_tokens=False kullanın.

Notlar

• aLoRA, önbellek yeniden kullanımına odaklanması nedeniyle yalnızca task_type=CAUSAL_LM görevlerini destekler.
• Ağırlıklar daha az token üzerinde uyarlandığı için, genellikle (her zaman değil) aLoRA, LoRA'dan daha yüksek bir rütbe (r) gerektirir. r=32 iyi bir başlangıç noktası olabilir.
• aLoRA ağırlıkları, adaptör ağırlıklarının yalnızca belirli bir token alt kümesine seçici olarak uygulanması nedeniyle tanım gereği temel modele birleştirilemez. Birleştirme denemeleri hata fırlatır.
• Beam search henüz desteklenmiyor.
• Genellikle, temel modelde bulunmayan yeni token'ları tokenizer'a eklemek önerilmez. Bu durum, temel modelin ve adaptör modelin üst üste binen bir bağlam üzerinde çalıştığı hedef kullanım senaryosunu karmaşıklaştırabilir. Bunu, adaptörü eğitmeye başlamadan önce temel modele eğitilebilir token'lar ekleyerek aşabilirsiniz.

Çağrı dizisi seçimi ve SFT tasarımı

alora_invocation_tokens dizisini otomatik olarak eklenmediği için eklemeniz gerekir. Model performansını, önbellek yeniden kullanımını zayıflatmadan en üst düzeye çıkarmak için, adaptör ağırlıklarının uzun girdilerden sonra ancak herhangi bir adaptöre özgü istemcilemenin başlangıcında etkinleştirilmesini öneririz. Herhangi bir modelde olduğu gibi, biçimlendirme eğitim ve test arasında tutarlı olmalıdır.

Aşağıdaki örneği ele alalım: temel modelin bir sohbet şablonu (chat template) vardır ve amaç, adaptörün (adapter) istenen bir çıktı üretmesini sağlamaktır.

• Seçenek 1: Göreve özgü bir istem yoksa, yani girdi assistant istemine sahip bir sohbet geçmişi ise, sohbet şablonunun assistant istemi (ör. <|start_of_role|>assistant<|end_of_role|>) çağrı dizgesi için doğal bir seçimdir. Modelin istemini bulmak için modelin sohbet şablonuna bakın.
• Seçenek 2: Adaptörün öğrendiği görevi açıklayan, görev özel bir prompt varsa ve bu prompt, üretimden hemen önce bir user turu olarak yerleştiriliyorsa, sohbet şablonunun user prompt'u (ör. <|start_of_role|>user<|end_of_role|>) çağrı dizgesi için doğal bir seçimdir.

Bir çağrı dizgesi belirledikten sonra, modelin tokenizer'ını alın ve alora_invocation_tokens'i şu şekilde elde edin

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Örnek bir çıkarım kurulumu alora ince ayarı bölümünde yer almaktadır.

Çağrı dizgesi için özel dizeler kullanılıyorsa, sınırda tokenizasyon sorunlarını önlemek için dizgenin başlangıcının ve sonunun özel tokenlar olduğundan emin olun.

Nedenini görmek için, ‘a’, ‘b’, ‘c’ ve ‘ab’'nin tokenizörünüzdeki tokenlar olduğunu (sırasıyla 1, 2, 3, 4 numaralı) hayal edin. Diyelim ki alora_invocation_tokens = [2, 3]. Şimdi girdi dizinizin “abc” olduğunu varsayın. “ab” bir token olduğu için, bu dizi [4,3] olarak tokenize edilir. Bu nedenle, “bc” dizisi içinde bulunmasına rağmen alora_invocation_tokens bulunamaz. Ancak çağrı dizisinin başı ve sonu özel tokenlarsa, özel tokenlar asla diğer karakterlerle aynı tokena dönüştürülmediği için bu hata durumu asla yaşanmaz.

Üretim için önbelleğin (ve yeniden önbelleğin) kullanımı

aLoRA'nın ana amacı, temel model ile aLoRA adaptör modelleri arasındaki KV önbelleğinin çağrı dizisinden önce değiştirilebilir hale getirilmesidir; çünkü temel ve uyarlanmış KV değerleri uyumlu değildir. Özellikle, bir model üretimi sırasında saklanan anahtarlar ve değerler, bağlam jetonları için pahalı ön doldurma işlemlerinden kaçınmak amacıyla sonraki üretimlerde kullanılabilir. Temel model ile aLoRA adaptörleri arasında önbellek paylaşılırken 2 ana desen vardır:

1. Temel model bir çıktı üretir ve ardından bir aLoRA adaptörü, devam eden bir üretim yapmak için çağrılır. Örneğin, temel model bir soruyu yanıtlar ve halüsinasyonları tespit etmeye yönelik eğitilmiş bir aLoRA, temel modelin yanıtını kontrol eder.
2. Bir aLoRA adaptörü bir çıktı üretmiştir ve temel model veya farklı bir aLoRA adaptörü, orijinal aLoRA ile kısmi bağlam örtüşmesi olan bir devam üretimi için çağrılır. Örneğin, kullanıcı bir sorgu sağlar ve bir aLoRA, sorguyu daha kendi kendine yeterli hale getirmek ve bir RAG sisteminde geri getirmeyi (retrieval) iyileştirmek için yeniden yazar. Ardından, belgeler geri getirilir ve bağlama yüklenir, aLoRA bu belgelerin soruyla ilgili olup olmadığını kontrol eder ve ardından temel model bir yanıt üretir.

Önbellekleme kullanılırken yukarıdaki davranışları göstermek için transformers kütüphanesinden DynamicCache sınıfını kullanıyoruz. Uyarlanmış önbellek değerlerinin temel önbellek değerleriyle karışmamasına dikkat edin. Özellikle, kısmi bağlam örtüşmesi (2. desen) söz konusu olduğunda önbelleğin paylaşılması için ek bir adım gereklidir.

Desen 1: aLoRA'dan önce temel model Burada, temel modelin tüm girdisi ve üretimi, çağrı dizisiyle birlikte aLoRA adaptörüne girdi olarak verilir:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

Desen 2: aLoRA üretimi, ardından kısmi bağlam örtüşmesine sahip temel model (veya başka bir aLoRA) Burada, paylaşılan bağlamı temel model kullanarak önceden dolduruyor ve ardından üretiyoruz.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

Aynı batch içinde farklı LoRA adaptörleriyle çıkarım

Normalde, PEFT’te her çıkarım partisi aynı adaptör(ler)i kullanmak zorundadır. Bu bazen can sıkıcı olabilir, çünkü farklı LoRA adaptörleriyle kullanılacak örnekler içeren partilerimiz olabilir. Örneğin, İngilizcede iyi çalışan bir temel modele ve bir Fransızca, bir de Almanca için iki ek LoRA adaptöre sahip olabiliriz. Genellikle, partilerimizi her birinin yalnızca dillerden birinin örneklerini içerecek şekilde bölmek zorunda kalırız; farklı dilleri aynı partide birleştiremeyiz.

Neyse ki, adapter_name argümanını kullanarak farklı LoRA adaptörlerini aynı partide birleştirmek mümkündür. Aşağıda, bunun pratikte nasıl çalıştığını gösteren bir örnek sunuyoruz. Önce, temel modeli, İngilizceyi ve iki adaptörü (Fransızca ve Almanca) şu şekilde yükleyelim:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

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

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

Şimdi, üç dilin de yer aldığı bir örnek üzerinde metin üretmek istiyoruz: İlk üç örnek İngilizce, sonraki üç örnek Fransızca ve son üç örnek Almancadır. Her örnek için hangi adaptörün kullanılacağını belirtmek için adapter_names argümanını kullanabiliriz. Temel modelimiz İngilizce için kullanıldığından, bu örnekler için "__base__" özel dizesini kullanıyoruz. Sonraki üç örnek için Fransızca LoRA ince ayarının adaptör adını, bu durumda "adapter_fr" olarak belirtiyoruz. Son üç örnek için ise Almanca LoRA ince ayarının adaptör adını, bu durumda "adapter_de" olarak belirtiyoruz. Bu sayede temel modeli ve iki adaptörü tek bir partide kullanabiliriz.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

Burada sıranın önemi olmadığını, yani yukarıdaki örnekteki gibi batch içindeki örneklerin adapter'a göre gruplandırılmasının gerekmediğini belirtelim. Tek yapmamız gereken, adapter_names argümanının örneklerle doğru şekilde hizalanmasını sağlamaktır.

Ayrıca, aynı yaklaşım, sınıflandırma görevleri için özel başlıklar gibi belirli sinir ağı katmanlarının farklı LoRA adaptörleri arasında kaydedilip yeniden kullanılmasına olanak tanıyan modules_to_save özelliğiyle de çalışır.

Dikkat Edilmesi Gerekenler

Bu özelliğin kullanılması bazı dezavantajlar taşır, bunlar şunlardır:

• Sadece çıkarım için çalışır, eğitim için değil.
• with model.disable_adapter() bağlamı kullanılarak adaptörlerin devre dışı bırakılması, adapter_names parametresine göre önceliklidir.
• Bazı adaptör ağırlıkları merge_adapter yöntemi kullanılarak temel ağırlıklarla birleştirildiyse adapter_names parametresini geçemezsiniz. Lütfen önce model.unmerge_adapter() çağrısını yaparak tüm adaptörleri birleştirmeden (unmerge) çıkarın. Dikkat edin, adapter_names dışında yalnızca etkin adaptörlerin bir kısmını birleştirmek de benzer bir uyarı gerektirir.
• Açık nedenlerle, bu, merge_and_unload() çağrıldıktan sonra kullanılamaz; çünkü bu durumda tüm LoRA adaptörleri temel ağırlıklarla birleştirilir.
• Bu özellik şu anda DoRA ile çalışmıyor, bu özelliği kullanmak istiyorsanız LoraConfig içinde use_dora=False olarak ayarlayın.
• modules_to_save özelliği şu anda yalnızca Linear, Embedding, Conv2d ve Conv1d türündeki katmanlar için desteklenmektedir.
• Çıkarım için beklenen bir ek maliyet vardır adapter_names, özellikle bir toplamdaki farklı adaptör sayısı yüksekse. Bunun nedeni, toplama boyutunun fiilen adaptör başına örnek sayısına indirgenmesidir. Çalışma zamanı performansı en önceliğinizse, şunları deneyin:
  • Toplu işlem boyutunu artırın.
  • Aynı batch içinde çok sayıda farklı adapter bulunmasından kaçınmaya çalışın, homojen batch'leri tercih edin. Bu, aynı adapter'a sahip örnekleri tamponlamayla ve yalnızca küçük bir avuç farklı adapter ile çıkarım yaparak sağlanabilir.
  • Farklı adaptörlerin büyük bir sayısıyla çalışmak üzere özel olarak tasarlanmış LoRAX, punica veya S-LoRA gibi alternatif uygulamalara göz atın.

LoRA Uyarlayıcılarını Birleştirme ve Yeniden Kullanma

Arrow

Arrow, Polytropon'a benzer şekilde belirli bir görevi çözmek için birden fazla önceden eğitilmiş, görev özelinde LoRA adaptörünü birleştirmek üzere tasarlanmış modüler bir yönlendirme algoritmasıdır; ancak ince ayar gerektirmez. Tüm adaptörleri körü körüne birleştirmek yerine Arrow, gradyansız, token bazlı uzman karışımı (MoE) yönlendirme mekanizmasını sunar. Çıkarım sırasında, her LoRA için SVD ayrıştırmasından en üst sağ tekil vektörü çıkararak bir prototip hesaplar. Ardından her token temsilinin bu prototiplerle kosinüs benzerliği üzerinden karşılaştırılmasıyla yönlendirme katsayıları elde edilir. Tokenlar, en alakalı üst-k LoRA adaptörüne atanır, katsayılar softmax ile normalize edilir ve çıktıları doğrusal olarak birleştirilir. Bu, mevcut LoRA modüllerinin yeni görevler için etkili bir şekilde yeniden kullanılmasını sağlar ve daha güçlü sıfır atış genelleme yeteneğine yol açar.

PEFT'te Arrow, [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Ayrıca, create_arrow_model çağrısından sonra adaptörler ekleyebilir veya kaldırabilirsiniz; örneğin yeni bir adaptör ince ayar yapmak veya gereksiz birini atmak için. Adaptörler yerleştirildikten sonra, Arrow kullanmak için çıkarım sırasında "arrow_router" bileşenini etkinleştirebilirsiniz. Dikkat edin, create_arrow_model sonrasında yeni bir LoRA adaptörü eklediyseniz ve bunu ince ayarlamak istiyorsanız, create_arrow_model içinde "arrow_router" varsayılan olarak etkinleştirildiğinden, yeni adaptörü açıkça etkin olarak belirlemeniz gerekir.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub, Arrow'u, yönlendirme öncesinde görev özel LoRA adaptörlerini arındırarak güçlendirir. Temel fikir, inkâr yoluyla unutma ilkesine dayalı olarak LoRA uzayında kodlanmış genel bilgiyi çıkarmaktır; böylece görev adaptörleri daha izole hale gelir ve görevle ilgili sinyallere odaklanır. Somut olarak GenKnowSub, genel (görev özel olmayan) bir LoRA adaptörü kümesinden düşük boyutlu bir “genel” alt uzay tahmin eder ve Arrow'un token bazlı yönlendirmesi öncesinde bu bileşeni her görev adaptörünün LoRA güncellemesinden çıkarır. Bu, genellikle birçok görev adaptörünün birleştirildiğinde kompozisyonelliği iyileştirir ve girişimi azaltır.

PEFT’de GenKnowSub’u etkinleştirmek için use_gks=True değerini ArrowConfig içinde ayarlayın ve create_arrow_model içinde general_adapter_paths parametresini sağlayın:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Genel bilgiyi kodlamak için GenKnowSub, yönlendirme başlamadan önce, sağlanan genel adaptörlerin ortalamasını her görev özel adaptöründen bir kez çıkarır. Ayrıca, create_arrow_model çağrıldıktan sonra adaptör eklemenin veya kaldırmanın (Arrow bölümünde açıklandığı gibi) bu durumda da desteklenmeye devam ettiği unutulmamalıdır.

Arrow + GenKnowSub kullanırken dikkat edilmesi gerekenler:

• Tüm LoRA adaptörleri (görev özel ve genel) aynı rank ve target_modules değerlerini paylaşmalıdır.

• Bu ayarlar arasındaki herhangi bir tutarsızlık, create_arrow_model içinde bir hata oluşturur.

• Görev adaptörleri arasında farklı ölçekleme faktörlerinin (lora_alpha) kullanılması desteklenir — Arrow bunları otomatik olarak işler.

• Dinamik yönlendirme davranışı nedeniyle "arrow_router"'ın birleştirilmesi desteklenmez.

• create_arrow_model içinde görev adaptörleri task_i olarak, genel adaptörler ise gks_j olarak yüklenir (burada i ve j indekslerdir). İşlev, target_modules, rank ve adaptörlerin Linear mı yoksa Linear4bit katmanlarına mı uygulandığı tutarlılığını sağlar. Ardından "arrow_router" modülünü ekler ve etkinleştirir. Bu sürecin özelleştirilmesi, create_arrow_model işlevinin yeniden tanımlanmasını gerektirir.

• Bu uygulama, 4-bit kuantizasyonla (bitsandbytes aracılığıyla) uyumludur:

  Kopyalandı

  from transformers import AutoModelForCausalLM, BitsAndBytesConfig
  import torch
  
  # Quantisation config
  bnb_config = BitsAndBytesConfig(
          load_in_4bit=True,
          bnb_4bit_quant_type="nf4",
          bnb_4bit_compute_dtype=torch.bfloat16,
          bnb_4bit_use_double_quant=False,
      )
  
  # Loading the model
  base_model = AutoModelForCausalLM.from_pretrained(
      "microsoft/Phi-3-mini-4k-instruct",
      dtype=torch.bfloat16,
      device_map="auto",
      quantization_config=bnb_config,
  )
  
  # Now call create_arrow_model() as we explained before.

API

LoraConfig

LoraModel

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)

>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

Yardımcı

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

Yardımcılar

İstirahat Boyut Azaltma