PEFT documentation

UniLoRA

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

UniLoRA

Uni-LoRA é um método PEFT que compartilha um banco compacto de vetores treináveis entre os pesos dos adaptadores de baixo rank. Em vez de aprender cada elemento da matriz LoRA de forma independente, o UniLoRA projeta deterministicamente as entradas em valores compartilhados de theta_d e aprende os parâmetros compartilhados usados pela atualização do adaptador.

Início rápido

from peft import UniLoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-3B")

config = UniLoraConfig(
    r=32,
    theta_d_length=256,
    proj_seed=42,
    target_modules=["q_proj", "v_proj"],
    unilora_dropout=0.0,
    init_weights=True,
    task_type="CAUSAL_LM",
)

peft_model = get_peft_model(model, config)
peft_model.print_healthcheck()

Parâmetros Importantes

r controla a dimensão do adaptador de baixo rank. Valores maiores aumentam a capacidade do adaptador e o uso de memória.

theta_d_length controla o comprimento do banco de vetores UniLoRA compartilhado. Este é o armazenamento principal treinável compartilhado pelas entradas do adaptador projetado.

proj_seed controla a geração determinística de índices para as projeções fixas em theta_d. Reutilizar a mesma seed e configuração torna os índices de adaptador gerados reproduzíveis.

target_modules seleciona quais módulos recebem adaptadores UniLoRA. Use sufixos de módulo, como ["q_proj", "v_proj"], uma string regex ou "all-linear", quando suportado pela arquitetura do modelo.

unilora_dropout aplica dropout nas camadas do adaptador UniLoRA durante o treinamento.

init_weights controla a inicialização dos parâmetros do UniLoRA. Defina-o como False para manter uma inicialização aleatória de theta_d quando você precisar gerenciar a inicialização manualmente.

save_indices controla se os checkpoints do UniLoRA salvam os tensores de índice e escala gerados junto com os parâmetros compartilhados theta_d. Manter essa opção desativada resulta em checkpoints menores e regenera os índices a partir de proj_seed; ativá-la torna os adaptadores salvos independentes de futuras alterações na geração de índices.

Visão geral do benchmark

API

UniLoraConfig

classe peft.UniLoraConfig

< >

( 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 = Falser: int = 4proj_seed: int = 42theta_d_length: int = 256target_modules: list[str] | str | None = Noneunilora_dropout: float = 0.0fan_in_fan_out: bool = Falsebias: str = 'none'modules_to_save: list[str] | None = Noneinit_theta_d_bound: float = 0.02init_weights: bool = Truesave_indices: bool = Falselayers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = None )

Parâmetros

  • r (int) — Rank da adaptação de baixo rank. Isso controla a capacidade expressiva da atualização UniLora.
  • proj_seed (int) — Semente aleatória usada para gerar a atribuição fixa de índices. Isso garante reprodutibilidade entre execuções.
  • theta_d_length (int) — Comprimento do vetor UniLora compartilhado theta_d.
  • target_modules (Union[list[str], str], opcional) — Nomes ou padrões de módulos aos quais os adaptadores UniLora são aplicados.
    • Se uma string for fornecida, ela é tratada como uma expressão regular.
    • Se uma lista for fornecida, os módulos são correspondidos por nome exato ou sufixo.
    • O valor especial ‘all-linear’ aplica UniLora a todas as camadas Linear / Conv1D, exceto a camada de saída. Se não for especificado, os módulos são inferidos a partir da arquitetura do modelo. Um erro é lançado se a arquitetura não for suportada.
  • unilora_dropout (float) — Probabilidade de dropout aplicada dentro das camadas UniLora.
  • fan_in_fan_out (bool) — Se a camada substituída armazena os pesos no formato (fan_in, fan_out). Isso deve ser definido como True para modelos como GPT-2 que usam camadas Conv1D.
  • bias (str) — Especifica quais termos de viés são treináveis:
    • ‘none’: nenhum parâmetro de viés é atualizado
    • ‘all’: todos os parâmetros de viés são atualizados
    • ‘unilora_only’: apenas os vieses dentro das camadas UniLora são atualizados Observação: habilitar a atualização de vieses altera as saídas do modelo mesmo quando os adaptadores estão desabilitados.
  • modules_to_save (list[str], opcional) — Módulos adicionais (fora das camadas UniLora) que devem permanecer treináveis e serem salvos no checkpoint final. Isso é comumente usado para cabeçalhos específicos de tarefa, como classificadores.
  • init_theta_d_bound (float) — Limite de inicialização para o banco de vetores UniLora. Os vetores são amostrados uniformemente de [-init_theta_d_bound, init_theta_d_bound]. A inicialização com zeros é evitada para prevenir gradientes que desaparecem. Valores pequenos (por exemplo, 0.02) são recomendados para um treinamento estável.
  • init_weights (bool) — Se deve inicializar theta_d com a inicialização padrão do UniLora. Se definido como False, theta_d mantém uma inicialização aleatória.
  • save_indices (bool) — Se deve salvar os buffers de índice e escala do UniLora gerado junto com theta_d. Isso aumenta o tamanho do checkpoint, mas torna os adaptadores salvos independentes de alterações futuras na rotina de geração de índices.
  • layers_to_transform (Union[list[int], int], opcional) — Índices das camadas de transformer às quais o UniLora é aplicado. Se especificado, apenas essas camadas são modificadas. Esta opção é válida somente quando target_modules é uma lista.
  • layers_pattern (Union[list[str], str], opcional) — Padrão de nome de camada personalizado usado junto com layers_to_transform quando o modelo não segue as convenções padrão de nomenclatura de camadas. Esta opção é válida apenas quando target_modules é uma lista.

Classe de configuração para adaptadores UniLora.

Esta classe define todos os hiperparâmetros necessários para inicializar e aplicar camadas UniLora dentro do framework PEFT. A configuração é intencionalmente mínima e inclui apenas os parâmetros que são ativamente usados pela implementação atual do UniLora.

Referência: Uni-LoRA: One Vector Is All You Need https://arxiv.org/abs/2506.00799

UniLoraModel

classe peft.UniLoraModel

< >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: dict[str, torch.Tensor] | None = None )

Cria um adaptador UniLora em torno de um modelo pré-treinado.

generate_index

< >

( lora_param_count: inttheta_d_length: intproj_seed: int )

Atribua índices determinísticos theta_d ao espaço de parâmetros UniLora achatado.

Um simples np.random.choice(np.arange(theta_d_length), size=lora_param_count) amostra cada posição independentemente, o que pode deixar algumas entradas de theta_d sem uso para adaptadores menores. O UniLora, por outro lado, usa uma atribuição determinística balanceada: cada índice aparece floor(D / d) ou ceil(D / d) vezes, onde D é a contagem de parâmetros LoRA achatados e d é theta_d_length. Isso mantém a normalização por índice estável enquanto ainda embaralha a atribuição com proj_seed.

Update on GitHub