LoRA

LoRA é um dos métodos PEFT mais populares e um bom ponto de partida se você está começando a usar PEFT. Foi desenvolvido originalmente para modelos de linguagem de grande escala, mas é um método de treinamento extremamente popular para modelos de difusão devido à sua eficiência e eficácia.

A Low-Rank Adaptation (LoRA) é um método PEFT que decompõe uma grande matriz em duas matrizes menores de baixo posto. Isso reduz drasticamente o número de parâmetros que precisam ser ajustados.

O resumo do artigo é:

Um paradigma importante do processamento de linguagem natural consiste no pré-treinamento em larga escala em dados de domínio geral e na adaptação a tarefas ou domínios específicos. À medida que pré-treinamos modelos maiores, o ajuste fino completo, que retreina todos os parâmetros do modelo, torna-se menos viável. Usando o GPT-3 175B como exemplo — implantar instâncias independentes de modelos ajustados, cada uma com 175B parâmetros, é proibitivamente caro. Propomos a Low-Rank Adaptation, ou LoRA, que congela os pesos do modelo pré-treinado e injeta matrizes de decomposição de posto treináveis em cada camada da arquitetura Transformer, reduzindo drasticamente o número de parâmetros treináveis para tarefas de baixo nível. Em comparação com o GPT-3 175B ajustado com Adam, o LoRA pode reduzir o número de parâmetros treináveis em 10.000 vezes e o requisito de memória de GPU em 3 vezes. O LoRA apresenta desempenho igual ou superior ao do ajuste fino em qualidade de modelo no RoBERTa, DeBERTa, GPT-2 e GPT-3, apesar de ter menos parâmetros treináveis, um throughput de treinamento mais alto e, diferentemente dos adaptadores, nenhuma latência adicional de inferência. Também fornecemos uma investigação empírica sobre a deficiência de posto na adaptação de modelos de linguagem, que lança luz sobre a eficácia do LoRA. Liberamos um pacote que facilita a integração do LoRA com modelos PyTorch e fornecemos nossas implementações e checkpoints de modelo para RoBERTa, DeBERTa e GPT-2 em this https URL.

LoRA representa as atualizações de pesos $\Delta W$ com duas matrizes menores (chamadas de matrizes de atualização) por meio de decomposição de baixo posto. Essas novas matrizes podem ser treinadas para se adaptar aos novos dados, mantendo o número total de parâmetros baixo. A matriz de pesos original permanece congelada e não recebe mais atualizações. Para produzir os resultados finais, os pesos originais e os pesos adaptados extras são combinados. Você também pode mesclar os pesos do adaptador com o modelo base para eliminar a latência de inferência.

Essa abordagem apresenta uma série de vantagens:

• LoRA torna o ajuste fino mais eficiente ao reduzir drasticamente o número de parâmetros treináveis.
• Os pesos pré-treinados originais são mantidos congelados, o que significa que você pode ter vários modelos LoRA leves e portáveis para diversas tarefas de baixo nível construídos sobre eles.
• LoRA é ortogonal a outros métodos de eficiência de parâmetros e pode ser combinado com muitos deles.
• O desempenho de modelos ajustados usando LoRA é comparável ao desempenho de modelos totalmente ajustados.

Em princípio, o LoRA pode ser aplicado a qualquer subconjunto de matrizes de pesos em uma rede neural para reduzir o número de parâmetros treináveis. No entanto, por simplicidade e maior eficiência de parâmetros, o LoRA é tipicamente aplicado apenas aos blocos de atenção em modelos Transformer - pode valer a pena direcionar também outras camadas. O número resultante de parâmetros treináveis em um modelo LoRA depende do tamanho das matrizes de atualização, que é determinado principalmente pelo rank r e pela forma da matriz de pesos original.

Você pode inicializar as matrizes de baixo rank com diferentes casos de uso em mente - consciência de tarefa (CorDA, EVA, Astra), convergência mais rápida (PiSSA), mitigação de quantizações (LoftQ) - para citar apenas alguns casos de uso. Leia sobre as diferentes inicializações abaixo. A inicialização padrão é para que o LoRA seja um no-op, aprendendo gradualmente um novo comportamento sem interferir muito no modelo existente.

Uso

O tamanho das matrizes de atualização de baixo posto é determinado pelo rank ou r. Um posto mais alto significa que o modelo possui mais parâmetros para treinar, mas também significa que o modelo tem mais capacidade de aprendizado. No exemplo a seguir, você vai direcionar as matrizes de query e value dos blocos de atenção. Outros parâmetros importantes para definir são lora_alpha (fator de escala), bias (se none, all ou apenas os parâmetros de viés do LoRA devem ser treinados) e modules_to_save (os módulos, além das camadas LoRA, que devem ser treinados e salvos). Todos esses parâmetros - e mais - podem ser encontrados no LoraConfig.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

Visão geral do benchmark

Inicialização

A inicialização dos pesos do LoRA é controlada pelo parâmetro init_lora_weights em LoraConfig. Por padrão, o PEFT inicializa os pesos do LoRA com Kaiming-uniform para o peso A e zeros para o peso B, resultando em uma transformação identidade (igual à implementação de referência).

