PEFT documentation

Sorun Giderme

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Sorun Giderme

PEFT kullanırken herhangi bir sorunla karşılaşırsanız, lütfen aşağıdaki yaygın sorunlar ve çözümleri listesini kontrol edin.

Örnekler çalışmıyor

Örnekler genellikle en güncel paket sürümlerine dayanır, bu nedenle güncel olduklarından emin olun. Özellikle aşağıdaki paket sürümlerini kontrol edin:

  • peft
  • transformers
  • accelerate
  • torch

Genel olarak, Python ortamınızda bu komutu çalıştırarak paket sürümünü güncelleyebilirsiniz:

python -m pip install -U <package_name>

Kaynaktan PEFT kurmak, en son gelişmeleri takip etmek için faydalıdır:

python -m pip install git+https://github.com/huggingface/peft

Dtype ile ilgili sorunlar

ValueError: FP16 gradyanları ölçek dışı bırakılmaya çalışılıyor

Bu hata, muhtemelen modelin dtype=torch.float16 ile yüklenip ardından otomatik karma hassasiyet (AMP) bağlamında, örneğin 🤗 Transformers'tan Trainer sınıfında fp16=True ayarlanarak kullanılması nedeniyle oluşmuştur. Bunun nedeni, AMP kullanılırken eğitilebilir ağırlıkların asla fp16 kullanmaması gerektiğidir. Tüm modeli fp32'de yüklemeye gerek kalmadan bunu çalıştırmak için kodunuza aşağıdakileri ekleyin:

peft_model = get_peft_model(...)

# add this:
for param in model.parameters():
    if param.requires_grad:
        param.data = param.data.float()

# proceed as usual
trainer = Trainer(model=peft_model, fp16=True, ...)
trainer.train()

Alternatif olarak, ağırlıkları doğru şekilde dönüştürmek için cast_mixed_precision_params() işlevini kullanabilirsiniz:

from peft import cast_mixed_precision_params

peft_model = get_peft_model(...)
cast_mixed_precision_params(peft_model, dtype=torch.float16)

# proceed as usual
trainer = Trainer(model=peft_model, fp16=True, ...)
trainer.train()

PEFT sürüm v0.12.0'dan itibaren PEFT, uygun durumlarda adaptör ağırlıklarının dtype'ünü torch.float16 ve torch.bfloat16'dan torch.float32'ye otomatik olarak yükseltir. Bu davranışı önlemek için autocast_adapter_dtype=False parametresini ~get_peft_model(), from_pretrained() ve load_adapter() fonksiyonlarına iletebilirsiniz.

Adaptörün dtype'ünü seçme

LoRA gibi çoğu PEFT yöntemi, eğitilebilir adaptör ağırlıkları ekleyerek çalışır. Varsayılan olarak bu ağırlıklar float32 veri türünde (fp32), yani nispeten yüksek bir hassasiyette saklanır. Bu nedenle, temel model float16 (fp16) veya bfloat16 (bf16) olarak yüklense bile adaptör ağırlıkları float32'dir. İleri geçiş sırasında adaptör sonuçları hesaplanırken girdi genellikle temel modelin veri türünde olur; bu nedenle gerekirse float32'ye yükseltilir ve ardından orijinal veri türüne geri dönüştürülür.

Uyarlama ağırlıklarının (adapter weights) temel modelin daha düşük hassasiyetinde, yani float16 veya bfloat16 olarak tutulmasını tercih ediyorsanız, modeli oluştururken (~get_peft_model()) veya yüklerken (from_pretrained()) autocast_adapter_dtype=False parametresini iletebilirsiniz. Bunun bazı avantajları ve dezavantajları vardır:

Yarım hassasiyet adaptörünün avantajları:

  • hesaplama biraz daha hızlı
  • biraz daha az bellek
  • kontrol noktasının daha küçük dosya boyutu (yarısı kadar)

Yarım hassasiyet adaptörünün dezavantajları:

  • biraz daha kötü kayıp
  • taşma veya taşma altı riski daha yüksek

Çoğu kullanım senaryosunda, genel çalışma süresinin ve bellek maliyetinin temel modelin boyutu ve veri seti tarafından belirleneceğini, PEFT adaptörünün dtype'ünün ise yalnızca küçük bir etkiye sahip olacağını unutmayın.

Eğitim çalışıyor ancak model gelişmiyor

Eğitim sağlıklı görünüyorsa (kayıp azalıyor, kontrol noktaları hatasız kaydediliyor) ancak sonuçta elde edilen model, temel modelden daha iyi performans göstermiyorsa, eğitim sırasında eğitilebilir parametrelerin gerçekten değişip değişmediğini kontrol edin:

# before training
sample_param = next(p for p in model.parameters() if p.requires_grad)
before = sample_param.detach().clone()

# ... train for at least three optimizer steps ...

after = next(p for p in model.parameters() if p.requires_grad)
print("weights updated:", not torch.allclose(before, after.detach().cpu()))

Eksik ileri veya geri yönlü kancalar

