# Cartridges

Cartridges là một phương pháp học theo prompt, lưu trữ biểu diễn ngữ cảnh dài đã nén dưới dạng tiền tố KV-cache có tham số. Ý tưởng cốt lõi đến từ bài báo [Cartridges: Lightweight and general-purpose long context representations via self-study](https://huggingface.co/papers/2506.06266).

Để có cái nhìn tổng quan và động lực, hãy xem bài đăng trên blog [Cartridges: Storing long contexts in tiny caches with self-study](https://hazyresearch.stanford.edu/blog/2025-06-08-cartridges).

## Cách Cartridges khác với Prefix Tuning

Cả Prefix Tuning và Cartridges đều được triển khai bằng cách tiêm `past_key_values` (bộ đệm KV tiền tố) vào mô hình cơ sở.

- Prefix Tuning học các nhúng token ảo (và tùy chọn một phép chiếu MLP) và tạo ra một tiền tố KV.
- Cartridges học trực tiếp chính tiền tố KV (các vector key/value theo từng lớp cho `p` token ảo), và được thiết kế để khởi tạo từ KV prefill thực tế (ví dụ, `p` token đầu tiên của một tập dữ liệu/hệ thống prompt).

Bài báo cũng khuyến nghị đóng băng token đầu tiên như một điểm neo chú ý để đảm bảo tính ổn định (`num_frozen_tokens=1` là mặc định).

## Usage (suy luận)

Tải adapter CARTRIDGE đã được huấn luyện và chạy tạo văn bả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))
```

Nếu bạn cần tạo và khởi tạo một cartridge trước khi huấn luyện, hãy xem các tùy chọn khởi tạo bên dưới.

## Các tùy chọn khởi tạo

Bài báo thảo luận về một số chiến lược khởi tạo thực tiễn:

- Random KV (mặc định): tạo một `CartridgeConfig` và bắt đầu huấn luyện. Thao tác này sẽ khởi tạo tiền tố KV một cách ngẫu nhiên.
- KV từ các token đầu tiên của một prompt/corpus: sử dụng `initialize_kv_prefix_from_text(model, tokenizer, text=...)`. Hàm này thực hiện prefill trên `text` và sao chép KV cache kết quả cho `num_virtual_tokens` đầu tiên vào adapter.
- KV từ bộ nhớ đệm hiện có: sử dụng `initialize_kv_prefix_from_past_key_values(model, past_key_values=...)` nếu bạn đã có một đối tượng `past_key_values` từ bước prefill của mô hình cơ sở.

## Huấn luyện

Bài báo Cartridges đề xuất một mục tiêu chưng cất SELF-STUDY (một mô hình cơ sở đóng băng cung cấp logits của giáo viên; bộ thích ứng CARTRIDGE được huấn luyện để học sinh khớp với phân phối token tiếp theo của giáo viên trên đoạn đích). PEFT giữ logic huấn luyện tách khỏi thư viện lõi; xem `https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study` để biết quy trình tham chiếu. Các script trong ví dụ sử dụng mô hình cơ sở đóng băng làm giáo viên và mô hình đã thích ứng làm học sinh, do đó cả hai cùng chia sẻ checkpoint nền tảng giống nhau.

## Cấu thành

Để ghép nối các cartridge được huấn luyện độc lập thành một adapter duy nhất, hãy sử dụng `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)
```

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

**Tham số:**

num_frozen_tokens (`int`, mặc định là 1) : Số lượng token *prefix* ở đầu cartridge được giữ nguyên (không tính gradient). Bài báo về Cartridges khuyến nghị đóng băng token đầu tiên như một attention sink để đảm bảo tính ổn định (đặt giá trị này thành `1`), vì nhiều LLM sử dụng các token đầu tiên làm attention sink và việc thay đổi chúng có thể gây ảnh hưởng xấu đến quá trình huấn luyện.

Cấu hình cho CARTRIDGE, một bộ thích ứng tiền tố có tham số hóa bộ nhớ đệm KV.

Điều này tương tự như prefix-tuning về cách phục vụ (dưới dạng `past_key_values`), nhưng nó lưu trữ bộ nhớ đệm KV trực tiếp dưới dạng các tham số có thể huấn luyện thay vì học nó thông qua một phép chiếu MLP.

Khởi tạo: Bài báo Cartridges thảo luận về nhiều tùy chọn khởi tạo. Trong PEFT, khởi tạo là một bước *riêng biệt* so với việc xây dựng cấu hình adapter:

- **Khởi tạo KV ngẫu nhiên (tùy chọn 2 trong bài báo)**: Tạo adapter thông qua `get_peft_model(...)`. Các tham số của prompt encoder CARTRIDGE được khởi tạo ngẫu nhiên bởi PyTorch.

- **KV được suy ra từ các token đầu tiên của một prompt/corpus (lựa chọn 3 trong bài báo)**: Chạy prefill không có gradient trên *mô hình cơ sở* và sao chép `num_virtual_tokens` token KV được cache đầu tiên vào adapter. PEFT cung cấp các tiện ích cho việc này (có thể import từ `peft` hoặc từ `peft.tuners.cartridge.utils`):

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

  Nếu bạn đã có một tensor KV-prefix đã được làm phẳng, bạn có thể nạp nó trực tiếp thông qua phương thức `load_prompt_embeddings(...)` của prompt encoder.

## CartridgeEncoder[[peft.CartridgeEncoder]]

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

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

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

Bộ đệm KV có tiền tố được tham số hóa.

Các tham số được lưu trữ trong cùng một bố cục phẳng như đầu ra của `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
được thực hiện bởi `_prepare_prompt_learning_config`).

Nếu `num_frozen_tokens > 0`, `num_frozen_tokens` token ảo đầu tiên được lưu dưới dạng tham số không thể huấn luyện, và các token còn lại có thể huấn luyện.

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

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

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

Tải các embedding prompt đã được làm phẳng và lưu bởi PEFT (`prompt_embeddings`).

PEFT lưu các adapter prompt-learning dưới dạng một tensor `prompt_embeddings` duy nhất. Đối với CARTRIDGE, chúng tôi tách tensor đó thành các đoạn đóng băng và có thể huấn luyện theo `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)
```

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

Khởi tạo bộ thích ứng học prompt tiền tố KV từ tiền tố được lưu trong bộ nhớ đệm (`past_key_values`) hiện có.

Trả về tensor nhúng prompt đã được nạp vào adapter.

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

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

Chuyển đổi bộ đệm `past_key_values` (phiên bản cũ) thành tensor nhúng prompt đã được làm phẳng do PEFT lưu trữ.

Đầu ra khớp với bố cục được kỳ vọng bởi `PeftModel.get_prompt()` cho việc học prompt theo kiểu tiền tố: hình dạng `[num_virtual_tokens, num_layers * 2 * token_dim]`.

