PEFT documentation

ShadowPEFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ShadowPEFT

ShadowPEFT melengkapi model decoder-only beku dengan jaringan shadow yang ringan dan dapat dilatih ulang yang berjalan paralel dengan backbone. Backbone shadow kecil menghasilkan state shadow awal s^(0), yang kemudian mengikuti loop decoder model dasar: pada setiap blok yang ditargetkan, selisih antara hidden states dasar dan state shadow disuntikkan kembali ke input blok (koreksi low-rank), dan state shadow diperbarui melalui pembaruan residual bergerbang yang dihitung dari output blok. Hanya komponen shadow yang dilatih; model dasar tetap beku.

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)

Karena adaptasi merupakan lintasan yang bergantung pada input di ruang lapisan (bayangan keadaan berevolusi bersama data) dan bukan delta ruang bobot yang statis, ShadowPEFT tidak dapat digabungkan ke dalam bobot dasar. Memanggil merge, merge_adapter, atau merge_and_unload akan memicu error eksplisit. Untuk model bahasa Transformers, Anda dapat memperoleh jaringan bayangan ringan secara mandiri dengan model.base_model.unload_shadow(), yang mengembalikan DetachedShadowModel yang berdiri sendiri. Unloading mandiri tidak didukung untuk model Diffusers karena rekonstruksi denoiser lengkap bersifat spesifik arsitektur.

Menambahkan beberapa adapter, berpindah di antara mereka dengan set_adapter, menghapusnya, serta mengaktifkan/menonaktifkannya semuanya bekerja seperti pada metode PEFT lainnya. Hanya satu adapter yang dapat aktif pada satu waktu, karena shadow state merupakan satu lintasan tunggal melalui jaringan.

Shadow backbone dapat dibangun dengan dua cara, dikendalikan oleh ShadowConfig.shadow_model:

  • "mirror" (default): sebuah backbone bayangan yang lebih kecil dibuat secara otomatis. Model bahasa menggunakan salinan tereduksi dari arsitektur dasar. Arsitektur Diffusers dengan backend yang terdaftar menggunakan model arsitektur serupa yang tereduksi dan diinisialisasi dari bobot dasar yang dipilih; arsitektur kompatibel tanpa backend kembali ke MLP residual per token. Ketika ukuran tersembunyi bayangan berbeda dari dasar, proyeksi yang dilatih menjembatani kesenjangan tersebut.
  • id model atau path lokal: backbone dimuat sebagai model pre-trained yang lebih kecil. Model Transformers menggunakan AutoModel; backend Diffusers yang terdaftar mendefinisikan pemuatan checkpoint kompatibel mereka sendiri.

Dukungan Diffusers yang sadar arsitektur dipilih secara otomatis dari kelas model. Flux2 saat ini memiliki backend yang terdaftar; model Diffusers berbasis transformer lainnya yang kompatibel menggunakan fallback MLP generik. Pemanggilan unload_shadow() mandiri tetap tidak didukung untuk semua model Diffusers karena rekonstruksi denoiser yang lengkap bersifat spesifik arsitektur.

Dibandingkan dengan metode bergaya LoRA, ShadowPEFT menambahkan lebih banyak parameter dan komputasi (jalankan jaringan paralel dan membungkus seluruh blok decoder), tetapi adapter-nya adalah jaringan mandiri yang dapat dilatih secara terpusat, digunakan kembali di berbagai tugas, dan diinisialisasi dari model kecil yang telah dilatih. Loss tambahan opsional (auxiliary_loss_weight) menerapkan task head ke keadaan bayangan awal s^(0) dan menambahkannya ke loss tugas, mendorong jalur bayangan yang dapat dilepas untuk menyelesaikan tugas secara mandiri. Untuk LM kausal, kepala output dasar digunakan kembali; sertakan "lm_head" di modules_to_save untuk melatih dan menyimpannya melalui mekanisme PEFT standar.

KV cache

ShadowPEFT mendukung decoding inkremental dengan KV cache dual: satu untuk model dasar yang dibekukan dan satu untuk shadow backbone. Inject/update bersifat lokal per token, sehingga token baru hanya memerlukan state shadow-nya sendiri s; kausalitas menjaga kunci/nilai prefix dasar (yang dihitung di bawah injeksi) tetap valid. Objek berpasangannya adalah ShadowCache, dikembalikan sebagai past_key_values ketika use_cache=True. Anda dapat meneruskan use_cache=True ke generate() seperti biasa.

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 masih berfungsi dan memproses ulang seluruh urutan pada setiap langkah (berguna untuk debugging).

Penggunaan

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)

