# 카트리지

Cartridges는 압축된 장문맥 표현을 매개변수화된 KV-cache 접두사로 저장하는 프롬프트 학습 방법입니다. 핵심 아이디어는 [Cartridges: Lightweight and general-purpose long context representations via self-study](https://huggingface.co/papers/2506.06266) 논문에서 유래했습니다.

고수준 개요와 동기에 대해서는 블로그 포스트 [Cartridges: Storing long contexts in tiny caches with self-study](https://hazyresearch.stanford.edu/blog/2025-06-08-cartridges)를 참고하세요.

## Cartridges와 Prefix Tuning의 차이

Prefix Tuning과 Cartridges 모두 `past_key_values`(prefix KV 캐시)를 기본 모델에 주입하여 서빙됩니다.

- Prefix Tuning은 가상 토큰 임베딩(및 선택적으로 MLP 투영)을 학습하여 KV 접두사를 생성합니다.
- Cartridges는 `p`개의 가상 토큰에 대한 레이어별 key/value 벡터인 KV prefix 자체를 직접 학습하며, 실제 prefill KV(예: 코퍼스/시스템 프롬프트의 첫 `p`개 토큰)에서 초기화되도록 설계되었습니다.

이 논문은 안정성을 위해 첫 번째 토큰을 attention sink로 고정하는 것을 권장합니다(`num_frozen_tokens=1`이 기본값입니다).

## Usage (추론)

학습된 CARTRIDGE 어댑터를 로드하고 생성을 실행합니다:

```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))
```

학습 전에 카트리지를 생성하고 초기화해야 하는 경우, 아래 초기화 옵션을 참조하세요.

## 초기화 옵션

이 논문에서는 몇 가지 실용적인 초기화 전략을 다룹니다:

- Random KV(기본값): `CartridgeConfig`를 생성하고 학습을 시작합니다. 이렇게 하면 KV 접두사가 무작위로 초기화됩니다.
- 프롬프트/코퍼스에서 첫 번째 토큰의 KV: `initialize_kv_prefix_from_text(model, tokenizer, text=...)`을 사용합니다. 이 함수는 `text`에 대해 prefill을 실행하고, 생성된 KV 캐시의 첫 `num_virtual_tokens`개를 어댑터로 복사합니다.
- 기존 캐시에서 KV: 베이스 모델의 prefill에서 이미 `past_key_values` 객체를 가지고 있다면 `initialize_kv_prefix_from_past_key_values(model, past_key_values=...)`를 사용합니다.

## 학습

Cartridges 논문은 SELF-STUDY 증류 목적 함수를 제안합니다(동결된 베이스 모델이 교사 로짓을 제공하고, CARTRIDGE 어댑터는 학생 모델이 대상 세그먼트에서 교사의 다음 토큰 분포와 일치하도록 학습됩니다). PEFT는 학습 로직을 핵심 라이브러리에서 분리합니다. 참고 워크플로우는 `https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study`를 참조하세요. 예제 스크립트는 동결된 베이스 모델을 교사로, 어댑트된 모델을 학생으로 사용하므로, 두 모델은 동일한 기반 체크포인트를 공유합니다.

## 구성

독립적으로 학습된 카트리지를 단일 어댑터로 연결하려면 `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)
```

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

**매개변수:**

num_frozen_tokens (`int`, 기본값 1) : 카트리지 시작 부분에 있는 *prefix* 토큰 중 동결(그라디언트 없음)할 토큰 수입니다. Cartridges 논문은 안정성을 위해 첫 번째 토큰을 어텐션 싱크로 동결하는 것을 권장합니다(이 값을 `1`로 설정). 많은 LLM이 초기 토큰을 어텐션 싱크로 사용하며, 이를 변경하면 학습에 해로울 수 있기 때문입니다.

KV 캐시 매개변수화된 프리픽스 어댑터인 CARTRIDGE의 구성입니다.

`past_key_values`로 서빙되는 방식은 prefix-tuning과 유사하지만, MLP 투영을 통해 학습하는 대신 KV 캐시를 직접 학습 가능한 파라미터로 저장합니다.

초기화: Cartridges 논문은 여러 초기화 옵션을 다룹니다. PEFT에서 초기화는 어댑터 구성을 만드는 것과 *별도의* 단계입니다:

- **무작위 KV 초기화(논문 옵션 2)**: `get_peft_model(...)`을 통해 어댑터를 생성합니다. CARTRIDGE 프롬프트 인코더 매개변수는 PyTorch에 의해 무작위로 초기화됩니다.

- **프롬프트/코퍼스(종이 옵션 3)의 첫 토큰에서 파생된 KV**: *기본 모델*에서 no-grad prefill을 실행하고 캐시된 KV 토큰 중 처음 `num_virtual_tokens`개를 어댑터로 복사합니다. PEFT는 이를 위한 유틸리티를 제공합니다(`peft` 또는 `peft.tuners.cartridge.utils`에서 가져올 수 있음):

  - `initialize_kv_prefix_from_text(model, tokenizer, text=...)`
  - `initialize_kv_prefix_from_past_key_values(model, past_key_values=...)`

  이미 평탄화된 KV-prefix 텐서가 있는 경우, 프롬프트 인코더의 `load_prompt_embeddings(...)` 메서드를 통해 직접 로드할 수 있습니다.

## CartridgeEncoder[[peft.CartridgeEncoder]]

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

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

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

파라미터화된 프리픽스 KV 캐시.

파라미터는 `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
`_prepare_prompt_learning_config`에 의해 수행됩니다).

`num_frozen_tokens > 0`인 경우, 처음 `num_frozen_tokens`개의 가상 토큰은 학습 불가능한(non-trainable) 파라미터로 저장되고, 나머지 토큰은 학습 가능합니다.

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

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

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

PEFT가 저장한 평탄화된 프롬프트 임베딩(`prompt_embeddings`)을 로드합니다.

PEFT는 프롬프트 학습 어댑터를 단일 `prompt_embeddings` 텐서로 저장합니다. CARTRIDGE의 경우, `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)
```

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

기존에 캐시된 프리픽스(`past_key_values`)에서 KV-prefix 프롬프트 학습 어댑터를 초기화합니다.

어댑터에 로드된 프롬프트 임베딩 텐서를 반환합니다.

## 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)
```

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

(레거시) `past_key_values` 캐시를 PEFT가 저장하는 평탄화된 프롬프트 임베딩 텐서로 변환합니다.

출력은 prefix 스타일 프롬프트 학습에 대해 `PeftModel.get_prompt()`가 기대하는 레이아웃과 일치합니다: shape `[num_virtual_tokens, num_layers * 2 * token_dim]`.

