Implementation:Huggingface Peft CartridgeConfig
| Knowledge Sources | |
|---|---|
| Domains | Deep_Learning, Parameter_Efficient_Finetuning |
| Last Updated | 2026-02-07 14:00 GMT |
Overview
Concrete configuration dataclass for the CARTRIDGE (KV-cache-parameterized prefix adapter) PEFT method provided by the Huggingface PEFT library.
Description
CartridgeConfig controls the hyperparameters for the CARTRIDGE adapter, which is similar to prefix-tuning but stores KV cache directly as trainable parameters instead of learning it via an MLP projection. It supports multiple initialization strategies including random KV initialization and KV derived from prompt tokens. This class extends PromptLearningConfig.
Usage
Import and use CartridgeConfig when you want to apply a KV-cache-parameterized prefix adapter to a pretrained model. This is suitable for prompt-learning scenarios where you want to directly parameterize the key-value cache as trainable prefix tokens.
Code Reference
Source Location
- Repository: Huggingface_Peft
- File: src/peft/tuners/cartridge/config.py
- Lines: 21-75
Signature
@dataclass
class CartridgeConfig(PromptLearningConfig):
num_frozen_tokens: int = 1
Import
from peft import CartridgeConfig
I/O Contract
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| num_frozen_tokens | int | 1 | Number of initial virtual tokens to freeze (no gradients). The paper recommends freezing the first token as an attention sink for stability. |
Note: CartridgeConfig inherits additional fields from PromptLearningConfig, including num_virtual_tokens, task_type, and other prompt-learning parameters.
Outputs
| Name | Type | Description |
|---|---|---|
| instance | CartridgeConfig | Configuration object to pass to get_peft_model |
Usage Examples
Basic Configuration
from peft import CartridgeConfig, get_peft_model
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("model-name")
config = CartridgeConfig(
num_virtual_tokens=20,
num_frozen_tokens=1,
task_type="CAUSAL_LM",
)
model = get_peft_model(model, config)