PEFT documentation
Cartuchos
Cartuchos
Los cartuchos son un método de aprendizaje de prompts que almacena una representación comprimida de contexto largo como un prefijo de caché KV parametrizado. La idea central proviene del artículo Cartridges: Lightweight and general-purpose long context representations via self-study.
Para una visión general y la motivación, consulte la publicación de blog Cartridges: Storing long contexts in tiny caches with self-study.
En qué se diferencian los Cartridges del Prefix Tuning
Tanto Prefix Tuning como Cartridges se sirven inyectando past_key_values (un prefijo de caché KV) en el modelo base.
- Prefix Tuning aprende incrustaciones de tokens virtuales (y opcionalmente una proyección MLP) y genera un prefijo KV.
- Los cartuchos aprenden directamente el prefijo KV (los vectores de clave/valor por capa para
ptokens virtuales) y están diseñados para inicializarse a partir de KV de prefill reales (por ejemplo, los primerosptokens de un corpus o prompt de sistema).
El artículo también recomienda congelar el primer token como sumidero de atención para la estabilidad (num_frozen_tokens=1 es el valor predeterminado).
Uso (inferencia)
Cargue un adaptador CARTRIDGE entrenado y ejecute la generación:
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 necesitas crear e inicializar un cartucho antes del entrenamiento, consulta las opciones de inicialización a continuación.
Opciones de inicialización
El artículo discute algunas estrategias de inicialización prácticas:
- KV aleatorio (predeterminado): cree una
CartridgeConfigy comience el entrenamiento. Esto inicializa el prefijo KV de forma aleatoria. - KV de los primeros tokens de un prompt/corpus: use
initialize_kv_prefix_from_text(model, tokenizer, text=...). Esto ejecuta un prefill entexty copia la caché KV resultante para los primerosnum_virtual_tokensen el adaptador. - KV desde una caché existente: use
initialize_kv_prefix_from_past_key_values(model, past_key_values=...)si ya tiene un objetopast_key_valuesde un prefill de un modelo base.
Entrenamiento
El artículo Cartridges propone un objetivo de destilación de AUTOESTUDIO (un modelo base congelado proporciona los logits del maestro; el adaptador CARTRIDGE se entrena para que el alumno coincida con la distribución de tokens siguientes del maestro sobre el segmento objetivo).
PEFT mantiene la lógica de entrenamiento fuera de la biblioteca principal; consulte https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study para un flujo de trabajo de referencia.
Los scripts de ejemplo utilizan el modelo base congelado como maestro y el modelo adaptado como alumno, por lo que ambos comparten el mismo punto de control subyacente.
Composición
Para concatenar cartuchos entrenados de forma independiente en un solo adaptador, use compose_cartridge_adapters(...).
API
CartridgeConfig
clase 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 )
Parámetros
- num_frozen_tokens (
int, valor predeterminado 1) — Número de tokens de prefijo al inicio del cartucho que se mantendrán congelados (sin gradientes). El paper de Cartridges recomienda congelar el primer token como sumidero de atención para mayor estabilidad (establezca este valor en1), ya que muchos LLM utilizan los tokens iniciales como sumideros de atención y modificarlos puede perjudicar el entrenamiento.
Configuración para CARTRIDGE, un adaptador de prefijo parametrizado por KV-cache.
Esto es similar al prefix-tuning en cuanto a cómo se sirve (como past_key_values), pero almacena la caché KV directamente como parámetros entrenables en lugar de aprenderla mediante una proyección MLP.
Inicialización: El artículo de Cartridges discute varias opciones de inicialización. En PEFT, la inicialización es un paso separado de la construcción de la configuración del adaptador:
Inicialización aleatoria de KV (opción 2 del artículo): Crea el adaptador mediante
get_peft_model(...). Los parámetros del codificador de prompts de CARTRIDGE se inicializan aleatoriamente por PyTorch.KV derivado de los primeros tokens de un prompt/corpus (opción 3 del paper): Ejecuta un prefill sin gradiente en el modelo base y copia los primeros
num_virtual_tokenstokens KV en caché al adaptador. PEFT proporciona utilidades para esto (importables desdepefto desdepeft.tuners.cartridge.utils):initialize_kv_prefix_from_text(model, tokenizer, text=...)initialize_kv_prefix_from_past_key_values(model, past_key_values=...)
Si ya tiene un tensor de prefijo KV aplanado, puede cargarlo directamente mediante el método
load_prompt_embeddings(...)del codificador de prompts.
CartridgeEncoder
Una caché KV de prefijo parametrizada.
Los parámetros se almacenan en el mismo diseño aplanado que la salida 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, los primeros num_frozen_tokens tokens virtuales se almacenan como un parámetro no entrenable,
y los tokens restantes son entrenables.
Cargue los embeddings de prompt aplanados guardados por PEFT (prompt_embeddings).
PEFT guarda los adaptadores de prompt-learning como un único tensor prompt_embeddings. Para CARTRIDGE, dividimos ese tensor en segmentos congelados y entrenables según 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 )
Inicialice un adaptador de aprendizaje de prefijo KV a partir de un prefijo en caché existente (past_key_values).
Devuelve el tensor de embeddings del prompt que se cargó en el adaptador.
prompt_embeddings_from_past_key_values
peft.prompt_embeddings_from_past_key_values
< source >( past_key_values: Anynum_virtual_tokens: int )
Convierte una caché past_key_values (legada) en el tensor de embeddings de prompt aplanado que guarda PEFT.
La salida coincide con el formato esperado por PeftModel.get_prompt() para el aprendizaje de prompts de tipo prefijo: forma [num_virtual_tokens, num_layers * 2 * token_dim].