Ağırlıklar hareket etmediyse olası bir neden, parametre referanslarının parametreler hedef cihazda somutlaştırılmadan önce yakalanmış olmasıdır. Bu durum, taban model parametreleri henüz hedef cihaza taşınmadan get_peft_model() ile sarıldığında ve ardından üçüncü taraf bir kütüphane forward/backward kancaları kaydettiğinde (örneğin, diferansiyel gizlilik çerçevesinden gelen örnek başına gradyan kancaları) veya ilk forward çağrısından önce bir optimizör oluşturulduğunda ortaya çıkabilir. Parametreler daha sonra somutlaştırıldığında, bu kancalar ve optimizör referansları eski tensörlere işaret eder ve her güncelleme sessiz bir no-op'a dönüşür.

Bunu önlemek için aşağıdaki sıralamayı kullanın:

  1. Temel modeli yükleyin ve hedef cihaza taşıyın (ör. model.to(device)).
  2. Bunu get_peft_model() ile sarın.
  3. Yalnızca o zaman hook'ları kaydedin veya optimizörü oluşturun.

Hedef modüller modelle eşleşmiyor

Eğitim hata vermeden çalışıyor ancak kayıp neredeyse hiç değişmiyorsa — ya da ince ayar sonrası modelde bir iyileşme gözlenmiyorsa — yapılandırılan target_modules (kullanıcı tarafından aksi belirtilmedikse varsayılan target_modules) modeldeki gerçek modül adlarıyla eşleşmiyor olabilir. Bu durum, standart Transformer modellerinden farklı katman adları kullanan Mamba, Jamba veya NemotronH gibi hibrit mimarilerde yaygındır.

PEFT, yapılandırılan target_modules listesindeki hiçbir modülün modeldeki herhangi bir modülle eşleşmediği durumlarda hata fırlatır. Bazıları eşleşip bazıları eşleşmiyorsa, eşleşmeyen girdiler sessizce atlanır — herhangi bir uyarı verilmez. Modelin büyük bir bölümü, hiçbir gösterge olmadan donmuş kalabilir.

İlk tanı, eğitilebilir parametre sayısını kontrol etmektir:

from peft import LoraConfig, get_peft_model

config = LoraConfig(target_modules=["q_proj", "v_proj", "gate_proj"])
model = get_peft_model(base_model, config)
model.print_healthcheck()

Raporlanan sayı beklenenden çok daha düşükse, modeldeki adaptör katmanlarını inceleyin:

print(model.get_layer_status())

Bu, her adaptör katmanının adını, modül türünü, etkin durumunu ve aktif adaptörlerini gösteren TunerLayerStatus girdilerinden oluşan bir liste döndürür. Alternatif olarak, modelin temsilini yazdırma (print(model)) işlemi, tam modül hiyerarşisinin bir genel bakışını sunar ve bu da tanımadığınız mimarilerde doğru katman adlarını belirlemek için faydalıdır.

Modeldeki bir modüle karşılık gelmeyen herhangi bir target_modules girişi sessizce atlanır. target_modules değerini gerçek modül adlarıyla eşleşecek şekilde güncelleyin.

Bu sorun, yalnızca LoRA değil, target_modules kullanan tüm PEFT yöntemlerini (LoRA, LoHa, IA³ vb.) etkiler. Yöntemden bağımsız olarak tanısal adımlar aynıdır. Belirli bir mimarinin hangi modül adlarını kullandığından emin değilseniz, adaptörü yapılandırmadan önce modelin belgelendirmesini kontrol edin veya model.named_modules() ifadesini inceleyin.

Yüklenen bir PEFT modelinden kötü sonuçlar

Yüklenen bir PEFT modelinden düşük performans alınmasının birkaç nedeni olabilir ve bunlar aşağıda listelenmiştir. Sorunu hâlâ gideremiyorsanız, GitHub üzerinde başka birinin benzer bir sorun yaşayıp yaşamadığını kontrol edin; eğer bulamıyorsanız yeni bir sorun açın.

Bir sorun bildirirken, sorunu yeniden üreten minimal bir kod örneği sunmak çok yardımcı olur. Ayrıca, yüklenen modelin ince ayar öncesi modelle aynı düzeyde performans gösterip göstermediğini, rastgele bir düzeyde performans gösterip göstermediğini veya beklenenden yalnızca biraz daha kötü performans gösterip göstermediğini lütfen bildirin. Bu bilgi, sorunu daha hızlı tespit etmemize yardımcı olur.

Rastgele sapmalar

Eğer model çıktılarınız önceki çalıştırmalarla birebir aynı değilse, rastgele öğelerle ilgili bir sorun olabilir. Örneğin:

  1. Lütfen modelin .eval() modunda olduğundan emin olun; örneğin model dropout kullanıyorsa bu önemlidir.
  2. generate fonksiyonunu bir dil modeli üzerinde kullanıyorsanız rastgele örneklemeye dayalı bir süreç söz konusu olabilir; bu nedenle aynı sonucu elde etmek için rastgele bir tohum (seed) ayarlanmalıdır.
  3. eğer kuantizasyon kullandıysanız ve ağırlıkları birleştirdiyseniz, yuvarlama hataları nedeniyle küçük sapmalar beklenir

