PEFT documentation

Cartridges

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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 p token virtual), dan dirancang untuk diinisialisasi dari KV prefill yang sebenarnya (misalnya, p token 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 CartridgeConfig dan 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 pada text dan menyalin KV cache yang dihasilkan untuk num_virtual_tokens pertama 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 objek past_key_values dari 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

< >

( 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 ke 1), 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_tokens token KV cache pertama ke dalam adapter. PEFT menyediakan utilitas untuk ini (dapat diimpor dari peft atau dari peft.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

kelas peft.CartridgeEncoder

< >

( config )

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.

load_prompt_embeddings

< >

( prompt_embeddings: torch.Tensor )

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

< >

( 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

< >

( 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].

Update on GitHub