Para camadas de transformers.Conv1D, como as projeções do GPT-2, use fan_in_fan_out=True porque seus pesos são armazenados como (in_features, out_features) em vez do layout do nn.Linear. Os inicializadores baseados em pesos suportados usam o layout Linear para a decomposição e restauram o layout de armazenamento ao atualizar os pesos base. O escalonamento "stable" do LoRA-GA também usa a dimensão de saída, independentemente do layout de armazenamento.

Também é possível passar init_lora_weights="gaussian". Como o nome sugere, isso inicializa o peso A com uma distribuição gaussiana e zeros para o peso B (é assim que o Diffusers inicializa os pesos do LoRA).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

Também há a opção de definir init_lora_weights=False, que é útil para depuração e testes. Este deve ser o único momento em que você usa essa opção. Ao escolher essa opção, os pesos do LoRA são inicializados de modo a não resultar em uma transformação identidade.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

Treinamento

Esta seção mostra como lidar com cenários de treinamento mais complexos, em vez de apenas aplicar um adaptador de baixo rank ao modelo e fornecer dados.

Treinamento no estilo QLoRA

As configurações padrão de LoRA no PEFT adicionam pesos treináveis às camadas de query e value de cada bloco de atenção. Mas o QLoRA, que adiciona pesos treináveis a todas as camadas lineares de um modelo transformer, pode fornecer desempenho igual ao de um modelo totalmente ajustado. Para aplicar LoRA a todas as camadas lineares, como no QLoRA, defina target_modules="all-linear" (mais fácil do que especificar módulos individuais por nome, o que pode variar dependendo da arquitetura).

config = LoraConfig(target_modules="all-linear", ...)

Para mais informações sobre como aplicar quantização a adaptadores PEFT, consulte o guia de quantização.

Replicação de camadas eficiente em memória com LoRA

Uma abordagem usada para melhorar o desempenho de modelos consiste em expandir um modelo duplicando camadas para construir um modelo maior a partir de um modelo pré-treinado de um determinado tamanho. Por exemplo, aumentar um modelo de 7B para um modelo de 10B, conforme descrito no paper SOLAR. O PEFT LoRA suporta esse tipo de expansão de forma eficiente em memória, permitindo o ajuste fino posterior usando adaptadores LoRA anexados às camadas após a replicação. As camadas replicadas não consomem memória adicional, pois compartilham os pesos subjacentes, de modo que a única memória extra necessária é a dos pesos dos adaptadores. Para usar esse recurso, você deve criar uma configuração com o argumento layer_replication.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

Assumindo que o modelo original tivesse 5 camadas [0, 1, 2 ,3, 4], isso criaria um modelo com 7 camadas organizadas como [0, 1, 2, 3, 2, 3, 4]. Isso segue a convenção de mesclagem pass through do mergekit, na qual sequências de camadas especificadas como tuplas com início inclusivo e fim exclusivo são empilhadas para construir o modelo final. Cada camada no modelo final recebe seu próprio conjunto distinto de adaptadores LoRA.

Fewshot-Metamath-OrcaVicuna-Mistral-10B é um exemplo de modelo treinado usando esse método no Mistral-7B expandido para 10B. O adapter_config.json mostra uma configuração de adaptador LoRA de exemplo que aplica esse método para fine-tuning.

Controle fino sobre ranks e alpha (escala)

Por padrão, todas as camadas alvo do LoRA terão o mesmo rank r e o mesmo lora_alpha (que determina o escalonamento do LoRA), conforme especificado no LoraConfig. Em alguns casos, no entanto, você pode querer indicar valores diferentes para camadas diferentes. Isso é possível passando os argumentos rank_pattern e alpha_pattern para LoraConfig. Esses argumentos devem ser dicionários com a chave sendo o nome da camada e o valor sendo o valor de rank/alpha. As chaves podem ser expressões regulares (regex). Todas as camadas LoRA que não forem explicitamente mencionadas em rank_pattern e alpha_pattern assumirão os valores padrão de r e lora_alpha.

Para dar um exemplo, vamos supor que temos um modelo com a seguinte estrutura:

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42} corresponderá a todas as 3 camadas foo. Nem foobar nem barfoo são correspondidos.
• rank_pattern={"^foo": 42} corresponderá apenas à camada foo do modelo, mas nem a module.foo nem a module.module.foo. Isso ocorre porque ^ significa “início da string” ao usar expressões regulares, e apenas foo começa com "foo"; os outros nomes de camada possuem prefixos.
• rank_pattern={"^module.foo": 42} corresponde apenas a module.foo, mas não a module.module.foo, pelo mesmo motivo.
• rank_pattern={"module.foo": 42} corresponde tanto a module.foo quanto a module.module.foo, mas não a foo.
• rank_pattern={"^foo": 42, "^module.module.foo": 55} corresponde a foo e module.module.foo, respectivamente, mas não a module.foo.
• Não é necessário indicar $ para marcar o fim da correspondência, pois isso é adicionado automaticamente pelo PEFT.

