PEFT documentation
UniLoRA
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
< 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 = 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 compartilhadotheta_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 inicializartheta_dcom a inicialização padrão do UniLora. Se definido comoFalse,theta_dmantém uma inicialização aleatória. - save_indices (
bool) — Se deve salvar os buffers de índice e escala do UniLora gerado junto comtheta_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 quandotarget_modulesé uma lista. - layers_pattern (
Union[list[str], str], opcional) — Padrão de nome de camada personalizado usado junto comlayers_to_transformquando o modelo não segue as convenções padrão de nomenclatura de camadas. Esta opção é válida apenas quandotarget_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
< source >( 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.
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.