PEFT documentation

Conversão de LoRA

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Conversão de LoRA

Funções que permitem converter modelos PEFT não-LoRA em modelos LoRA.

Descrição

O PEFT suporta dezenas de diferentes técnicas de ajuste fino eficiente de parâmetros. A mais popular, de longe, é o LoRA. Isso significa que muitos outros pacotes também suportam o LoRA. Por exemplo, o Diffusers permite carregar adaptadores LoRA para alterar as capacidades de modelos de difusão. O vLLM permite servir modelos com adaptadores LoRA. Isso é ótimo, mas, infelizmente, todos os outros métodos PEFT, não-LoRA, raramente são suportados. Portanto, mesmo que outro método PEFT funcionasse melhor para o seu caso de uso específico, você pode ser impedido de usá-lo porque os pacotes downstream não oferecem suporte.

Aqui apresentamos uma solução potencial. O PEFT oferece duas funções, save_as_lora() e convert_to_lora(), que permitem converter um adaptador PEFT em um adaptador LoRA. Nem todos os métodos PEFT suportam isso no momento, mas, se suportarem, significa que você pode começar com o método PEFT que funciona melhor para você e, depois, usá-lo como se fosse um adaptador LoRA.

Exemplo

O rank LoRA do adaptador convertido pode ser definido como um rank fixo, passando um int > 0 para o argumento rank, ou como um rank dinâmico, que se adapta a cada camada, passando um float entre 0 e 1 para o argumento rank. Ranks dinâmicos podem ser potencialmente mais eficientes (mesmo desempenho com menos parâmetros).

Rank de LoRA fixo

O uso de save_as_lora() é relativamente simples:

from peft import get_peft_model, save_as_lora

# first load and train your non-LoRA PEFT model as normal
base_model = ...
non_lora_config = ...
model = get_peft_model(base_model, non_lora_config)
# check that this PEFT method can indeed be converted to LoRA
assert model.supports_lora_conversion()
...  # train the model

# the rank of the LoRA adapter that you want to convert to
target_rank = 64
# save as a LoRA checkpoint
save_as_lora(output_path, model, rank=target_rank)

Isso criará um checkpoint LoRA em output_path que você pode carregar como qualquer outro adaptador LoRA, ou usar em pacotes downstream como Diffusers ou vLLM.

A função convert_to_lora() é útil se você não quiser salvar o adaptador LoRA convertido, mas sim usar os pesos convertidos imediatamente, por exemplo, para realizar avaliações:

from peft import convert_to_lora, get_peft_model, set_peft_model_state_dict

base_model = ...
non_lora_config = ...
model = get_peft_model(base_model, non_lora_config)
...  # train the model

# get the lora config and state dict of the converted lora model
lora_config, lora_state_dict = convert_to_lora(model, rank=target_rank)
# reload the base model, or use model.unload()
base_model = ...
# apply the lora config to the base model
lora_model = get_peft_model(base_model, lora_config)
# load the LoRA weights onto the base model
set_peft_model_state_dict(lora_model, state_dict)

Rank dinâmico de LoRA

Nos exemplos acima, usamos um rank de LoRA fixo para a conversão. No entanto, é plausível que algumas camadas não necessitem de um rank alto para serem convertidas com precisão, enquanto outras camadas exijam um rank maior. Para acomodar isso, o PEFT oferece a opção de passar um número flutuante entre 0 e 1 como argumento rank. Digamos que você passe rank=0.5. Isso significa que, para cada camada, o rank do adaptador LoRA é escolhido de modo que o adaptador LoRA explique 50% da variância nos pesos introduzida pelo adaptador original. Em termos mais técnicos, por baixo dos panos, realizamos uma Decomposição em Valores Singulares na contribuição de pesos do adaptador e, em seguida, tomamos os valores singulares principais que, quando normalizados, somam o valor passado.

# set a dynamic rank by passing a float
threshold = 0.7
# save as a LoRA checkpoint
save_as_lora(output_path, model, rank=threshold)
# get the lora config and state dict directly:
lora_config, lora_state_dict = convert_to_lora(model, rank=threshold)
# inspect the different ranks per layer:
print(lora_config.rank_pattern)

O uso desse tipo de rank dinâmico de LoRA pode ser útil se a contribuição das diferentes camadas variar muito. A desvantagem é que isso pode significar que algumas camadas terão um rank de LoRA muito alto, o que pode levar a picos de memória. Por favor, teste o que funciona melhor para o seu caso de uso.

Compilando o modelo

