PEFT documentation
Cartuchos
Cartuchos
Cartridges é um método de aprendizado de prompt que armazena uma representação de contexto longo comprimida como um prefixo de KV-cache parametrizado. A ideia central vem do artigo Cartridges: Lightweight and general-purpose long context representations via self-study.
Para uma visão geral e a motivação, consulte o post no blog Cartridges: Storing long contexts in tiny caches with self-study.
Como os Cartridges diferem do Prefix Tuning
Tanto o Prefix Tuning quanto o Cartridges são executados por meio da injeção de past_key_values (um cache KV de prefixo) no modelo base.
- Prefix Tuning aprende incorporações de tokens virtuais (e, opcionalmente, uma projeção MLP) e produz um prefixo KV.
- Os cartuchos aprendem diretamente o próprio prefixo KV (os vetores de chave/valor por camada para
ptokens virtuais) e são projetados para serem inicializados a partir de KV de pré-preenchimento real (por exemplo, os primeirosptokens de um corpus/prompt de sistema).
O artigo também recomenda congelar o primeiro token como um ponto de atenção para estabilidade (num_frozen_tokens=1 é o padrão).
Uso (inferência)
Carregue um adaptador CARTRIDGE treinado e execute a geração:
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))Se você precisar criar e inicializar um cartucho antes do treinamento, consulte as opções de inicialização abaixo.
Opções de inicialização
O artigo discute algumas estratégias práticas de inicialização:
- KV aleatório (padrão): crie um
CartridgeConfige inicie o treinamento. Isso inicializa o prefixo KV aleatoriamente. - KV dos primeiros tokens de um prompt/corpus: use
initialize_kv_prefix_from_text(model, tokenizer, text=...). Isso executa um prefill emtexte copia o cache KV resultante para os primeirosnum_virtual_tokensno adaptador. - KV de um cache existente: use
initialize_kv_prefix_from_past_key_values(model, past_key_values=...)se você já tiver um objetopast_key_valuesde um prefill de um modelo base.
Treinamento
O paper Cartridges propõe um objetivo de destilação de AUTOESTUDO (um modelo base congelado fornece os logits do professor; o adaptador CARTRIDGE é treinado para que o aluno corresponda à distribuição de próximo token do professor sobre o segmento alvo).
O PEFT mantém a lógica de treinamento fora da biblioteca principal; consulte https://github.com/huggingface/peft/tree/main/examples/cartridge_self_study para um fluxo de trabalho de referência.
Os scripts de exemplo usam o modelo base congelado como professor e o modelo adaptado como aluno, de modo que ambos compartilham o mesmo checkpoint subjacente.
Composição
Para concatenar cartuchos treinados de forma independente em um único adaptador, use compose_cartridge_adapters(...).
API
CartridgeConfig
classe 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 )
Parâmetros
- num_frozen_tokens (
int, padrão 1) — Número de tokens de prefixo no início do cartridge que devem permanecer congelados (sem gradientes). O paper Cartridges recomenda congelar o primeiro token como um attention sink para estabilidade (defina este valor como1), pois muitos LLMs usam tokens iniciais como attention sinks e alterá-los pode prejudicar o treinamento.
Configuração para CARTRIDGE, um adaptador de prefixo parametrizado por KV-cache.
Isso é semelhante ao prefix-tuning em como é servido (como past_key_values), mas ele armazena o cache KV diretamente como
parâmetros treináveis, em vez de aprendê-lo por meio de uma projeção MLP.
Inicialização: O paper Cartridges discute várias opções de inicialização. No PEFT, a inicialização é uma etapa separada da construção da configuração do adaptador:
Inicialização aleatória de KV (opção 2 do paper): Crie o adaptador via
get_peft_model(...). Os parâmetros do codificador de prompt do CARTRIDGE são inicializados aleatoriamente pelo PyTorch.KV derivado dos primeiros tokens de um prompt/corpus (opção 3 do paper): Execute um prefill sem gradiente no modelo base e copie os primeiros
num_virtual_tokenstokens KV em cache para o adaptador. O PEFT fornece utilitários para isso (importáveis depeftou depeft.tuners.cartridge.utils):initialize_kv_prefix_from_text(model, tokenizer, text=...)initialize_kv_prefix_from_past_key_values(model, past_key_values=...)
Se você já possui um tensor de prefixo KV achatado, pode carregá-lo diretamente por meio do método
load_prompt_embeddings(...)do codificador de prompt.
CartridgeEncoder
Um cache KV de prefixo parametrizado.
Os parâmetros são armazenados no mesmo layout achatado da saída de 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`).
Se num_frozen_tokens > 0, os primeiros num_frozen_tokens tokens virtuais são armazenados como um parâmetro não treinável,
e os tokens restantes são treináveis.
Carregue os embeddings de prompt achatados salvos pelo PEFT (prompt_embeddings).
PEFT salva adaptadores de prompt-learning como um único tensor prompt_embeddings. Para CARTRIDGE, dividimos esse tensor em segmentos congelados e treináveis de acordo com 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 )
Inicialize um adaptador de aprendizado de prompt com prefixo KV a partir de um prefixo em cache existente (past_key_values).
Retorna o tensor de embeddings do prompt que foi carregado no adaptador.
prompt_embeddings_from_past_key_values
peft.prompt_embeddings_from_past_key_values
< source >( past_key_values: Anynum_virtual_tokens: int )
Converte um cache past_key_values (legado) para o tensor de embeddings de prompt achatado salvo pelo PEFT.
A saída corresponde ao layout esperado por PeftModel.get_prompt() para aprendizado de prompt no estilo prefixo: forma [num_virtual_tokens, num_layers * 2 * token_dim].