A mesma lógica se aplica a alpha_pattern. Se você tiver dúvidas, não tente ser criativo com expressões regulares — basta passar o nome completo de cada módulo com um rank/alpha diferente, precedido pelo prefixo ^, e estará tudo certo.

Detectar automaticamente módulos de destino viáveis

peft.helpers.KappaTuneSelector implementa a estratégia de seleção de alvos baseada no número de condicional descrita no artigo KappaTune. Ela varre todos os módulos nn.Linear e, para modelos em que os pesos de especialistas MoE são armazenados como tensores nn.Parameter 3D fundidos (por exemplo, Llama-4, Qwen3-MoE), também esses parâmetros, calcula o número de condicional da matriz κ = σ_max / σ_min para cada um e seleciona as camadas mais isotrópicas (menor κ). Essas camadas isotrópicas servem como candidatos ideais para fine-tuning, pois sua natureza de alta entropia permite que absorvam novas informações com mais facilidade, mantendo as camadas especializadas e anisotrópicas intactas para mitigar o esquecimento catastrófico durante o aprendizado contínuo.

Use peft.helpers.find_kappa_target_modules() como uma linha única para obter os target_modules ideais para o LoraConfig:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

Veja um exemplo completo aqui.

Direcionando-se diretamente para nn.Parameter

Em geral, você deve usar target_modules para direcionar o módulo (por exemplo, nn.Linear). No entanto, em algumas circunstâncias, isso não é possível. Por exemplo, em muitas camadas de mixture of expert (MoE) no HF Transformers, em vez de usar nn.Linear, um nn.Parameter é utilizado. O PEFT normalmente sobrescreve o método forward para LoRA, mas para nn.Parameter, não há nenhum. Portanto, para aplicar LoRA a esse parâmetro, ele precisa ser direcionado com target_parameters. Como exemplo, para Llama4, você pode passar: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

Observe que, ao direcionar parâmetros de especialistas, o PEFT pode adicionar uma sobrecarga de tempo de execução considerável. A razão é que o PEFT sempre materializa a contribuição do LoRA para cada especialista, mesmo que apenas uma pequena quantidade de especialistas seja necessária. Durante o treinamento, isso é menos relevante, pois, ao longo da sequência, tipicamente uma grande fração dos especialistas é ativada pelo menos uma vez. No entanto, durante a inferência, normalmente um cache KV é usado e, portanto, precisamos calcular apenas o último token, o que significa que apenas uma pequena quantidade de especialistas é ativada. Portanto, usar LoRA em camadas MoE pode resultar em um atraso considerável no tempo de inferência. A recomendação, portanto, é mesclar os pesos (model.merge_adapter() ou model = model.merge_and_unload()). Isso remove a sobrecarga do PEFT.

Uma investigação mais detalhada sobre essa questão pode ser encontrada neste pull request sobre otimização de MoE.

Observações

• No momento, este argumento permite direcionar nn.Parameters de 2 ou 3 dimensões. Assume-se que, no caso de um parâmetro de 3 dimensões, a dimensão 0 é a dimensão do especialista.
• Vários adaptadores LoRA (adicionados via model.add_adapter ou model.load_adapter) que usam target_parameters são suportados, mas todos eles devem visar o mesmo conjunto de parâmetros.

Parâmetros de especialistas MoE e vLLM

Alguns modelos MoE em Transformers armazenam os pesos dos especialistas como tensores nn.Parameter (frequentemente 3D), e não como módulos nn.Linear. Para aplicar LoRA a esses especialistas, use target_parameters e defina um rank por camada com rank_pattern:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

Isso mantém o orçamento total de parâmetros do LoRA semelhante ao das camadas densas (veja LoRA Without Regret de Schulman et. al.). Os módulos não especialistas usam o rank padrão r.

A inferência acelerada com o modelo ajustado é possível com, por exemplo, vLLM, que suporta camadas de especialistas MoE fundidas desde a v0.11.2.

Treine tokens de forma eficiente junto com o LoRA

Os adaptadores PEFT LoRA suportam a adição de novos tokens com o parâmetro trainable_token_indices. Isso permite o ajuste de outros tokens em conjunto com o fine-tuning de camadas específicas. Apenas os tokens especificados são treinados e todos os outros permanecem inalterados. Isso economiza memória e não descarta o contexto aprendido dos embeddings de tokens existentes, ao contrário do treinamento de toda a matriz de embeddings. Internamente, este método utiliza a camada de TrainableTokensModel.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

No trecho abaixo, mostramos como adicionar novos tokens ao modelo e como treiná-lo junto com as outras camadas do modelo.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

Os pesos dos tokens são salvos como parte do dicionário de estado do adaptador, junto com os pesos do LoRA. O ajuste fino completo e o salvamento da matriz de incorporação teriam armazenado um arquivo muito maior.

Para dar uma noção de quanto VRAM pode ser economizado, uma comparação rudimentar do exemplo acima foi feita entre treinar a matriz de incorporação totalmente (modules_to_save=["embed_tokens"]), usar um LoRA para a matriz de incorporação (target_modules=[..., "embed_tokens"], rank 32) e tokens treináveis (trainable_token_indices=[...], 6 tokens):