Para modelos grandes, a conversão pode levar algum tempo; por exemplo, cada módulo PEFT precisa passar por um cálculo de SVD. Ao passar compile_kwargs para save_as_lora() ou convert_to_lora(), você pode aplicar torch.compile à função de conversão e potencialmente acelerar o processo. Os compile_kwargs são um dicionário de argumentos de palavra-chave que são passados para torch.compile (um dicionário vazio também funciona). Abaixo está um exemplo:

compile_kwargs = {"dynamic": True, "mode": "max-autotune-no-cudagraphs", "fullgraph": True}
save_as_lora(output_path, model, rank=rank, compile_kwargs=compile_kwargs)

Conversão de LoRA para LoRA

Também é possível converter um adaptador LoRA em outro adaptador LoRA. Por que você faria isso? Há um motivo: se você deseja reduzir o rank do adaptador LoRA. Se, após o treinamento, você quiser reduzir o tamanho do adaptador LoRA, use save_as_lora() ou convert_to_lora() e passe um rank menor. Isso resultará em um novo adaptador LoRA com menor consumo de memória e armazenamento.

Métricas

Conversão de não-LoRA para LoRA

É claro, converter um adaptador PEFT em outro adaptador é um processo com perda de informação. O novo adaptador provavelmente não terá o mesmo desempenho do adaptador inicial. Portanto, é altamente recomendável avaliar o adaptador LoRA convertido. Dessa forma, você pode ter certeza de que o adaptador convertido tem desempenho suficiente para o seu caso de uso. A regra geral é que, quanto maior o rank do adaptador LoRA, melhor ele aproximará o seu adaptador inicial. Isso significa que o adaptador LoRA convertido pode exigir mais parâmetros do que o adaptador original para alcançar um desempenho semelhante.

Para dar um exemplo, aqui estão alguns números derivados no benchmark PEFT MetaMathQA. Para isso, um adaptador LoHa foi usado para fazer o fine-tuning de meta-llama/Llama-3.2-3B no MetaMathQA e avaliado no GSM8K. O adaptador LoKr inicial tinha rank 32, resultando em 18.350.080 parâmetros treináveis e uma precisão de teste de 41,85%. A avaliação exigiu 12,25 GB de memória. O checkpoint foi convertido para LoRA com diferentes valores para o rank. O resultado obtido é:

rankparâmetros treináveisprecisão de teste (%)mudança de precisãomemória reservada (máx., GB)aumento de memória
8229376037.60-4.2512.410.16
16458752038.89-2.9612.15-0.10
32917504040.11-1.7412.410.16
641835008039.20-2.6512.18-0.07
0.4242892837.60-4.2512.410.16
0.5476160040.18-1.6712.410.16
0.6885760039.42-2.4312.410.16
0.71623040039.04-2.8112.15-0.10

Como você pode ver, é possível alcançar uma precisão de teste próxima à do adaptador LoHa original, desde que o rank seja suficientemente alto. Escolher o rank adequado é um equilíbrio entre o desempenho do modelo e a eficiência do modelo. Para reproduzir esse experimento, siga o script em https://github.com/huggingface/peft/tree/main/scripts/evaluate-lora-conversion.py.

Observe que o número de parâmetros treináveis não pode ser traduzido de forma direta para o uso de memória. Alguns métodos PEFT exigem mais memória, outros menos, mesmo com o mesmo número de parâmetros treináveis. Portanto, mesmo que, após a conversão, o adaptador LoRA tenha mais parâmetros que o original, ele ainda pode ser mais eficiente em termos de memória durante o serviço.

Conversão de LoRA para LoRA

De forma semelhante ao experimento acima, também podemos avaliar a conversão de LoRA para LoRA (ou seja, compressão de LoRA). Aqui, partimos de um adaptador LoRA de rank 64 treinado no mesmo setup acima com RS-LoRA. O adaptador inicial possui 18.350.080 parâmetros treináveis, uma precisão de teste de 52,92% e requer 12,58 GB de memória para avaliação. A tabela a seguir mostra os resultados da conversão deste adaptador para adaptadores LoRA de rank menor:

rankparâmetros treináveisprecisão de teste (%)mudança de precisãomemória reservada (máx., GB)aumento de memória
8229376043.37-9.5512.38-0.20
16458752048.90-4.0212.38-0.20
32917504051.48-1.4412.49-0.09
481376256052.01-0.9112.38-0.20
0.5215040044.12-8.8012.37-0.21
0.6308224047.54-5.3812.37-0.21
0.7444825650.49-2.4312.37-0.21
0.8651059250.11-2.8112.37-0.21
0.91002291251.55-1.3712.38-0.20
0.951297612852.62-0.3012.39-0.19

