PEFT documentation
Cartridges
Cartridges
Cartridges adalah metode pembelajaran prompt yang menyimpan representasi konteks panjang yang terkompresi sebagai prefiks KV-cache yang diparameterisasi. Ide intinya berasal dari makalah Cartridges: Lightweight and general-purpose long context representations via self-study.
Untuk gambaran umum dan motivasi, lihat artikel blog Cartridges: Storing long contexts in tiny caches with self-study.
Bagaimana Cartridges Berbeda dari Prefix Tuning
Baik Prefix Tuning maupun Cartridges disajikan dengan cara menyuntikkan past_key_values (cache KV prefix) ke dalam model dasar.
- Prefix Tuning mempelajari embedding token virtual (dan secara opsional proyeksi MLP) serta menghasilkan prefix KV.
- Cartridges mempelajari prefix KV itu sendiri secara langsung (vektor key/value per lapisan untuk
ptoken virtual), dan dirancang untuk diinisialisasi dari KV prefill yang sebenarnya (misalnya,ptoken pertama dari korpus/system prompt).
Paper tersebut juga merekomendasikan untuk membekukan token pertama sebagai attention sink demi stabilitas (num_frozen_tokens=1 adalah
default).
Penggunaan (inferensi)
Muat adapter CARTRIDGE yang telah dilatih dan jalankan generasi:
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
model_id = "Qwen/Qwen2.5-0.5B-Instruct"
adapter_path = "path/to/cartridge_adapter"
base = AutoModelForCausalLM.from_pretrained(model_id)
model = PeftModel.from_pretrained(base, adapter_path)
tok = AutoTokenizer.from_pretrained(model_id)
if tok.pad_token is None:
tok.pad_token = tok.eos_token
out = model.generate(**tok("Question about the corpus:", return_tensors="pt"), max_new_tokens=64)
print(tok.decode(out[0], skip_special_tokens=True))Jika Anda perlu membuat dan menginisialisasi cartridge sebelum pelatihan, lihat opsi inisialisasi di bawah.
Opsi inisialisasi
Paper tersebut membahas beberapa strategi inisialisasi praktis:
- Random KV (default): buat
CartridgeConfigdan mulai pelatihan. Ini menginisialisasi prefiks KV secara acak. - KV dari token pertama prompt/korpus: gunakan
initialize_kv_prefix_from_text(model, tokenizer, text=...). Ini menjalankan prefill padatextdan menyalin KV cache yang dihasilkan untuknum_virtual_tokenspertama ke dalam adapter. - KV dari cache yang sudah ada: gunakan
initialize_kv_prefix_from_past_key_values(model, past_key_values=...)jika Anda sudah memiliki objekpast_key_valuesdari prefill model dasar.
Pelatihan
Paper Cartridges mengusulkan tujuan distilasi SELF-STUDY (model dasar yang dibekukan menyediakan logit guru; adapter CARTRIDGE dilatih agar siswa mencocokkan distribusi token berikutnya dari guru pada segmen target).
PEFT menjaga logika pelatihan di luar pustaka inti; lihat https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study untuk alur kerja referensi.
Skrip contoh menggunakan model dasar yang dibekukan sebagai guru dan model yang diadaptasi sebagai siswa, sehingga keduanya berbagi checkpoint yang mendasari sama.
Komposisi
Untuk menggabungkan cartridge yang dilatih secara independen menjadi satu adapter, gunakan compose_cartridge_adapters(...).
API
CartridgeConfig
kelas peft.CartridgeConfig
< source >( 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 = Falsenum_virtual_tokens: int = Nonetoken_dim: int = Nonenum_transformer_submodules: Optional[int] = Nonenum_attention_heads: Optional[int] = Nonenum_layers: Optional[int] = Nonemodules_to_save: Optional[list[str]] = Nonenum_frozen_tokens: int = 1 )
Parameter
- num_frozen_tokens (
int, default 1) — Jumlah token prefix di awal cartridge yang akan dibekukan (tanpa gradien). Paper Cartridges merekomendasikan untuk membekukan token pertama sebagai attention sink demi stabilitas (setel ini ke1), karena banyak LLM menggunakan token awal sebagai attention sink dan mengubahnya dapat merugikan pelatihan.
Konfigurasi untuk CARTRIDGE, sebuah adapter prefiks yang diparameterkan oleh KV-cache.
Ini mirip dengan prefix-tuning dalam hal cara penyajiannya (sebagai past_key_values), tetapi menyimpan KV cache secara langsung sebagai parameter yang dapat dilatih, bukan mempelajarinya melalui proyeksi MLP.
Inisialisasi: Kertas Cartridges membahas beberapa opsi inisialisasi. Di PEFT, inisialisasi adalah langkah yang terpisah dari pembuatan konfigurasi adapter:
Inisialisasi KV acak (opsi 2 dari paper): Buat adapter melalui
get_peft_model(...). Parameter prompt encoder CARTRIDGE diinisialisasi secara acak oleh PyTorch.KV yang diturunkan dari token pertama prompt/korpus (opsi 3 paper): Jalankan prefill no-grad pada model dasar dan salin
num_virtual_tokenstoken KV cache pertama ke dalam adapter. PEFT menyediakan utilitas untuk ini (dapat diimpor daripeftatau daripeft.tuners.cartridge.utils):initialize_kv_prefix_from_text(model, tokenizer, text=...)initialize_kv_prefix_from_past_key_values(model, past_key_values=...)
Jika Anda sudah memiliki tensor KV-prefix yang telah diratakan, Anda dapat memuatnya secara langsung melalui metode
load_prompt_embeddings(...)dari prompt encoder.
CartridgeEncoder
Cache KV dengan prefiks yang diparameterisasi.
Parameter disimpan dalam tata letak datar yang sama dengan output PrefixEncoder: `[num_virtual_tokens, num_layers
- 2 * token_dim]
, wheretoken_dimis per-head hidden size times number of heads (after any GQA adjustment performed by_prepare_prompt_learning_config`).
Jika num_frozen_tokens > 0, num_frozen_tokens token virtual pertama disimpan sebagai parameter yang tidak dapat dilatih,
dan token sisanya dapat dilatih.
Muat embedding prompt yang telah diratakan dan disimpan oleh PEFT (prompt_embeddings).
PEFT menyimpan adapter pembelajaran prompt sebagai tensor tunggal prompt_embeddings. Untuk CARTRIDGE, tensor tersebut dipecah menjadi segmen beku dan segmen yang dapat dilatih sesuai dengan self.num_frozen_tokens.
initialize_kv_prefix_from_past_key_values
peft.initialize_kv_prefix_from_past_key_values
< source >( modeladapter_name: Optional[str] = Nonepast_key_values: Anynum_virtual_tokens: Optional[int] = None )
Inisialisasi adapter pembelajaran prompt KV-prefix dari prefix yang sudah di-cache (past_key_values).
Mengembalikan tensor prompt embeddings yang dimuat ke dalam adapter.
prompt_embeddings_from_past_key_values
peft.prompt_embeddings_from_past_key_values
< source >( past_key_values: Anynum_virtual_tokens: int )
Mengonversi cache past_key_values (legacy) menjadi tensor prompt embeddings yang telah diratakan dan disimpan oleh PEFT.
Outputnya sesuai dengan tata letak yang diharapkan oleh PeftModel.get_prompt() untuk pembelajaran prompt bergaya prefix: bentuk [num_virtual_tokens, num_layers * 2 * token_dim].