Untuk menginisialisasi shadow backbone dari model pre-trained yang lebih kecil, lewati id atau path-nya sebagai shadow_model:

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

Mengevaluasi jalur bayangan

Secara default, output model (logits) adalah model dasar yang diadaptasi bayangan: koreksi bayangan disuntikkan ke dalam hidden states model dasar di setiap lapisan, sehingga logits sudah mencerminkan ShadowPEFT (gunakan model.disable_adapter() untuk mendapatkan model dasar polos perbandingan). Loss tambahan juga melatih jalur bayangan untuk menyelesaikan tugas secara mandiri.

Untuk mengevaluasi standalone shadow network untuk model bahasa Transformers (model yang dapat dilepas dan ringan β€” padanan ShadowPEFT dari merge_and_unload), gunakan unload_shadow(). Metode ini mengembalikan head(projection(backbone(x))) sebagai model tugas biasa yang dapat dievaluasi seperti model lainnya: untuk tugas causal-LM, model ini adalah causal LM yang mampu melakukan generasi (mendukung generate() dan KV caching), dan untuk tugas klasifikasi-sekuens, model ini melakukan pooling pada token terakhir dan mengembalikan logits kelas. Memanggil metode ini untuk model Diffusers akan memicu NotImplementedError.

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)

Secara default (copy=False) model yang dikembalikan berbagi modulnya dengan model PEFT, dan shadow backbone yang berbagi input embeddings base yang dibekukan mencapai modul tersebut melalui referensi yang bukan merupakan submodul. Hal ini tidak masalah untuk evaluasi, tetapi artinya save_pretrained akan menulis checkpoint tanpa tabel embedding. Gunakan copy=True ketika Anda ingin menyimpan atau mendorong model standalone:

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

Ikhtisar benchmark

API

ShadowConfig

kelas peft.ShadowConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falsetarget_modules: list[str] | str | None = Noneexclude_modules: list[str] | str | None = Noner: int = 8shadow_alpha: float = 0.1shadow_dropout: float = 0.2init_weights: bool = Trueshadow_model: str = 'mirror'shadow_num_hidden_layers: int | None = Noneshadow_hidden_size: int | None = Noneshadow_num_attention_heads: int | None = Noneshadow_intermediate_size: int | None = Noneshare_embeddings: bool = Trueupdate_hidden_size: int | None = Noneauxiliary_loss_weight: float = 0.05layers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = Nonemodules_to_save: list[str] | None = None )

