ShadowPEFT

ShadowPEFT, donmuş bir taban yalnızca-çözücü modeline, omurgayla paralel çalışan hafif, ön eğitilebilir bir gölge ağı ekler. Küçük bir gölge omurgası, başlangıç gölge durumu s^(0) üretir; bu durum daha sonra taban modelin çözücü döngüsünde ilerler: her hedeflenen blokta, taban gizli durumları ile gölge durumu arasındaki fark, blok girdisine geri enjekte edilir (düşük-ranklı bir düzeltme) ve gölge durumu, blok çıktısından hesaplanan kapılı bir artıklı güncelleme ile ileri taşınır. Yalnızca gölge bileşenleri eğitilir; taban model donmuş kalır.

Input
  ├──► Shadow backbone (small, trainable) ──► s^(0)
  └──► Base model (frozen, large)
         block_0 ◄── inject(h, s) ─► h_0 ──► update ─► s_1
         block_1 ◄── inject(h, s) ─► h_1 ──► update ─► s_2
         ...                       (the (hidden, shadow) pair rides the loop together)

Uyarlanma, katman uzayında girdiye bağlı bir yörünge (gölge durumu verilerle birlikte evrilir) olduğundan, statik bir ağırlık uzayı farkı değildir; bu nedenle ShadowPEFT taban ağırlıklarına birleştirilemez. merge, merge_adapter veya merge_and_unload çağrıldığında açık bir hata yükseltilir. Transformers dil modelleri için, hafif gölge ağını tek başına model.base_model.unload_shadow() ile elde edebilirsiniz; bu, bağımsız bir DetachedShadowModel döndürür. Diffusers modelleri için bağımsız boşaltma desteklenmez, çünkü tam bir gürültü azaltıcıyı yeniden oluşturmak mimariye özgüdür.

Birden çok adaptör eklemek, set_adapter ile aralarında geçiş yapmak, silmek ve etkinleştirme/devre dışı bırakma işlemleri, diğer PEFT yöntemlerinde olduğu gibi çalışır. Gölge durum, ağ üzerinden tek bir yörünge olduğu için aynı anda yalnızca bir adaptör etkin olabilir.

Gölge omurga, ShadowConfig.shadow_model tarafından kontrol edilen iki şekilde oluşturulabilir:

• "mirror" (varsayılan): daha küçük bir gölge omurga otomatik olarak oluşturulur. Dil modelleri, temel mimarinin küçültülmüş bir kopyasını kullanır. Kayıtlı bir arka uca sahip Diffusers mimarileri, seçilen temel ağırlıklardan başlatılan, küçültülmüş bir benzer mimariye sahip model kullanır; arka ucu olmayan uyumlu mimariler ise token bazlı bir MLP'ye geri düşer. Gölge gizli boyutu temelden farklıysa, bu farkı köprüleyen eğitilmiş bir projeksiyon kullanılır.
• bir model kimliği veya yerel yol: omurga, daha küçük bir önceden eğitilmiş model olarak yüklenir. Transformers modelleri AutoModel kullanır; kayıtlı Diffusers arka uçları kendi uyumlu kontrol noktası yükleme işlemlerini tanımlar.

Mimariye duyarlı Diffusers desteği, model sınıfından otomatik olarak seçilir. Flux2 şu anda kayıtlı bir arka uca sahiptir; diğer uyumlu transformer tabanlı Diffusers modelleri genel MLP yedeğini kullanır. Tam bir denoiser'ın yeniden oluşturulması mimariye özgü olduğundan, bağımsız unload_shadow() tüm Diffusers modelleri için desteklenmemeye devam etmektedir.

LoRA tarzı yöntemlere kıyasla ShadowPEFT daha fazla parametre ve hesaplama ekler (paralel bir ağ çalıştırır ve tüm decoder bloklarını sarar), ancak adaptör, merkezi olarak eğitilebilen, görevler arasında yeniden kullanılabilen ve önceden eğitilmiş küçük bir modelden başlatılabilen kendi kendine yeten bir ağdır. İsteğe bağlı bir yardımcı kayıp (auxiliary_loss_weight), görev başlığını başlangıç gölge durumu s^(0) üzerine uygular ve görev kaybına ekler; bu da sökülebilir gölge yolunun görevi kendi başına çözmesini teşvik eder. Neden-sonuç LM için temel çıktı başlığı yeniden kullanılır; standart PEFT mekanizması üzerinden eğitip kaydetmek için "lm_head" öğesini modules_to_save içine dahil edin.