Vinculação de pesos

Muitos LMs causais usam weight tying, no qual dois ou mais pesos compartilham os mesmos parâmetros subjacentes. No caso mais comum, os pesos de incorporação de entrada (embed_tokens) e os pesos de projeção de saída (lm_head) compartilham o mesmo tensor. Isso ocorre porque reduz o número de parâmetros e geralmente preserva a qualidade do modelo.

Nem sempre é óbvio como o PEFT lida com esses pesos vinculados quando eles são alvo de ajuste fino. Para o LoRA, o ensure_weight_tying no LoraConfig controla se o PEFT deve manter explicitamente vinculadas as atualizações do lado do adaptador para aquelas camadas. Na prática, isso pode afetar modules_to_save, target_modules e trainable_token_indices. Observe que essa lógica depende parcialmente de convenção no que diz respeito ao nome das camadas ("embed_tokens", "lm_head") e o funcionamento adequado não pode ser garantido se essas convenções não forem usadas.

As tabelas abaixo resumem o comportamento esperado.

modules_to_save

target_modules

trainable_token_indices

Para tokens treináveis, temos a complicação adicional de que, mesmo que a cabeça do LM e os embeddings estejam vinculados, como usuário, posso querer fazer o ajuste fino de tokens diferentes neles. Na tabela de exemplo abaixo, diferenciamos, portanto, entre fazer o ajuste fino dos mesmos tokens e fazer o ajuste fino de tokens diferentes.

Para os usuários, isso significa:

• Em geral, se você deseja ajustar pesos que estão vinculados e quer mantê-los vinculados, passe ensure_weight_tying=True.
• Se os pesos do seu modelo base não estiverem vinculados, ensure_weight_tying=True não pode forçar a vinculação e apenas emite um aviso.
• Para trainable_token_indices, as camadas vinculadas devem usar os mesmos índices de tokens quando ensure_weight_tying=True.

Otimizadores

O treinamento com LoRA pode incluir, opcionalmente, otimizadores de uso especial. Atualmente, o PEFT suporta LoRA-FA, LoRA+ e LoRA com pré-condicionamento riemanniano.

Otimizador LoRA-FA

O treinamento com LoRA pode ser mais eficaz e eficiente usando LoRA-FA, conforme descrito em LoRA-FA. O LoRA-FA reduz o consumo de memória de ativação ao fixar a matriz A e ajustar apenas a matriz B. Durante o treinamento, o gradiente de B é otimizado para aproximar o gradiente do ajuste fino de parâmetros completos. Além disso, o consumo de memória do LoRA-FA não é sensível ao rank (uma vez que ele elimina a ativação de $A$), portanto, é possível melhorar o desempenho aumentando o lora rank sem aumentar o consumo de memória.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ otimizado

O treinamento de LoRA pode ser otimizado usando LoRA+, que utiliza taxas de aprendizado diferentes para as matrizes de adaptador A e B, demonstrando um aumento de até 2x na velocidade de ajuste fino e de 1-2% no desempenho.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA pré-condicionado riemanniano

O treinamento de LoRA pode ser aprimorado com um pré-condicionador riemanniano, conforme descrito em Riemannian Preconditioned LoRA. Em cada passo do otimizador, os gradientes das matrizes LoRA $A$ e $B$ são multiplicados por um $r \times r$ pré-condicionador que reescala o gradiente euclidiano em direção à direção riemanniana (gradiente escalonado) na variedade de matrizes de baixo posto, o que melhora o condicionamento da atualização e pode melhorar a convergência. Como o pré-condicionador é $r \times r$, sua sobrecarga de memória e tempo de execução é pequena em relação ao posto do LoRA. create_riemannian_optimizer envolve qualquer classe de otimizador base (por exemplo, torch.optim.AdamW ou torch.optim.SGD): os parâmetros não-LoRA são atualizados pelo otimizador base sem alterações, e apenas nn.Linear-camadas LoRA com formatolora_A / lora_B) são pré-condicionados.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg é um termo de amortecimento adicionado à $r \times r$ diagonal da matriz antes da inversão; ele estabiliza o pré-condicionador quando um fator LoRA é (quase) de posto deficiente.

Treinamento Pós

Esta seção mostra possíveis métodos de pós-processamento para adaptadores treinados.

Mesclar os pesos do LoRA no modelo base

Embora o LoRA seja significativamente menor e mais rápido de treinar, você pode encontrar problemas de latência durante a inferência devido ao carregamento separado do modelo base e do adaptador LoRA. Para eliminar a latência, use a função merge_and_unload() para mesclar os pesos do adaptador com o modelo base. Isso permite que você use o novo modelo mesclado como um modelo independente. A função merge_and_unload() não mantém os pesos do adaptador na memória.

Abaixo está um diagrama que explica a intuição por trás da mesclagem de adaptadores LoRA:

Mostramos nos trechos abaixo como executar isso usando PEFT.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