Parameter

  • target_modules (Optional[Union[list[str], str]]) β€” Blok transformer yang akan dibungkus dengan mekanisme bayangan (blok decoder utuh, bukan lapisan linear). Dapat berupa daftar nama modul, atau regex, misalnya r'.*\.layers\.\d+$' untuk menargetkan setiap blok decoder. Nilainya secara default adalah None, yang berarti setiap blok decoder dari model dasar akan dibungkus. Perhatikan bahwa blok yang dibungkus harus berurutan, karena status bayangan mengikuti loop decoder dari blok yang dibungkus pertama hingga yang terakhir.
  • exclude_modules (Optional[Union[list[str], str]]) β€” Nama-nama modul yang tidak akan dibungkus dengan mekanisme bayangan, diberikan sebagai daftar atau regex. Nilainya secara bawaan adalah None.
  • r (int) β€” Rank dari bottleneck injeksi low-rank W_down / W_up. Defaultnya adalah 8.
  • shadow_alpha (float) β€” Kekuatan koreksi yang disuntikkan ke input blok (Persamaan 4). Nilai default adalah 0.1.
  • shadow_dropout (float) β€” Probabilitas dropout yang diterapkan pada sinyal diskrepansi sebelum bottleneck (Persamaan 3). Nilainya secara default adalah 0.2.
  • init_weights (bool) β€” Apakah akan menginisialisasi W_up dengan nol sehingga injeksi menjadi no-op di awal pelatihan (mengikuti konvensi B=0 dari LoRA). Jangan ubah ini kecuali Anda tahu apa yang Anda lakukan. Defaultnya adalah True.
  • shadow_model (str) β€” Cara membangun shadow backbone. "mirror" (default) membangun backbone baru dengan arsitektur yang sama seperti model dasar tetapi dengan lapisan yang lebih sedikit/kecil (lihat override shadow_* di bawah). Arsitektur Diffusers dengan Shadow backend yang terdaftar menggunakan model serupa arsitektur yang direduksi; diffusion transformer kompatibel lainnya kembali ke MLP token-wise generik. String lain apa pun diperlakukan sebagai id model atau jalur lokal. Checkpoint shadow Transformers yang β€œdiproyeksikan” (model_type == "causal_lm_with_hidden_projection", misalnya shadow-llm/Qwen3-0.6B-H8B) memuat backbone terlatihnya bersama dengan proyeksi shadow-hidden -> base-hidden yang dilatih. Checkpoint Diffusers eksplisit memerlukan backend terdaftar; saat ini Flux2 didukung.
  • shadow_num_hidden_layers (Optional[int]) β€” Kedalaman dari shadow backbone yang dibangun otomatis ("mirror"). Untuk Flux2, ini membuat jumlah blok double-stream yang diminta dan dua kali lipat jumlah blok single-stream; untuk fallback Diffusers generik, ini adalah jumlah blok residual MLP. Nilainya secara default adalah None (1 layer).
  • shadow_hidden_size (Optional[int]) β€” Ukuran tersembunyi dari shadow backbone yang dibangun secara otomatis; dapat berbeda dari ukuran tersembunyi dasar (sebuah proyeksi disisipkan secara otomatis). Backend arsitektur dapat memberlakukan batasan tambahan; reduksi Flux2 harus mempertahankan dimensi kepala perhatian dasarnya. Bawaan adalah None (sama dengan model dasar).
  • shadow_num_attention_heads (Optional[int]) β€” Jumlah attention heads dari shadow backbone yang dibangun secara otomatis. Nilainya secara default adalah None (sama dengan model dasar). Opsi ini digunakan oleh backend yang sadar arsitektur, tetapi tidak oleh fallback Diffusers MLP generik.
  • shadow_intermediate_size (Optional[int]) β€” Lebar feed-forward dari shadow backbone yang dibangun secara otomatis. Nilainya secara default adalah None (sama dengan hidden size-nya untuk fallback MLP Diffusers generik).
  • share_embeddings (bool) β€” Apakah akan menggunakan kembali embedding input dasar yang dibekukan untuk memberi umpan ke shadow backbone (melalui inputs_embeds) alih-alih tabel embedding milik shadow backbone itu sendiri. Nilai default adalah True.
  • update_hidden_size (Optional[int]) β€” Lebar tersembunyi dari MLP pembaruan T (kandidat) dan G (gerbang). Bawaan adalah None (menggunakan r).
  • auxiliary_loss_weight (float) β€” Bobot lambda dari auxiliary shadow loss (Eq. 8-9) yang ditambahkan ke task loss ketika labels dilewatkan. Loop pelatihan Diffusion dapat menggunakan nilai yang sama untuk detached denoising loss. Atur ke 0 untuk menonaktifkannya. Defaultnya adalah 0.05.
  • layers_to_transform (Optional[Union[list[int], int]]) β€” Indeks blok yang akan ditransformasi. Jika daftar yang diberikan, mekanisme bayangan diterapkan pada blok di indeks tersebut. Jika satu bilangan bulat yang diberikan, mekanisme ini diterapkan hanya pada indeks tersebut. Defaultnya adalah None (setiap blok yang cocok akan ditransformasi).
  • layers_pattern (Optional[Union[list[str], str]]) β€” Nama pola layer, hanya digunakan jika layers_to_transform berbeda dari None. Ini adalah nama dari nn.ModuleList yang menyimpan blok decoder (sering kali "layers" atau "h"). Nilainya secara default adalah None.
  • modules_to_save (Optional[list[str]]) β€” Modul tambahan yang akan diset sebagai trainable dan disimpan dalam checkpoint akhir (misalnya "lm_head" atau kepala klasifikasi). Defaultnya adalah None.

Kelas konfigurasi untuk ShadowModel (ShadowPEFT).

ShadowPEFT melengkapi model decoder-only beku dengan jaringan shadow paralel kecil yang dapat dilatih. Tulang punggung shadow menghasilkan keadaan shadow awal s^(0) yang kemudian mengikuti loop decoder model dasar: pada setiap blok yang ditargetkan, perbedaan antara keadaan tersembunyi dasar dan keadaan shadow disuntikkan kembali ke input blok (Persamaan 2-4), dan keadaan shadow diperbarui melalui pembaruan residual bergerbang dari output blok (Persamaan 5-7). Hanya komponen shadow yang dilatih; model dasar tetap beku. Karena adaptasi ini merupakan lintasan yang bergantung pada input di ruang lapisan, bukan delta bobot statis, ShadowPEFT tidak dapat digabungkan ke dalam bobot dasar.

ShadowModel

kelas peft.ShadowModel

< >

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

Membuat model ShadowPEFT dari model transformers yang telah dilatih sebelumnya.