Yanlış yüklenen model

Modeli doğru şekilde yüklediğinizden emin olun. Yaygın bir hata, eğitilmiş bir modeli get_peft_model() ile yüklemeye çalışmaktır; bu yanlıştır. Bunun yerine, yükleme kodu şu şekilde olmalıdır:

from peft import PeftModel, PeftConfig

base_model = ...  # to load the base model, use the same code as when you trained it
config = PeftConfig.from_pretrained(peft_model_id)
peft_model = PeftModel.from_pretrained(base_model, peft_model_id)

Adaptörleri atlayan optimize edilmiş yürütme yolları

Bazı optimize edilmiş yürütme yolları, modül ağırlıklarını doğrudan okur; bunun yerine forward yöntemlerini çağırmaz. Bu durum, adaptör aktif olsa bile, birleştirilmemiş adaptörler tarafından yapılan değişiklikleri uyarı vermeden atlayabilir. Sorun, farklı modülleri ve PEFT yöntemlerini etkileyebilir.

Örneğin, PyTorch’un yerel torch.nn.TransformerEncoder bileşeni, değerlendirme sırasında torch.no_grad() veya torch.inference_mode() ile birleştirilmiş bir yol kullanabilir. Bu yol, TransformerEncoderLayer alt modüllerindeki adaptörleri atlayabilir; örneğin linear1 ve linear2 üzerindeki LoRA adaptörleri. Eğitim doğru çalışırken değerlendirme, adaptör değişikliklerini göz ardı edebilir. Bir yeniden üretim için #3976 sayfasına bakın.

Bu sorundan şüpheleniyorsanız, önce get_layer_status() ile adaptörün etkin ve aktif olduğunu kontrol edin. Değerlendirme modunda, aynı girdilerle adaptörün varlığı ve yokluğu durumundaki çıktıları karşılaştırın, ardından optimizasyon devre dışı bırakılarak tekrar karşılaştırın. Çıktıları değiştiren eğitilmiş bir adaptör kullanın, çünkü yeni başlatılmış LoRA adaptörleri genellikle bir etkiye sahip değildir. Küçük sayısal farklar normaldir.

Eager modda yerleşik bir kodlayıcıda birleştirilmemiş bir adaptör için, aynı girdi tensörü x için çıktıları karşılaştırın:

import torch

model.eval()
previous = torch.backends.mha.get_fastpath_enabled()
try:
    with torch.inference_mode():
        torch.backends.mha.set_fastpath_enabled(True)
        fast_output = model(x)

        torch.backends.mha.set_fastpath_enabled(False)
        reference_output = model(x)
finally:
    torch.backends.mha.set_fastpath_enabled(previous)

print((fast_output - reference_output).abs().max().item())

Etkinleştirilmiş bir backend bayrağı tek başına füzyonlu yolun çalıştığı anlamına gelmez; kullanım, model, girdiler ve çalışma zamanı koşullarına da bağlıdır. Kapsayan modülün forward uygulamasını doğrudan ağırlık erişimi veya füzyonlu operatör çağrıları için inceleyin. Forward hook'ları ile hata ayıklarken dikkatli olun: bir hook kaydının kendisi bir optimizasyonu devre dışı bırakabilir ve incelediğiniz davranışı değiştirebilir.

Eager modda yerel kodlayıcılar için, torch.backends.mha.set_fastpath_enabled(False) adaptörlerin birleştirilmemiş kalmasını sağlayan bir geçici çözümdür. Bu ayar işlem geneline etki eder, diğer modelleri ve performansı etkileyebilir ve eşzamanlı istekler tarafından bağımsız olarak değiştirilmemelidir. Diğer optimize yollar için, etkilenen optimizasyonu devre dışı bırakın veya uyarlanmış modülleri çağıran bir uygulama kullanın. PEFT yöntemi ve kuantizasyon kurulumu buna izin veriyorsa, adaptörleri merge_and_unload() ile birleştirip döndürülen modeli çıkarım için kullanabilirsiniz. Bu durumda adaptör değişiklikleri temel ağırlıklara dahil edilir. Birleştirme işlemi adaptör sarmalayıcılarını kaldırdığı için, adaptör değiştirmeniz veya eğitimi sürdürmeniz gerekiyorsa orijinal kontrol noktalarınızı (checkpoint) saklayın.

Rastgele başlatılmış katmanlar

Bazı görevlerde, rastgele başlatılmış katmanları hesaba katmak için yapılandırmada modules_to_save öğesinin doğru şekilde yapılandırılması önemlidir.

Örnek olarak, bir dil modelini sıra sınıflandırma için LoRA ile ince ayarladığınızda bu gereklidir çünkü 🤗 Transformers modelin üzerine rastgele başlatılmış bir sınıflandırma başlığı ekler. Bu katmanı modules_to_save içine eklemeseniz, sınıflandırma başlığı kaydedilmez. Modeli bir sonraki kez yüklediğinizde, farklı bir şekilde rastgele başlatılmış bir sınıflandırma başlığı elde edersiniz ve bu da tamamen farklı sonuçlara yol açar.