É importante atribuir o modelo retornado a uma variável e usá-lo, pois merge_and_unload() não é uma operação in-place. Se você precisar manter uma cópia dos pesos para poder desintegrar o adaptador posteriormente ou excluir e carregar outros diferentes, você deve usar a função merge_adapter() em vez disso. Agora você tem a opção de usar unmerge_adapter() para retornar o modelo base.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

Em um modelo quantizado, o desmerge não é exato: o merge re-quantiza o peso base, e ciclos repetidos de merge e desmerge podem acumular erro de arredondamento. Consulte Merging adapters into quantized weights.

Se vários adaptadores estiverem ativos e apenas alguns deles forem mesclados, os adaptadores que não forem mesclados não serão aplicados silenciosamente. Esse comportamento mudará no PEFT v1.0. Consulte Mesclando apenas alguns dos adaptadores ativos.

A função add_weighted_adapter() é útil para mesclar vários LoRAs em um novo adaptador com base em um esquema de ponderação fornecido pelo usuário no parâmetro weights. Abaixo está um exemplo de ponta a ponta.

Primeiro, carregue o modelo base:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

Em seguida, carregamos o primeiro adaptador:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

Em seguida, carregue um adaptador diferente e combine-o com o primeiro:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

Existem vários métodos suportados para combination_type. Consulte a documentação para mais detalhes. Observe que “svd” como combination_type não é suportado ao usar torch.float16 ou torch.bfloat16 como tipo de dados.

Agora, execute a inferência:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

Recuperando o desempenho do modelo base por meio da redução da dimensão do intruso

O artigo LoRA vs Full Fine-tuning: An Illusion of Equivalence argumenta que o treinamento com LoRA introduz dimensões extras nos pesos que têm muito pouco em comum com os pesos já aprendidos e levam ao esquecimento de informações já aprendidas. O PEFT implementa a mitigação sugerida em peft.tuners.lora.intruders.reduce_intruder_dimension().

A mitigação utilizará um modelo PEFT com um LoRA carregado e criará um novo adaptador modificado que será carregado junto com o adaptador existente e se tornará o adaptador ativo.

Exemplo de uso:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

Existem alguns hiperparâmetros que podem ser usados para ajustar a eficácia da mitigação, mas, como evidenciado na Figura 8 do artigo, sempre haverá um compromisso entre a precisão da tarefa aprendida pelo adaptador e o esquecimento do conhecimento do modelo base. A mitigação removerá informações do adaptador para reduzir o impacto no esquecimento de conhecimentos anteriores, mas isso também significa que algumas informações sobre a tarefa aprendidas pelo adaptador também serão perdidas.

Embora os padrões sejam configurados para oferecer um bom equilíbrio entre os dois fatores, não há garantia de que eles se mantenham adequados para o seu adaptador, o seu modelo e os seus dados; portanto, é recomendável ter um benchmark pronto para medir o efeito.

Carregar adaptadores

Adapters podem ser carregados em um modelo pré-treinado com load_adapter(), o que é útil para testar diferentes adapters cujos pesos não foram mesclados. Defina os pesos do adapter ativo com a função set_adapter().

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

Para retornar o modelo base, você pode usar unload() para descarregar todos os módulos LoRA ou delete_adapter() para excluir o adaptador por completo. unload() não é uma operação in-place; lembre-se de atribuir o modelo retornado a uma variável e usá-lo.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Paralelismo de Tensors

O LoRA oferece suporte a Tensor Parallelism (TP) conforme fornecido pelo Transformers. Quando um modelo base é carregado com um tp_plan, o PEFT detecta automaticamente a configuração de TP de cada módulo alvo e adiciona os hooks apropriados aos pesos do adaptador LoRA para que eles participem corretamente do cálculo tensor-parallel.

O suporte a Tensor Parallelism para LoRA requer transformers >= 5.4.0. A API de Tensor Parallelism baseada em DTensor requer peft >= 0.21.1 e transformers >= 5.17.0.

O uso é idêntico ao fluxo de trabalho padrão do LoRA — basta carregar o modelo base com um tp_plan antes de envolvê-lo com o PEFT:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

Salvar e carregar funcionam normalmente via save_pretrained / from_pretrained. O PEFT reúne os pesos do adaptador fragmentados de volta em tensores completos antes de salvar, de modo que os checkpoints são portáveis e independentes do número de dispositivos usados durante o treinamento.

Se você aplicar paralelismo de tensor sem um plano de TP, por exemplo, com parallelize_module do PyTorch, o PEFT dimensiona os pesos LoRA de um nn.Linear particionado para o tamanho do shard local se a malha de dispositivos do peso tiver uma dimensão nomeada "tp", e para a forma completa da camada caso contrário (como no FSDP2). O PEFT não adiciona hooks de TP a esses pesos LoRA nem os agrega ao salvar. Se a dimensão da sua malha de TP tiver um nome diferente, adicione-a antes de criar o modelo PEFT:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

Inferência

Esta seção apresenta o que você pode fazer durante o tempo de inferência com LoRA, como desacoplar o adaptador.

LoRA ativado (aLoRA)