Por exemplo, para rank 0.95, podemos reduzir a diferença de acurácia para apenas 0,3 pontos percentuais, ao mesmo tempo em que reduzimos o número de parâmetros em 30%. Observe também que esses LoRAs comprimidos podem ser melhores do que treiná-los diretamente no rank inferior — por exemplo, para rank 32, o treinamento direto resulta em uma acurácia de teste de 48,22%, enquanto a conversão a partir do rank 64 resulta em 51,48%.

Observações

Existem algumas limitações na conversão do LoRA. Conforme mencionado acima, é esperado um decréscimo no desempenho e o LoRA convertido provavelmente será menos eficiente em parâmetros do que o adaptador original. Além disso, a conversão do LoRA possui as seguintes limitações:

  • No momento, apenas adaptadores aplicados a camadas lineares podem ser convertidos.
  • Nem todos os métodos de PEFT atualmente suportam a conversão para LoRA.

Se houver muita demanda para estender a conversão de LoRA, por favor, nos avise criando uma discussão no GitHub e faremos com que funcione com mais tipos de camadas e métodos PEFT.

API

Converte um modelo não-LoRA em um modelo LoRA, retorna o LoraConfig e o state_dict

peft.convert_to_lora

< >

( model: Modulerank: floatadapter_name: str = 'default'progressbar: bool = Falsecompile_kwargs = None )

Parâmetros

  • model — O modelo a ser convertido. Deve ser um modelo que possua camadas PEFT que suportem conversão.
  • rank (int ou float) — O rank desejado para o adaptador LoRA retornado. Um rank mais alto resulta em um adaptador LoRA que espelha o adaptador original com mais precisão. No entanto, isso também exigirá mais memória, computação e espaço em disco. Portanto, escolha um valor que represente o melhor equilíbrio para o seu caso de uso e valide o adaptador final. Se um float for passado, ele é interpretado como um limiar de variância explicada / energia: escolhemos o menor rank k tal que os k primeiros valores singulares representem pelo menos essa fração dos valores singulares quadrados totais. Isso resulta efetivamente em ranks menores sendo atribuídos se alguns valores singulares conseguem capturar a adaptação desta camada. Um float menor significa que o rank é menor e vice-versa. Esteja ciente de que ranks dinâmicos podem levar a ranks muito desiguais por camada, o que significa que algumas camadas podem exigir uma quantidade desproporcionalmente alta de memória para ativações. Escolher um rank fixo (int) é melhor para alcançar um requisito de memória previsível.
  • adapter_name (str, opcional) — O nome do adaptador a ser convertido. Apenas um adaptador pode ser convertido por vez. O valor padrão é "default".
  • progressbar (bool) — se deve exibir uma barra de progresso indicando o andamento da conversão (pode levar alguns minutos para modelos grandes).
  • compile_kwargs (dict, opcional) — Se fornecido, compila a função para converter módulos individuais em LoRA, passando os kwargs especificados para torch.compile. Isso pode potencialmente acelerar a conversão em modelos grandes.

Converta um modelo não-LoRA com camadas PEFT para um checkpoint LoRA.

Isso é suportado apenas para alguns métodos específicos de PEFT que permitem uma conversão equivalente. Essencialmente, isso se resume a métodos de PEFT para os quais podemos calcular o delta aditivo de peso W’ - W, seja diretamente (métodos aditivos como LoKr) ou construindo primeiro o peso efetivo W’ (métodos multiplicativos como OFT). Além disso, no momento, apenas camadas lineares são suportadas.

O adaptador LoRA tentará aproximar o adaptador inicial o mais próximo possível. Quanto maior o rank, melhor será a aproximação. Espera-se que a aproximação nunca alcance o desempenho total do adaptador original e que a eficiência de parâmetros do adaptador LoRA seja menor que a do adaptador original (ou seja, para um desempenho semelhante, será necessário mais parâmetros). A conversão ainda pode ser útil em muitas situações:

  • No PEFT, o LoRA suporta mais recursos do que a maioria dos outros métodos, por exemplo, lotes de adaptadores mistos. Assim, o adaptador convertido pode ser usado com esses recursos.
  • Alguns pacotes downstream suportam adaptadores LoRA, mas não outros métodos PEFT, por exemplo, Diffusers. A conversão permite usar um adaptador não-LoRA com esses pacotes.

O fator de escala do LoRA já está incorporado nos pesos do LoRA, portanto a escala sempre será um (ou seja, o rank e o alpha são escolhidos para serem idênticos).