PEFT, yapılandırma içinde task_type argümanını sağlarsanız modules_to_save değerini doğru şekilde tahmin etmeye çalışır. Bu, standart adlandırma şemasını izleyen transformers modelleri için işe yaramalıdır. Yine de, tüm modellerin adlandırma şemasını izlediğini garanti edemediğimiz için her zaman iki kez kontrol etmek iyi bir fikirdir.

Rastgele başlatılmış katmanlara sahip bir transformers modeli yüklediğinizde, aşağıdaki türde bir uyarı görmelisiniz:

Some weights of <MODEL> were not initialized from the model checkpoint at <ID> and are newly initialized: [<LAYER_NAMES>].
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

Bahsedilen katmanlar, açıklanan sorunu önlemek için yapılandırmadaki modules_to_save alanına eklenmelidir.

healthcheck(), bu hatanın en yaygın biçimi olan, temel model yüklenirken yeni başlatılmış ancak modules_to_save içinde bulunmayan (örneğin task_type ayarlanmadığı için) bir dizi sınıflandırma, token sınıflandırma veya soru cevaplama başlığı için TASK_HEAD_NOT_SAVED uyarısı raporlar. Temel model, yapılarını yapılandırmada listelemiyorsa bu kontrol atlanır.

Örnek olarak, sıralı sınıflandırma için DeBERTa mimarisini kullanan bir model yüklenirken, aşağıdaki ağırlıkların yeni başlatıldığına dair bir uyarı görürsünüz: ['classifier.bias', 'classifier.weight', 'pooler.dense.bias', 'pooler.dense.weight']. Buradan, classifier ve pooler katmanlarının modules_to_save=["classifier", "pooler"] listesine eklenmesi gerektiği sonucu çıkar.

Sözlüğün genişletilmesi

Birçok dil ince ayarı görevinde, yeni tokenler tanıtıldığından modelin sözlüğünü genişletmek gereklidir. Bu, yeni tokenleri hesaba katmak için gömme katmanını genişletmeyi ve ince ayar yöntemine bağlı olarak, adaptörü kaydederken adaptör ağırlıklarının yanı sıra gömme katmanını da depolamayı gerektirir. Bunu parametre etkinliğine göre sıralanmış birkaç yolla gerçekleştirmek mümkündür:

  • eğitilebilir jetonlar, yalnızca belirtilen jetonları eğitin, isteğe bağlı olarak yalnızca güncellenen değerleri saklayın
  • gömme matrisinde bir adaptör eğitimi, isteğe bağlı olarak yalnızca güncellenen değerleri saklama
  • gömme katmanının tam ince ayarı

Eğitilebilir jetonlar kullanma

Eğitilebilir tokenlerden başlayalım; bu durumda LoRA entegrasyonu. Sadece yeni gömme (embedding) katmanlarını eğitmek ve başka hiçbir şeyi eğitmek istiyorsanız, bağımsız dokümantasyona bakın.

Gömme katmanının seçici token eğitimini etkinleştirmek için, yeni eklediğiniz tokenların kimliklerini trainable_token_indices parametresi aracılığıyla sağlamanız gerekir. Birden fazla gömme katmanı varsa, hedeflenecek katmanı isteğe bağlı olarak belirleyebilirsiniz. Bir Mistral modeli için bu şu şekilde görünebilir:

new_tokens = ['<think>', '</think>']
tokenizer.add_tokens(new_tokens)
base_model.resize_token_embeddings(len(tokenizer))

lora_config = LoraConfig(
    ...,
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(new_tokens)},
)

Modeliniz bağlı ağırlıklar (örneğin lm_head) kullanıyorsa, eğitilebilir jetonlar bu ağırlıkları çözmeye ve onları da güncel tutmaya çalışır; bu nedenle o durumda modules_to_save=["lm_head"] eklemeye gerek yoktur. Bu, yalnızca modelin ağırlıkları bağlamak için Transformers sözleşmesini kullandığı durumda çalışır.

model.save_pretrained ile modeli kaydetmek, gömme matrisinin yeniden boyutlandırılmış olması nedeniyle bir önlem olarak yalnızca farkı değil, tam gömme matrisini de kaydedebilir. Alan tasarrufu yapmak için, save_pretrained çağrılırken save_embedding_layers=False değerini ayarlayarak bu davranışı devre dışı bırakabilirsiniz. Gömme matrisini başka yollarla da değiştirmiyorsanız bunu yapmak güvenlidir; çünkü bu tür değişiklikler eğitilebilir tokenlar tarafından izlenmez.

Bir adaptör kullanarak, örneğin LoRA

Gömme katmanını hazırlamak için onu adaptör yapılandırmanızın target_modules alanına ekleyin. Örneğin, Mistral yapılandırması şu şekilde görünebilir:

config = LoraConfig(..., target_modules=["embed_tokens", "lm_head", "q_proj", "v_proj"])

target_modules listesine eklendikten sonra, PEFT, modelin get_input_embeddings ve get_output_embeddings yöntemlerine sahip olması durumunda, adaptör kaydedilirken gömme katmanını otomatik olarak saklar. Transformers modelleri için bu genellikle geçerlidir.