Activated LoRA (aLoRA) é uma arquitetura de adaptador de baixo rank para LMs causais que reutiliza o cache KV do modelo base existente para uma inferência mais eficiente. Essa abordagem é mais adequada para pipelines de inferência que dependem do modelo base para a maioria das tarefas/gerações, mas usam adaptador(es) aLoRA para executar tarefa(s) especializada(s) dentro da cadeia. Por exemplo, verificar ou corrigir as saídas geradas pelo modelo base. Nesses cenários, os tempos de inferência podem ser acelerados em uma ordem de grandeza ou mais. Para mais informações sobre aLoRA e muitos casos de uso de exemplo, veja o paper do aLoRA.

Essa técnica procura a última ocorrência de uma sequência de invocação (alora_invocation_tokens) em cada entrada (que pode ter apenas 1 token). Ela ativa os pesos do adaptador nos tokens a partir do início da sequência de invocação. Qualquer entrada após a sequência de invocação também é adaptada, e todos os tokens gerados usarão os pesos adaptados. Os pesos nos tokens anteriores são deixados sem adaptação, tornando o cache desses tokens intercambiável com o cache do modelo base devido à máscara de atenção causal nos LMs causais. O uso é muito semelhante ao do LoRA padrão. A principal diferença é que a sequência de invocação deve ser especificada quando o adaptador é criado:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