KV önbelleği

ShadowPEFT, dual KV önbelleği ile artımlı çözümlendirmeyi destekler: biri dondurulmuş temel model için, diğeri gölge omurga için. Enjekte/güncelle işlemleri token-yereldir, bu nedenle yeni bir token yalnızca kendi gölge durumu s değerine ihtiyaç duyar; nedensellik, önek temel anahtar/değerlerin (enjeksiyon altında hesaplanan) geçerli kalmasını sağlar. Eşleştirilmiş nesne ShadowCache'tir ve use_cache=True olduğunda past_key_values olarak döndürülür. generate() çağrısına use_cache=True parametresini normalde olduğu gibi iletebilirsiniz.

out = model.generate(input_ids, max_new_tokens=32)  # dual KV cache enabled by default
# or explicitly:
out = model.generate(input_ids, use_cache=True, max_new_tokens=32)

use_cache=False hâlâ çalışır ve her adımda tam diziyi yeniden işler (hata ayıklama için faydalıdır).

Kullanım

from transformers import AutoModelForCausalLM
from peft import ShadowConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")
config = ShadowConfig(r=8, shadow_num_hidden_layers=1, task_type="CAUSAL_LM")
model = get_peft_model(model, config)
model.print_healthcheck()

out = model.generate(input_ids, max_new_tokens=32)

Daha küçük bir önceden eğitilmiş modelden gölge omurgayı başlatmak için, kimliğini veya yolunu shadow_model olarak iletin:

config = ShadowConfig(shadow_model="Qwen/Qwen3-0.6B", task_type="CAUSAL_LM")
model = get_peft_model(base_model, config)

Gölge yolunun değerlendirilmesi

Varsayılan olarak model çıktısı (logits), gölge uyumlu temel model'dir: gölge düzeltmeleri, her katmanda temel modelin gizli durumlarına enjekte edilir, bu nedenle logits zaten ShadowPEFT'yi yansıtır (karşılaştırma için düz temel modeli almak için model.disable_adapter() kullanın). Yardımcı kayıp, gölge yolunu görevi kendi başına çözmek için ayrıca eğitir.

Transformers dil modeli için bağımsız gölge ağını (ayrılabilir, hafif model — merge_and_unload'ın ShadowPEFT karşılığı) değerlendirmek için unload_shadow() kullanın. Bu yöntem, head(projection(backbone(x))) ifadesini, diğer herhangi bir model gibi değerlendirebileceğiniz normal bir görev modeli olarak döndürür: bir nedensel-LM görevi için üretim yeteneğine sahip bir nedensel LM'dir (generate() ve KV önbellekleme desteklenir) ve bir dizi sınıflandırma görevi için son token'ı havuzlar ve sınıf logitlerini döndürür. Bu yöntemin bir Diffusers modeli için çağrılması NotImplementedError hatası oluşturur.

shadow = model.base_model.unload_shadow()  # a DetachedShadowModel (a PreTrainedModel)
shadow.eval()
# causal LM:
out = shadow.generate(input_ids, max_new_tokens=32)
# sequence classification:
logits = shadow(input_ids=input_ids, attention_mask=attention_mask).logits  # (batch, num_labels)

Varsayılan olarak (copy=False) döndürülen model, modüllerini PEFT modeliyle paylaşır ve dondurulmuş temel giriş gömme katmanlarını paylaşan bir gölge omurga, bunlara bir alt modül olmayan bir referans üzerinden erişir. Bu durum değerlendirme için uygundur, ancak save_pretrained'in gömme tablosu olmadan bir kontrol noktası yazacağı anlamına gelir. Bağımsız modeli kaydetmek veya göndermek istediğinizde copy=True parametresini iletin:

shadow = model.base_model.unload_shadow(copy=True)
shadow.save_pretrained("standalone-shadow")

Karma performans değerlendirmesi genel bakış

API

ShadowConfig

ShadowModel

ShadowCache