Modelin gömme katmanı Transformer’ın adlandırma şemasını takip etmiyorsa ancak yine de get_input_embeddings uyguluyorsa, adaptörü kaydederken save_embedding_layers=True parametresini manuel olarak geçirerek yine de kaydedebilirsiniz:

model = get_peft_model(...)
# train the model
model.save_pretrained("my_adapter", save_embedding_layers=True)

Çıkarım için önce temel modeli yükleyin ve modeli eğitmeden önce yaptığınız gibi yeniden boyutlandırın. Temel modeli yeniden boyutlandırdıktan sonra PEFT kontrol noktasını yükleyebilirsiniz.

Tam bir örnek için lütfen bu defterine göz atın.

Tam ince ayar

Tam ince ayar, VRAM veya depolama alanı açısından daha maliyetlidir ancak her şey başarısız olursa, bu yönteme başvurup sizin için işe yarayıp yaramadığını görebilirsiniz. Bunu, gömme katmanının adını modules_to_save parametresine ekleyerek gerçekleştirin. Bağlı katmanları da eklemeniz gerektiğini unutmayın, örneğin lm_head. LoRA ile bir Mistral modeli için örnek:

config = LoraConfig(..., modules_to_save=["embed_tokens", "lm_head"], target_modules=["q_proj", "v_proj"])

“Model checkpoint'ten ağırlıkların başlatılmadığı” konusunda bir uyarı alıyorsunuz

Bir görevde (örneğin sınıflandırma) eğitilmiş PEFT modelinizi yüklediğinizde, aşağıdaki gibi bir uyarı alabilirsiniz:

LlamaForSequenceClassification ağırlıklarının bazıları meta-llama/Llama-3.2-1B model kontrol noktasından başlatılmadı ve yeni başlatıldı: [‘score.weight’]. Tahmin ve çıkarım için kullanabilmek için bu modeli bir alt akış görevinde EĞİTMENİZ önerilir.

Bu görünüm korkutucu olsa da, büyük olasılıkla endişelenilecek bir durum değildir. Bu uyarı Transformers kütüphanesinden gelir ve PEFT'ye özgü bir uyarı değildir. Bu uyarı, taban modele rastgele başlatılmış bir sınıflandırma başlığının (score) eklendiğini ve anlamlı tahminler üretebilmesi için bu başlığın eğitilmesi gerektiğini bildirir.

Bu uyarıyı modelin eğitiminden önce alırsanız, PEFT yapılandırmasına task_type argümanını doğru şekilde iletmişseniz sınıflandırma başının eğitilebilir olmasını otomatik olarak sağlar.

from peft import LoraConfig, TaskType

lora_config = LoraConfig(..., task_type=TaskType.SEQ_CLS)

Sınıflandırma başınız Transformers'taki (nadir bir durum olmakla birlikte) olağan adlandırma kurallarına uymuyorsa, başın adını modules_to_save içinde PEFT'ye açıkça bildirmeniz gerekir.

lora_config = LoraConfig(..., modules_to_save=["name-of-classification-head"])

Sınıflandırma başlığının adını kontrol etmek için modeli yazdırın; son modül olmalıdır.

Eğer bu uyarıyı, modelin eğitiminden sonra, PEFT modelini yüklediğinizde çıkarım kodunuzdan alıyorsanız, her zaman önce Transformers modelini yüklemeniz gerekir. Transformers, sonrasında PEFT ağırlıklarını yükleyeceğinizi bilmediği için yine de bu uyarıyı verir.

Her zamanki gibi, modelin çıkarım için doğru çalıştığını doğrulamak için üzerinde bazı doğrulama çalışmaları yapmak en iyi uygulamadır.

Eğitim sağlık kontrolü çalıştırın

Eğitimden önce, PEFT modelinin durumuna ilişkin kompakt ve insan tarafından okunabilir bir özet almak için print_healthcheck() kullanın. Bu özet, model ve katman durum API'lerinden (bkz. sonraki bölüm) türetilir ve tutarsız adaptörler, birleştirilmiş adaptörler veya şüpheli bir eğitilebilir parametre sayısı gibi şüpheli durumları işaretler.

peft_model.print_healthcheck()

Raporun sonunda, düzensizlikler tespit edilirse dahil edilen “Findings” bölümüne özellikle dikkat edin.

JSON-serializable bir sözlük çıktısı tercih ediyorsanız, bunun yerine healthcheck() kullanın:

healthcheck = peft_model.healthcheck()
print(healthcheck.get("findings", "all good")

Bu kontrol yalnızca modeli ve adaptörlerini denetler. Eğitim döngünüzü, optimizatörü veya veri setinizi doğrulamaz. Prompt öğrenme ve adaption prompt için rapor, model bilgilerini ve parametre sayılarını gösterir ancak bu yöntemlerin desteklemediği katman durumunu içermez.

Katman ve model durumunu kontrol edin

Bazen bir PEFT modeli kötü bir duruma gelebilir, özellikle birden çok adaptörle çalışırken. Hangi adaptörlerin mevcut olduğu, hangisinin aktif olduğu, hangisinin birleştirildiği gibi konularda kafa karışıklığı yaşanabilir. Bu sorunu araştırmaya yardımcı olmak için get_layer_status() ve get_model_status() yöntemlerini çağırın.

get_layer_status() yöntemi, her hedeflenen katmanın etkin, birleştirilmiş ve kullanılabilir adaptörlerine ilişkin ayrıntılı bir genel bakış sunar.

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

>>> model_id = "google/flan-t5-small"
>>> model = AutoModel.from_pretrained(model_id)
>>> model = get_peft_model(model, LoraConfig())

>>> model.get_layer_status()
[TunerLayerStatus(name='model.encoder.block.0.layer.0.SelfAttention.q',
                  module_type='lora.Linear',
                  enabled=True,
                  active_adapters=['default'],
                  merged_adapters=[],
                  requires_grad={'default': True},
                  available_adapters=['default']),
 TunerLayerStatus(name='model.encoder.block.0.layer.0.SelfAttention.v',
                  module_type='lora.Linear',
                  enabled=True,
                  active_adapters=['default'],
                  merged_adapters=[],
                  requires_grad={'default': True},
                  available_adapters=['default']),
...]

>>> model.get_model_status()
TunerModelStatus(
    base_model_type='T5Model',
    adapter_model_type='LoraModel',
    peft_types={'default': 'LORA'},
    trainable_params=344064,
    total_params=60855680,
    num_adapter_layers=48,
    enabled=True,
    active_adapters=['default'],
    merged_adapters=[],
    requires_grad={'default': True},
    available_adapters=['default'],
)

Model durumu çıktısında "irregular" yazan girdilere dikkat etmelisiniz. Bu, PEFT'nin modelde tutarsız bir durum tespit ettiğini gösterir. Örneğin, merged_adapters="irregular" ise, en az bir adaptörün bazı hedef modüllerde birleştirildiği ancak diğerlerinde birleştirilmediği anlamına gelir. Sonuç olarak çıkarım sonuçları büyük olasılıkla hatalı olacaktır.

Bu sorunu çözmek için en iyi yol, tüm model ve adaptör kontrol noktasını (checkpoint) yeniden yüklemektir. Model üzerinde hatalı işlemler yapmadığınızdan emin olun; örneğin, bazı modüllerde adaptörleri manuel olarak birleştirip diğerlerinde birleştirmeyin.

Katman durumunu daha kolay görsel inceleme için pandas DataFrame'ine dönüştürün.

from dataclasses import asdict
import pandas as pd

df = pd.DataFrame(asdict(layer) for layer in model.get_layer_status())

PEFT katmanlarını altta kullanan PEFT olmayan modeller için bu bilgiyi almak mümkündür, ancak bu durumda base_model_type veya peft_types gibi bazı bilgiler belirlenemez. Örneğin, bir diffusers modelinde bunu şu şekilde çağırabilirsiniz:

>>> import torch
>>> from diffusers import StableDiffusionPipeline
>>> from peft import get_model_status, get_layer_status

>>> path = "runwayml/stable-diffusion-v1-5"
>>> lora_id = "takuma104/lora-test-text-encoder-lora-target"
>>> pipe = StableDiffusionPipeline.from_pretrained(path, dtype=torch.float16)
>>> pipe.load_lora_weights(lora_id, adapter_name="adapter-1")
>>> pipe.load_lora_weights(lora_id, adapter_name="adapter-2")
>>> pipe.set_lora_device(["adapter-2"], "cuda")
>>> get_layer_status(pipe.text_encoder)
[TunerLayerStatus(name='text_model.encoder.layers.0.self_attn.k_proj',
                  module_type='lora.Linear',
                  enabled=True,
                  active_adapters=['adapter-2'],
                  merged_adapters=[],
                  requires_grad={'adapter-1': False, 'adapter-2': True},
                  available_adapters=['adapter-1', 'adapter-2'],
                  devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']}),
 TunerLayerStatus(name='text_model.encoder.layers.0.self_attn.v_proj',
                  module_type='lora.Linear',
                  enabled=True,
                  active_adapters=['adapter-2'],
                  merged_adapters=[],
                  requires_grad={'adapter-1': False, 'adapter-2': True},
                  devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']}),
...]

>>> get_model_status(pipe.unet)
TunerModelStatus(
    base_model_type='other',
    adapter_model_type='None',
    peft_types={},
    trainable_params=797184,
    total_params=861115332,
    num_adapter_layers=128,
    enabled=True,
    active_adapters=['adapter-2'],
    merged_adapters=[],
    requires_grad={'adapter-1': False, 'adapter-2': True},
    available_adapters=['adapter-1', 'adapter-2'],
    devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']},
)

Hız

Adaptör ağırlıklarının yüklenmesi yavaştır

LoRA ağırlıkları gibi adaptörlerin yüklenmesi, temel modelin yüklenmesine kıyasla genellikle hızlı olmalıdır. Ancak adaptör ağırlıklarının oldukça büyük olduğu veya kullanıcıların çok sayıda adaptör yüklemesi gerektiği durumlar olabilir; bu durumda yükleme süresi birikebilir. Bunun nedeni, adaptör ağırlıklarının önce başlatılıp ardından yüklenen ağırlıklarla üzerine yazılmasıdır; bu işlem israftır. Yükleme süresini hızlandırmak için low_cpu_mem_usage=True argümanını from_pretrained() ve load_adapter() fonksiyonlarına iletebilirsiniz.

Bu seçenek farklı kullanım senaryolarında iyi çalışırsa, gelecekte adaptör yükleme için varsayılan haline gelebilir.

Tekrarlanabilirlik

Batch norm kullanan modeller

Taban modelin batch norm kullandığı (ör. torch.nn.BatchNorm1d veya torch.nn.BatchNorm2d) eğitilmiş bir PEFT modelini yüklerken, tam olarak aynı çıktıları üretemediğinizi fark edebilirsiniz. Bunun nedeni, batch norm katmanlarının eğitim sırasında çalışan istatistikleri (running stats) takip etmesi, ancak bu istatistiklerin PEFT checkpoint'inin bir parçası olmamasıdır. Dolayısıyla PEFT modelini yüklediğinizde, taban modelin çalışan istatistikleri (yani PEFT ile eğitimden önceki değerler) kullanılacaktır.

Kullanım durumunuza bağlı olarak bu büyük bir sorun olmayabilir. Ancak çıktıların %100 yeniden üretilebilir olması gerekiyorsa, bunu modules_to_save parametresine batch norm katmanlarını ekleyerek sağlayabilirsiniz. Aşağıda, resnet ve LoRA kullanılarak bunun bir örneği verilmiştir. modules_to_save=["classifier", "normalization"] olarak ayarladığımıza dikkat edin. Görevimiz görüntü sınıflandırma olduğu için "classifier" argümanına ihtiyacımız var ve PEFT checkpoint'inde batch norm katmanlarının kaydedilmesini sağlamak için "normalization" argümanını ekliyoruz.

from transformers import AutoModelForImageClassification
from peft import LoraConfig, get_peft_model

model_id = "microsoft/resnet-18"
base_model = AutoModelForImageClassification.from_pretrained(self.model_id)
config = LoraConfig(
    target_modules=["convolution"],
    modules_to_save=["classifier", "normalization"],
),

Kullandığınız model türüne bağlı olarak, batch norm katmanlarının "normalization" dışında farklı adlar taşıması mümkündür; bu nedenle adın model mimarinizle eşleştiğinden emin olun.

Sürüm uyumsuzluğu

Beklenmeyen bir anahtar kelime argümanı nedeniyle yapılandırma yüklenirken hata

Aşağıda gösterilen türden bir hata ile karşılaştığınızda, yüklemeye çalıştığınız adaptörün, sisteminizde kurulu PEFT sürümünden daha yeni bir PEFT sürümüyle eğitildiği anlamına gelir.

TypeError: LoraConfig.__init__() got an unexpected keyword argument <argument-name>

Bu sorunu çözmek için en iyi yol, en son PEFT sürümünü yüklemektir:

python -m pip install -U PEFT

Eğer adaptör, PEFT'nin kaynak kurulumundan (PEFT'nin yayınlanmamış bir sürümünden) eğitildiyse, PEFT'yi de kaynaktan kurmanız gerekir.

python -m pip install -U git+https://github.com/huggingface/peft.git

PEFT'yi yükseltmeniz mümkün değilse, deneyebileceğiniz bir geçici çözüm vardır.

Hata mesajının, bilinmeyen anahtar kelime argümanının adının foobar olduğunu varsayalım. Bu PEFT adaptörünün adapter_config.json dosyasının içinde foobar girdisini arayın ve dosyadan silin. Ardından dosyayı kaydedin ve modeli tekrar yüklemeyi deneyin.

Bu çözüm çoğu durumda işe yarar. foobar için varsayılan değer olduğu sürece yok sayılabilir. Ancak başka bir değere ayarlandığında hatalı sonuçlar alırsınız. Önerilen çözüm PEFT sürümünü yükseltmektir.

Uydu yönetimi

Aynı anda birden çok adaptör kullanma

PEFT, aynı model üzerinde birden fazla adaptör oluşturmanıza olanak tanır. Bu, birçok durumda faydalı olabilir. Örneğin, çıkarım (inference) sırasında, her ince ayarlı model için temel modeli ayrı ayrı yüklemek yerine (bu daha fazla bellek maliyeti gerektirir), aynı temel modelden iki ince ayarlı model sunmak isteyebilirsiniz. Ancak, birden fazla adaptör aynı anda etkinleştirilebilir. Bu sayede, model tüm bu adaptörlerden gelen öğrenmeleri aynı anda kullanabilir. Bir örnek olarak, bir difüzyon modeliniz varsa, stili değiştirmek için bir LoRA adaptörü ve konuyu değiştirmek için farklı bir adaptör kullanmak isteyebilirsiniz.

Birden fazla adaptörün aynı anda etkinleştirilmesi, prompt öğrenme yöntemleri (p-tuning, prefix tuning vb.) dışında tüm PEFT yöntemlerinde (LoRA, LoHa, IA³ vb.) genel olarak mümkündür. Aşağıdaki örnek bunu nasıl başaracağınızı göstermektedir:

from transformers import AutoModelForCausalLM
from peft import PeftModel

model_id = ...
base_model = AutoModelForCausalLM.from_pretrained(model_id)
model = PeftModel.from_pretrained(base_model, lora_path_0)  # default adapter_name is 'default'
model.load_adapter(lora_path_1, adapter_name="other")
# the 'other' adapter was loaded but it's not active yet, so to activate both adapters:
model.base_model.set_adapter(["default", "other"])

Yukarıdaki örnekte, model.base_model.set_adapter(["default", "other"]) çağrısını yapmamız gerektiğini görebilirsiniz. model.set_adapter(["default", "other"]) çağrısını neden yapamıyoruz? Ne yazık ki bu mümkün değil çünkü daha önce açıklandığı gibi, bazı PEFT yöntemleri aynı anda birden fazla adaptörün etkinleştirilmesini desteklemiyor.

Aynı anda iki adaptörün eğitilmesi de mümkündür, ancak her iki adaptörün ağırlıklarının optimizör tarafından bilindiğinden emin olmak için dikkatli olmalısınız. Aksi takdirde, yalnızca bir adaptör güncellemeler alır.

from transformers import AutoModelForCausalLM
from peft import LoraConfig, get_peft_model

model_id = ...
base_model = AutoModelForCausalLM.from_pretrained(model_id)
lora_config_0 = LoraConfig(...)
lora_config_1 = LoraConfig(...)
model = get_peft_model(base_model, lora_config_0)
model.add_adapter(adapter_name="other", peft_config=lora_config_1)

Şimdi şunu çağırsak:

from transformers import Trainer

trainer = Trainer(model=model,  ...)
trainer.train()

veya

optimizer = torch.optim.AdamW([param for param in model.parameters() if param.requires_grad], ...)

ardından ikinci LoRA adaptörü ("other") eğitilmeyecektir. Bunun nedeni, bu anda pasif olması ve bu da parametrelerindeki requires_grad özniteliklerinin False olarak ayarlanması ve optimizatörün onu yok sayması demektir. Bu nedenle, eğitilmesi gereken tüm adaptörleri optimizatörü başlatmadan önce etkinleştirdiğinizden emin olun:

# activate all adapters
model.base_model.set_adapter(["default", "other"])
trainer = Trainer(model=model,  ...)
trainer.train()

Bu bölüm, aynı model üzerinde aynı türden birden çok adaptörün kullanılmasını ele alır; örneğin, aynı anda birden çok LoRA adaptörünün kullanılması. Aynı model üzerinde farklı türlerde adaptörlerin kullanılmasına uygulanmaz; örneğin bir LoRA adaptörü ve bir LoHa adaptörü. Bunun için lütfen PeftMixedModel öğesini inceleyin.

Yalnızca etkin adaptörlerin bir kısmını birleştirme

Adaptör ağırlıkları taban ağırlıklarla birleştirildiğinde, etkilenen katmanlar ileri geçiş sırasında artık herhangi bir adaptör uygulamaz, yalnızca birleştirilmiş taban ağırlıklarını kullanır. Dolayısıyla, birden fazla adaptör etkin olsa da bunlardan yalnızca bazıları birleştirildiyse, hâlâ etkin olan ancak birleştirilmemiş adaptörler sessizce uygulanmaz:

model = get_peft_model(base_model, lora_config_0, adapter_name="default")
model.add_adapter("other", lora_config_1)
model.base_model.set_adapter(["default", "other"])
output_both = model(**inputs)

model.merge_adapter(adapter_names=["default"])
output_merged = model(**inputs)  # this is *not* the same as output_both

Burada output_merged, "other" hâlâ etkin olarak listelenmesine rağmen yalnızca "default" adaptörünün çıktısıdır:

>>> model.get_layer_status()[0].active_adapters
['default', 'other']
>>> model.get_layer_status()[0].merged_adapters
['default']

Aktif olmayan bir adaptör birleştirildiğinde de aynı durum geçerlidir: o andan itibaren model, birleştirilen adaptörün çıktısını döndürür ve aktif olan adaptör yok sayılır. Her iki durumda da hata veya uyarı verilmez. Adaptör ağırlıkları kendileri etkilenmediğinden, unmerge_adapter() çağrısı birleşik çıktıyı geri yükler.

Bunu önlemek için, tüm etkin adaptörleri birleştirin, yani adapter_names olmadan model.merge_adapter() çağrısını yapın, ya da hangi adaptörlerin etkin olduğunu değiştirmeden önce birleştirmeyi geri alın.

Bu davranış, birleştirme (merging) destekleyen PEFT yöntemleri arasında (LoRA, LoHa, LoKr, IA³, OFT vb.) tutarlıdır, çünkü hepsi ileri geçişte (forward pass) aynı mantığı paylaşır.

Bu davranış kafa karıştırıcıdır ve PEFT v1.0 sürümünde değiştirilmesi planlanmaktadır.

Update on GitHub