alora_invocation_tokens` é uma lista de ids de tokens inteiros. Dada uma string de invocação desejada, isso pode ser obtido como:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

O tokenizer é o tokenizer do modelo base. Use add_special_tokens=False para evitar a adição dos tokens SOS/EOS na nossa string de busca (o que provavelmente causará a falha da busca).

Observações

• aLoRA é suportado apenas para tarefas de task_type=CAUSAL_LM devido ao seu foco na reutilização de cache.
• Como os pesos são adaptados em menos tokens, muitas vezes (nem sempre) o aLoRA requer um rank (r) maior do que o LoRA. r=32 pode ser um bom ponto de partida.
• Os pesos do aLoRA não podem ser mesclados ao modelo base por definição, pois os pesos do adaptador são aplicados seletivamente a um subconjunto de tokens. Tentativas de mesclagem resultarão em erros.
• O beam search ainda não é suportado.
• Em geral, não é recomendado adicionar novos tokens ao tokenizer que não estejam presentes no modelo base. Isso pode complicar o caso de uso em que o modelo base e o modelo adaptador operam em contextos sobrepostos. Você pode contornar isso adicionando tokens treináveis ao modelo base antes de treinar o adaptador.

Escolha da sequência de invocação e do design do SFT

Você deve adicionar a sequência alora_invocation_tokens, pois ela não é adicionada automaticamente. Recomendamos ativar os pesos do adaptador precocemente (no início de qualquer prompt específico do adaptador), mas após qualquer entrada longa, para maximizar o desempenho do modelo sem comprometer a reutilização do cache. Como em qualquer modelo, o formato deve ser consistente entre o treinamento e o teste.

Considere o exemplo a seguir, em que o modelo base possui um modelo de chat e o objetivo é treinar o adaptador para gerar uma saída desejada.

• Opção 1: Se não houver um prompt específico para a tarefa, ou seja, se a entrada for um histórico de chat com o prompt assistant, então o prompt assistant do template de chat (por exemplo, <|start_of_role|>assistant<|end_of_role|>) é uma escolha natural para a string de invocação. Consulte o template de chat do modelo para encontrar o prompt do modelo.
• Opção 2: Se houver um prompt específico da tarefa para o adaptador que descreve a tarefa que o adaptador está aprendendo, e esse prompt for colocado como uma rodada de user imediatamente antes da geração, então o prompt de user do modelo de chat (por exemplo, <|start_of_role|>user<|end_of_role|>) é uma escolha natural para a string de invocação.

Após decidir pela string de invocação, obtenha o tokenizer do modelo e obtenha alora_invocation_tokens como

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Um exemplo de configuração de inferência está em alora finetuning.

Ao usar strings personalizadas para a string de invocação, certifique-se de que o início e o fim da string sejam tokens especiais para evitar problemas com a tokenização nas fronteiras.

Para entender o motivo, imagine que ‘a’, ‘b’, ‘c’ e ‘ab’ são tokens no seu tokenizer (números 1, 2, 3 e 4, respectivamente). Suponha que seu alora_invocation_tokens = [2, 3]. Agora imagine que sua string de entrada é “abc”. Como “ab” é um token, isso será tokenizado como [4,3]. Assim, o alora_invocation_tokens não será encontrado, apesar de a string “bc” estar presente nela. No entanto, se o início e o fim da string de invocação forem tokens especiais, esse caso de falha nunca ocorrerá, pois tokens especiais nunca são tokenizados no mesmo token junto com outros caracteres.

Usando (e reutilizando) cache para geração

O principal objetivo do aLoRA é tornar o cache de KV intercambiável entre o modelo base e os modelos adaptadores aLoRA antes da sequência de invocação, uma vez que os valores de KV do modelo base e do modelo adaptado não são compatíveis. Especificamente, as chaves e os valores armazenados durante uma geração de um modelo podem ser usados em gerações subsequentes para evitar operações de pré-preenchimento caras para tokens de contexto. Ao compartilhar o cache entre o modelo base e os adaptadores aLoRA, existem 2 padrões principais:

1. O modelo base gerou algo e, em seguida, um adaptador aLoRA é chamado para fazer uma geração de acompanhamento. Por exemplo, o modelo base responde a uma pergunta e um aLoRA treinado para detectar alucinações verifica a resposta do modelo base.
2. Um adaptador aLoRA gerou algo, e o modelo base ou um adaptador aLoRA diferente é chamado para fazer uma geração de acompanhamento em que há sobreposição parcial de contexto com o aLoRA original. Por exemplo, o usuário fornece uma consulta, e um aLoRA reescreve a consulta para que ela seja mais autossuficiente e melhore a recuperação em um sistema RAG. Em seguida, os documentos são recuperados e carregados no contexto, o aLoRA verifica se esses documentos são relevantes para a pergunta e, então, o modelo base gera uma resposta.

Para demonstrar os comportamentos acima ao usar cache, estamos usando DynamicCache do transformers. Tenha o cuidado de garantir que os valores de cache adaptados não sejam misturados com os valores de cache base. Em particular, uma etapa extra é necessária para compartilhar o cache quando há sobreposição parcial de contexto (padrão 2).

Padrão 1: modelo base seguido por aLoRA Aqui, a entrada e a geração inteiras do modelo base são fornecidas ao adaptador aLoRA, junto com a sequência de invocação:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

Padrão 2: geração com aLoRA seguida pelo modelo base (ou outro aLoRA) com sobreposição parcial de contexto Aqui, fazemos o pré-preenchimento do contexto compartilhado usando o modelo base e, em seguida, geramos.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

Inferência com diferentes adaptadores LoRA no mesmo lote

Normalmente, cada lote de inferência precisa usar o mesmo adaptador (ou adaptadores) no PEFT. Isso pode ser inconveniente às vezes, pois podemos ter lotes que contêm amostras destinadas a serem usadas com diferentes adaptadores LoRA. Por exemplo, poderíamos ter um modelo base que funciona bem em inglês e mais dois adaptadores LoRA, um para francês e outro para alemão. Normalmente, teríamos que dividir nossos lotes de modo que cada lote contenha apenas amostras de um dos idiomas; não podemos combinar diferentes idiomas no mesmo lote.

Felizmente, é possível misturar diferentes adaptadores LoRA no mesmo lote usando o argumento adapter_name. Abaixo, mostramos um exemplo de como isso funciona na prática. Primeiro, vamos carregar o modelo base, o inglês e os dois adaptadores, o francês e o alemão, da seguinte forma:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

model_id = ...
tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

Agora, queremos gerar texto em uma amostra que contém os três idiomas: as três primeiras amostras estão em inglês, as três seguintes estão em francês e as três últimas estão em alemão. Podemos usar o argumento adapter_names para especificar qual adaptador usar para cada amostra. Como nosso modelo base é usado para o inglês, usamos a string especial "__base__" para essas amostras. Para as três amostras seguintes, indicamos o nome do adaptador do fine-tune LoRA em francês, neste caso "adapter_fr". Para as três últimas amostras, indicamos o nome do adaptador do fine-tune LoRA em alemão, neste caso "adapter_de". Dessa forma, podemos usar o modelo base e os dois adaptadores em um único lote.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

Observe que a ordem não importa aqui, ou seja, as amostras no lote não precisam ser agrupadas por adaptador, como no exemplo acima. Basta garantir que o argumento adapter_names esteja alinhado corretamente com as amostras.

Além disso, a mesma abordagem também funciona com o recurso modules_to_save, que permite salvar e reutilizar camadas específicas de redes neurais, como cabeçalhos personalizados para tarefas de classificação, entre diferentes adaptadores LoRA.

Observações

O uso deste recurso apresenta algumas desvantagens, a saber:

• Funciona apenas para inferência, não para treinamento.
• Desativar adaptadores usando o contexto with model.disable_adapter() tem precedência sobre adapter_names.
• Você não pode passar adapter_names quando alguns pesos de adaptador foram mesclados com o peso base usando o método merge_adapter. Por favor, desfaça a mesclagem de todos os adaptadores primeiro, chamando model.unmerge_adapter(). Observe que mesclar apenas alguns dos adaptadores ativos tem uma observação semelhante fora de adapter_names.
• Por razões óbvias, isso não pode ser usado após chamar merge_and_unload(), pois, nesse caso, todos os adaptadores LoRA serão mesclados nos pesos base.
• Este recurso não funciona atualmente com DoRA, portanto, defina use_dora=False em seu LoraConfig se você quiser usá-lo.
• O recurso modules_to_save é atualmente suportado apenas para camadas dos tipos Linear, Embedding, Conv2d e Conv1d.
• Há um overhead esperado para inferência com adapter_names, especialmente se a quantidade de adaptadores diferentes no lote for alta. Isso ocorre porque o tamanho do lote é efetivamente reduzido para o número de amostras por adaptador. Se o desempenho em tempo de execução for sua prioridade máxima, tente o seguinte:
  • Aumente o tamanho do lote.
  • Tente evitar ter um grande número de adaptadores diferentes no mesmo lote; prefira lotes homogêneos. Isso pode ser alcançado ao fazer o buffer de amostras com o mesmo adaptador e executar a inferência apenas com um pequeno número de adaptadores diferentes.
  • Dê uma olhada em implementações alternativas, como LoRAX, punica ou S-LoRA, que são especializadas para trabalhar com um grande número de adaptadores diferentes.

Compondo e Reutilizando Adaptadores LoRA

Arrow

Arrow é um algoritmo de roteamento modular projetado para combinar múltiplos adaptadores LoRA pré-treinados e específicos para tarefas, a fim de resolver uma tarefa dada, de forma semelhante ao Polytropon, mas sem a necessidade de ajuste fino. Em vez de mesclar todos os adaptadores de forma ingênua, o Arrow introduz um mecanismo de roteamento de mistura de especialistas (MoE) por token, livre de gradiente. No momento da inferência, ele primeiro calcula um protótipo para cada LoRA, extraindo o vetor singular direito principal de sua decomposição SVD. Cada representação de token é então comparada a esses protótipos por meio de similaridade de cosseno para obter os coeficientes de roteamento. Os tokens são atribuídos aos k adaptadores LoRA mais relevantes, com os coeficientes normalizados por meio de softmax, e suas saídas são combinadas linearmente. Isso permite a reutilização eficaz de módulos LoRA existentes para novas tarefas e leva a uma generalização zero-shot mais robusta.

In PEFT, Arrow is enabled through [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Além disso, você pode adicionar ou remover adaptadores após chamar create_arrow_model—por exemplo, para fazer o ajuste fino de um novo adaptador ou descartar um desnecessário. Uma vez que os adaptadores estejam configurados, você pode ativar o "arrow_router" para inferência e usar o Arrow. Observe que, se você adicionar um novo adaptador LoRA após create_arrow_model e quiser fazer o ajuste fino dele, deve definir explicitamente o novo adaptador como ativo, pois "arrow_router" é ativado por padrão em create_arrow_model.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub aprimora o Arrow purificando adaptadores LoRA específicos de tarefa antes do roteamento. A ideia central é subtrair o conhecimento geral codificado no espaço LoRA—com base no princípio do esquecimento por negação—para que os adaptadores de tarefa fiquem mais isolados e focados nos sinais relevantes para a tarefa. Concretamente, o GenKnowSub estima um subespaço “geral” de baixa dimensão a partir de um conjunto de adaptadores LoRA gerais (não específicos de tarefa) e remove esse componente da atualização LoRA de cada adaptador de tarefa antes do roteamento token a token do Arrow. Isso geralmente melhora a composicionalidade e reduz a interferência ao combinar muitos adaptadores de tarefa.

No PEFT, ative o GenKnowSub definindo use_gks=True em ArrowConfig e fornecendo general_adapter_paths em create_arrow_model:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Para codificar conhecimento geral, o GenKnowSub subtrai a média dos adaptadores gerais fornecidos de cada adaptador específico para a tarefa uma única vez, antes do início do roteamento. Além disso, a capacidade de adicionar ou remover adaptadores após a chamada de create_arrow_model (conforme descrito na seção Arrow) ainda é suportada neste caso.

Coisas a ter em mente ao usar Arrow + GenKnowSub:

• Todos os adaptadores LoRA (específicos de tarefa e gerais) devem compartilhar o mesmo rank e target_modules.

• Qualquer inconsistência nessas configurações causará um erro em create_arrow_model.

• O uso de diferentes fatores de escala (lora_alpha) entre adaptadores de tarefa é suportado — o Arrow os trata automaticamente.

• A mesclagem do "arrow_router" não é suportada, devido ao seu comportamento de roteamento dinâmico.

• Em create_arrow_model, os adaptadores de tarefa são carregados como task_i e os adaptadores gerais como gks_j (onde i e j são índices). A função garante a consistência de target_modules, rank e se os adaptadores são aplicados a camadas Linear ou Linear4bit. Em seguida, adiciona o módulo "arrow_router" e o ativa. Qualquer personalização desse processo exige a sobrescrita de create_arrow_model.

• Esta implementação é compatível com quantização de 4 bits (via bitsandbytes):

  Copiado

  from transformers import AutoModelForCausalLM, BitsAndBytesConfig
  import torch
  
  # Quantisation config
  bnb_config = BitsAndBytesConfig(
          load_in_4bit=True,
          bnb_4bit_quant_type="nf4",
          bnb_4bit_compute_dtype=torch.bfloat16,
          bnb_4bit_use_double_quant=False,
      )
  
  # Loading the model
  base_model = AutoModelForCausalLM.from_pretrained(
      "microsoft/Phi-3-mini-4k-instruct",
      dtype=torch.bfloat16,
      device_map="auto",
      quantization_config=bnb_config,
  )
  
  # Now call create_arrow_model() as we explained before.

API

LoraConfig

LoraModel

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)

>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

Utilitário

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

Utilitários

Redução de Dimensão Intruder