Observação: Esta função não suporta modelos fragmentados (ainda).

Raises TypeError: Se o modelo fornecido não possui nenhuma camada que possa ser convertida para LoRA, um TypeError é lançado. ValueError: Se um rank inválido foi escolhido (muito alto ou muito baixo), ou se os adaptadores estão atualmente mesclados nos pesos base (caso em que eles devem ser desmesclados primeiro).

Convert um modelo não-LoRA em um modelo LoRA, salve o checkpoint do adaptador e a configuração no caminho fornecido

peft.save_as_lora

< >

( path: str | os.PathLikemodel: Modulerank: floatadapter_name: str = 'default'progressbar: bool = Falsecompile_kwargs = None )

Parâmetros

  • model — O modelo a ser convertido. Deve ser um modelo que possua camadas PEFT que suportem conversão.
  • rank (int ou float) — O rank desejado para o adaptador LoRA retornado. Um rank mais alto resulta em um adaptador LoRA que espelha o adaptador original com mais precisão. No entanto, isso também exigirá mais memória, computação e espaço em disco. Portanto, escolha um valor que represente o melhor equilíbrio para o seu caso de uso e valide o adaptador final. Se um float for passado, ele é interpretado como um limiar de variância explicada / energia: escolhemos o menor rank k tal que os k primeiros valores singulares representem pelo menos essa fração dos valores singulares quadrados totais. Isso resulta efetivamente em ranks menores sendo atribuídos se alguns valores singulares conseguem capturar a adaptação desta camada. Um float menor significa que o rank é menor e vice-versa. Esteja ciente de que ranks dinâmicos podem levar a ranks muito desiguais por camada, o que significa que algumas camadas podem exigir uma quantidade desproporcionalmente alta de memória para ativações. Escolher um rank fixo (int) é melhor para alcançar um requisito de memória previsível.
  • adapter_name (str, opcional) — O nome do adaptador a ser convertido. Apenas um adaptador pode ser convertido por vez. O valor padrão é "default".
  • progressbar (bool) — se deve exibir uma barra de progresso indicando o andamento da conversão (pode levar alguns minutos para modelos grandes).
  • compile_kwargs (dict, opcional) — Se fornecido, compila a função para converter módulos individuais em LoRA, passando os kwargs especificados para torch.compile. Isso pode potencialmente acelerar a conversão em modelos grandes.

Converta um modelo não-LoRA com camadas PEFT para LoRA, em seguida salve o arquivo de checkpoint e a configuração PEFT.

Isso é suportado apenas para alguns métodos específicos de PEFT que permitem uma conversão equivalente. Essencialmente, isso se resume a métodos de PEFT para os quais podemos calcular o delta aditivo de peso W’ - W, seja diretamente (métodos aditivos como LoKr) ou construindo primeiro o peso efetivo W’ (métodos multiplicativos como OFT). Além disso, no momento, apenas camadas lineares são suportadas.

O adaptador LoRA tentará aproximar o adaptador inicial o mais próximo possível. Quanto maior o rank, melhor será a aproximação. Espera-se que a aproximação nunca alcance o desempenho total do adaptador original e que a eficiência de parâmetros do adaptador LoRA seja menor que a do adaptador original (ou seja, para um desempenho semelhante, será necessário mais parâmetros). A conversão ainda pode ser útil em muitas situações:

  • No PEFT, o LoRA suporta mais recursos do que a maioria dos outros métodos, por exemplo, lotes de adaptadores mistos. Assim, o adaptador convertido pode ser usado com esses recursos.
  • Alguns pacotes downstream suportam adaptadores LoRA, mas não outros métodos PEFT, por exemplo, Diffusers. A conversão permite usar um adaptador não-LoRA com esses pacotes.

O fator de escala do LoRA já está incorporado nos pesos do LoRA, portanto a escala sempre será um (ou seja, o rank e o alpha são escolhidos para serem idênticos).

Você pode carregar o peso LoRA convertido da seguinte forma:

>>> lora_path = ...
>>> save_as_lora(lora_path, model, rank=...)
>>> base_model = AutoModel.from_pretrained(...)
>>> lora_model = PeftModel.from_pretrained(base_model, lora_path)

Observação: Esta função não suporta modelos fragmentados (ainda).

Raises TypeError: Se o modelo fornecido não possui nenhuma camada que possa ser convertida para LoRA, um TypeError é lançado. ValueError: Se um rank inválido foi escolhido (muito alto ou muito baixo), ou se os adaptadores estão atualmente mesclados nos pesos base (caso em que eles devem ser desmesclados primeiro).

Update on GitHub