ShadowPEFT melengkapi model decoder-only beku dengan jaringan shadow paralel kecil yang dapat dilatih. Tulang punggung shadow menghasilkan state shadow awal yang mengikuti loop decoder dasar; pada setiap blok yang ditargetkan, selisih antara hidden states dasar dan state shadow disuntikkan ke dalam blok tersebut, dan state shadow diperbarui melalui pembaruan residual yang digate. Hanya komponen shadow yang dilatih. Lihat ShadowConfig untuk konfigurasinya.

Metode ini tidak dapat digabungkan ke dalam bobot dasar (adaptasi adalah lintasan yang bergantung pada input, bukan delta bobot statis); gunakan ShadowModel.unload_shadow() untuk mendapatkan jaringan bayangan yang berdiri sendiri.

shadow_auxiliary_loss

< >

( labels: Tensorattention_mask: torch.Tensor | None = None )

Loss tugas dari jalur bayangan itu sendiri, CE(shadow_head(s^(0)), labels) (tanpa bobot; forward menerapkan bobotnya).

Loss dihitung pada state bayangan awal s^(0) (output backbone bayangan, yang diproyeksikan) β€” persis apa yang dihitung oleh model unload_shadow() mandiri sebagai head(projection(backbone(x))). Hal inilah yang membuat jaringan bayangan yang dilepas (detached) dapat digunakan secara mandiri; melatihnya pada s^(L) (state akhir, yang bergantung pada output per-lapisan dari model dasar dan tidak ada secara mandiri) akan membuat model yang dilepas tersebut tidak terlatih.

unload_shadow

< >

( adapter_name: str | None = Nonecopy: bool = False )

Parameter

  • adapter_name (str, opsional) β€” Adapter yang jaringan bayangannya akan dimuat keluar. Bawaan adalah adapter yang aktif.
  • copy (bool, opsional, default False) β€” Jika True, lakukan deep-copy pada model yang dikembalikan agar independen dari model ini (menggunakan lebih banyak memori). Jika False (default), bagikan modul β€” mirip dengan merge_and_unload, yang menggunakan ulang modul alih-alih mengklonnya. Mengubah satu model akan memengaruhi model lainnya.

Kembalikan shadow backbone (+ head) sebagai model mandiri, tanpa model dasar.

Padanan ShadowPEFT dari merge_and_unload: jika fungsi tersebut mengembalikan model dasar dengan adaptasi yang sudah terintegrasi, fungsi ini hanya mengembalikan jaringan bayangan yang ringan untuk inferensi yang efisien / di edge. Fungsi ini menjalankan head(projection(backbone(x))) β€” pembaruan per blok memerlukan output dasar sehingga tidak dapat berdiri sendiri. Untuk model bahasa, hasilnya berperilaku seperti LM kausal normal (mendukung generate() dan penyangga KV). Model Diffusers tidak didukung karena merekonstruksi denoiser mandiri yang lengkap bersifat spesifik untuk setiap arsitektur difusi.

Tugaskan hasilnya ke variabel dan gunakan; dengan copy=False, modul tetap dibagikan bersama model ini.

Lewati copy=True ketika Anda bermaksud untuk save_pretrained model standalone. Shadow backbone yang berbagi input embeddings base yang dibekukan (setup "mirror" default) mengaksesnya melalui referensi yang bukan merupakan submodul dari model yang dikembalikan, sehingga checkpoint copy=False tidak memiliki tabel embedding; copy=True menempelkan kembali salinan privat dan menyimpan checkpoint yang lengkap.

ShadowCache

kelas peft.tuners.shadow.ShadowCache

< >

( base: Any = Noneshadow: Any = None )

Cache KV berpasangan untuk decoding ShadowPEFT inkremental.

Generasi autoregresif memerlukan cache model dasar (kunci/nilai yang dihitung di bawah injeksi bayangan) dan cache model bayangan yang terpisah (untuk memajukan token s^(0) satu per satu). Ini adalah subkelas Cache Transformers: operasi yang memengaruhi tata letak batch atau sekuens (reset, reorder, crop, repeat, dan select) diterapkan ke kedua cache, sedangkan metadata perhatian dan pembaruan didelegasikan ke cache dasar. Atribut cache yang tidak dikenal juga didelegasikan ke cache dasar untuk kompatibilitas dengan implementasi cache yang spesifik arsitektur.

Wrapper ini sengaja tidak dapat dikompilasi karena kedua cache dapat memiliki tata letak layer dan ukuran hidden yang berbeda. Konversi tuple legacy tidak didukung, karena satu tuple legacy tidak dapat merepresentasikan kedua jalur. Setengah bayangan (shadow half) diurai sebelum forward base dan dikemas kembali saat keluar β€” lihat hook ShadowModel.

Update on GitHub