PEFT documentation
Cartouches
Cartouches
Les cartouches sont une méthode d'apprentissage par prompt qui stocke une représentation de contexte long compressée sous forme de préfixe de cache KV paramétré. L'idée centrale provient de l'article Cartridges: Lightweight and general-purpose long context representations via self-study.
Pour un aperçu général et la motivation, consultez le billet de blog Cartridges: Storing long contexts in tiny caches with self-study.
En quoi les Cartridges diffèrent du Prefix Tuning
Prefix Tuning et Cartridges sont tous deux servis en injectant past_key_values (un cache KV préfixe) dans le modèle de base.
- Prefix Tuning apprend des embeddings de jetons virtuels (et éventuellement une projection MLP) et génère un préfixe KV.
- Les cartouches apprennent directement le préfixe KV lui-même (les vecteurs clé/valeur par couche pour
pjetons virtuels) et sont conçus pour être initialisés à partir de KV de préremplissage réels (par exemple, lesppremiers jetons d’un corpus/invite système).
L’article recommande également de geler le premier jeton comme puits d’attention pour la stabilité (num_frozen_tokens=1 est la valeur par défaut).
Utilisation (inférence)
Charger un adaptateur CARTRIDGE entraîné et exécuter la génération :
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))Si vous devez créer et initialiser une cartouche avant l’entraînement, consultez les options d’initialisation ci-dessous.
Options d'initialisation
L'article aborde quelques stratégies d'initialisation pratiques :
- KV aléatoire (par défaut) : créez un
CartridgeConfiget lancez l’entraînement. Cela initialise le préfixe KV de manière aléatoire. - KV des premiers jetons d’un prompt/corpus : utilisez
initialize_kv_prefix_from_text(model, tokenizer, text=...). Cela effectue un préremplissage surtextet copie le cache KV résultant pour lesnum_virtual_tokenspremiers jetons dans l’adaptateur. - KV à partir d’un cache existant : utilisez
initialize_kv_prefix_from_past_key_values(model, past_key_values=...)si vous disposez déjà d’un objetpast_key_valuesissu du préremplissage d’un modèle de base.
Entraînement
L’article Cartridges propose un objectif de distillation en AUTO-APPRENTISSAGE (un modèle de base figé fournit les logits de l’enseignant ; l’adaptateur CARTRIDGE est entraîné afin que l’élève corresponde à la distribution du jeton suivant de l’enseignant sur le segment cible).
PEFT maintient la logique d’entraînement en dehors de la bibliothèque principale ; voir https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study pour un flux de travail de référence.
Les scripts d’exemple utilisent le modèle de base figé comme enseignant et le modèle adapté comme élève, de sorte que les deux partagent le même point de contrôle sous-jacent.
Composition
Pour concaténer des cartouches entraînées indépendamment en un seul adaptateur, utilisez compose_cartridge_adapters(...).
API
CartridgeConfig
classe 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 )
Paramètres
- num_frozen_tokens (
int, par défaut 1) — Nombre de jetons de préfixe en début de cartouche à conserver figés (sans gradients). L’article Cartridges recommande de figer le premier jeton comme puits d’attention pour la stabilité (fixez cette valeur à1), car de nombreux LLM utilisent les jetons initiaux comme puits d’attention et les modifier peut nuire à l’entraînement.
Configuration pour CARTRIDGE, un adaptateur de préfixe paramétré par cache KV.
Ceci est similaire au prefix-tuning en ce qui concerne sa manière d’être servi (sous forme de past_key_values), mais il stocke le cache KV directement en tant que paramètres entraînables au lieu de l’apprendre via une projection MLP.
Initialisation : L’article Cartridges aborde plusieurs options d’initialisation. Dans PEFT, l’initialisation est une étape séparée de la construction de la configuration de l’adaptateur :
Initialisation aléatoire des KV (option 2 du papier) : créez l’adaptateur via
get_peft_model(...). Les paramètres de l’encodeur de prompt CARTRIDGE sont initialisés aléatoirement par PyTorch.KV dérivé des premiers jetons d’un prompt/corpus (option 3 du papier) : exécutez un préremplissage sans gradient sur le modèle de base et copiez les premiers jetons KV mis en cache, au nombre de
num_virtual_tokens, dans l’adaptateur. PEFT fournit des utilitaires à cet effet (importables depuispeftou depuispeft.tuners.cartridge.utils) :initialize_kv_prefix_from_text(model, tokenizer, text=...)initialize_kv_prefix_from_past_key_values(model, past_key_values=...)
Si vous disposez déjà d'un tenseur de préfixe KV aplati, vous pouvez le charger directement via la méthode
load_prompt_embeddings(...)de l'encodeur de prompt.
CartridgeEncoder
Un cache KV préfixe paramétré.
Les paramètres sont stockés dans la même disposition aplatie que la sortie de 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`).
Si num_frozen_tokens > 0, les num_frozen_tokens premiers jetons virtuels sont stockés en tant que paramètre non entraînable, et les jetons restants sont entraînables.
Chargez les embeddings de prompt aplatis enregistrés par PEFT (prompt_embeddings).
PEFT enregistre les adaptateurs d'apprentissage de prompts sous forme d'un unique tenseur prompt_embeddings. Pour CARTRIDGE, nous divisons ce tenseur en segments gelés et entraînables en fonction de 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 )
Initialiser un adaptateur d’apprentissage de préfixe KV à partir d’un préfixe mis en cache existant (past_key_values).
Retourne le tenseur d'embeddings du prompt qui a été chargé dans l'adaptateur.
prompt_embeddings_from_past_key_values
peft.prompt_embeddings_from_past_key_values
< source >( past_key_values: Anynum_virtual_tokens: int )
Convertir un cache past_key_values (légacy) en tenseur d'embeddings de prompt aplati enregistré par PEFT.
La sortie correspond à la disposition attendue par PeftModel.get_prompt() pour l'apprentissage de prompts de type préfixe : forme [num_virtual_tokens, num_layers * 2 * token_dim].