# 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](https://huggingface.co/papers/2506.06266).

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](https://hazyresearch.stanford.edu/blog/2025-06-08-cartridges).

## 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 `p` tokens virtuales) y están diseñados para inicializarse a partir de KV de prefill reales (por ejemplo, los primeros `p` tokens 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).

## Usage (inferencia)

Cargue un adaptador CARTRIDGE entrenado y ejecute la generación:

```py
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 `CartridgeConfig` y 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 en `text` y copia la caché KV resultante para los primeros `num_virtual_tokens` en el adaptador.
- KV desde una caché existente: use `initialize_kv_prefix_from_past_key_values(model, past_key_values=...)` si ya tiene un objeto `past_key_values` de 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 checkpoint subyacente.

## Composición

Para concatenar cartuchos entrenados de forma independiente en un solo adaptador, use `compose_cartridge_adapters(...)`.

# API

## CartridgeConfig[[peft.CartridgeConfig]]

#### peft.CartridgeConfig[[peft.CartridgeConfig]]

```python
peft.CartridgeConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, num_virtual_tokens: int = None, token_dim: int = None, num_transformer_submodules: Optional[int] = None, num_attention_heads: Optional[int] = None, num_layers: Optional[int] = None, modules_to_save: Optional[list[str]] = None, num_frozen_tokens: int = 1)
```

[Fuente](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/cartridge/config.py#L22)

**Parámetros:**

num_frozen_tokens (`int`, por defecto 1) : Número de tokens de *prefix* 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 en `1`), 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_tokens` tokens KV en caché al adaptador. PEFT proporciona utilidades para esto (importables desde `peft` o desde `peft.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[[peft.CartridgeEncoder]]

#### peft.CartridgeEncoder[[peft.CartridgeEncoder]]

```python
peft.CartridgeEncoder(config)
```

[Fuente](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/cartridge/model.py#L22)

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]`, where `token_dim` is per-head hidden size times number of heads (after any GQA adjustment
realizado por `_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.

#### load_prompt_embeddings[[peft.CartridgeEncoder.load_prompt_embeddings]]

```python
load_prompt_embeddings(prompt_embeddings: torch.Tensor)
```

[Fuente](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/cartridge/model.py#L91)

Cargue los embeddings de prompt aplanados guardados por PEFT (`prompt_embeddings`).

PEFT guarda los adaptadores de aprendizaje de prompts 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]]

#### peft.initialize_kv_prefix_from_past_key_values[[peft.initialize_kv_prefix_from_past_key_values]]

```python
peft.initialize_kv_prefix_from_past_key_values(model, adapter_name: Optional[str] = None, past_key_values: Any, num_virtual_tokens: Optional[int] = None)
```

[Fuente](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/cartridge/utils.py#L101)

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

#### peft.prompt_embeddings_from_past_key_values[[peft.prompt_embeddings_from_past_key_values]]

```python
peft.prompt_embeddings_from_past_key_values(past_key_values: Any, num_virtual_tokens: int)
```

[Fuente](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/cartridge/utils.py#L49)

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

