PEFT documentation
カートリッジ
カートリッジ
Cartridgesは、パラメータ化されたKV-cacheプレフィックスとして圧縮された長文脈の表現を保存するプロンプト学習手法です。このコアアイデアは、論文Cartridges: Lightweight and general-purpose long context representations via self-studyに由来します。
高レベルな概要と動機については、ブログ記事Cartridges: Storing long contexts in tiny caches with self-studyを参照してください。
CartridgesとPrefix Tuningの違い
Prefix Tuning と Cartridges の両方は、ベースモデルにpast_key_values(プレフィックスKVキャッシュ)を注入することによって提供されます。
- Prefix Tuningは、仮想トークンの埋め込み(および任意のMLP投影)を学習し、KVプレフィックスを生成します。
- Cartridges は KV プレフィックス自体を直接学習します(
p個の仮想トークンに対するレイヤーごとのキー/ベクトル)。また、実際のプリフィル KV(例えばコーパスやシステムプロンプトの最初のpトークン)から初期化されるよう設計されています。
この論文では、安定性を高めるために最初のトークンをアテンションシンクとして固定することを推奨しています(デフォルトではnum_frozen_tokens=1)。
使用法(推論)
学習済みのCARTRIDGEアダプターを読み込み、生成を実行します:
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に対してプリフィルが実行され、最初のnum_virtual_tokensのKVキャッシュがアダプターにコピーされます。 - 既存のキャッシュからのKV: ベースモデルのプリフィルから
past_key_valuesオブジェクトをすでに持っている場合は、initialize_kv_prefix_from_past_key_values(model, past_key_values=...)を使用します。
トレーニング
Cartridges論文は、SELF-STUDY蒸留目的関数を提案しています(凍結されたベースモデルが教師のlogitsを提供し、CARTRIDGEアダプターは、ターゲットセグメント上で生徒モデルが教師の次のトークン分布に一致するように訓練されます)。
PEFTは、訓練ロジックをコアライブラリから分離しています。参考ワークフローについては、https://github.com/huggingface/peft/tree/main/examples/cartridge_self_studyを参照してください。
サンプルスクリプトでは、凍結されたベースモデルを教師、適応済みモデルを生徒として使用するため、両者は同じ基盤となるチェックポイントを共有します。
構成
独立して学習されたカートリッジを単一のアダプターに連結するには、compose_cartridge_adapters(...)を使用します。
API
CartridgeConfig
class 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 )
KVキャッシュパラメータ化されたプレフィックスアダプタであるCARTRIDGEの設定。
サービングの仕組み(past_key_values として提供される点)は prefix-tuning と似ていますが、MLP 投影を通じて学習するのではなく、KV キャッシュをそのまま学習可能なパラメータとして保存します。
初期化: Cartridges論文では、複数の初期化オプションについて議論されています。PEFTでは、初期化はアダプタ設定の構築とは別のステップです:
ランダムな KV 初期化(論文のオプション 2):
get_peft_model(...)を使用してアダプターを作成します。CARTRIDGE プロンプトエンコーダーのパラメータは PyTorch によってランダムに初期化されます。プロンプト/コーパスの最初のトークンから導出されたKV(論文のオプション3): ベースモデルで勾配なしのプリフィルを実行し、キャッシュされた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プレフィックステンソルが既に用意されている場合は、プロンプトエンコーダーの
load_prompt_embeddings(...)メソッドを介して直接読み込むことができます。
CartridgeEncoder
パラメータ化されたプレフィックスKVキャッシュ。
パラメータは、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`).
num_frozen_tokens > 0の場合、最初のnum_frozen_tokens個の仮想トークンは学習可能なパラメータとして保存され、残りのトークンは学習可能になります。
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
< source >( modeladapter_name: Optional[str] = Nonepast_key_values: Anynum_virtual_tokens: Optional[int] = None )
past_key_values の既存のキャッシュされたプレフィックスから、KVプレフィックスプロンプト学習アダプターを初期化します。
アダプターに読み込まれたプロンプト埋め込みテンソルを返します。
prompt_embeddings_from_past_key_values
peft.prompt_embeddings_from_past_key_values
< source >( past_key_values: Anynum_virtual_tokens: int )
(レガシーの)past_key_valuesキャッシュを、PEFTが保存するフラット化されたプロンプト埋め込みテンソルに変換します。
出力は、プレフィックススタイルのプロンプト学習においてPeftModel.get_prompt()が期待するレイアウトと一致しています。形状は[num_virtual_tokens, num_layers * 2 * token_dim]です。