# LoRA Sem Arrependimento

Pesquisas recentes da equipe do [Thinking Machines Lab](https://thinkingmachines.ai/blog/lora/) (Schulman et al., 2025) mostram que **o LoRA pode alcançar o mesmo desempenho do fine-tuning completo** quando configurado corretamente, utilizando apenas ~67% do poder de computação. Esses achados são empolgantes para os usuários do TRL, pois são fáceis de implementar e podem melhorar o desempenho do modelo com orçamentos menores.

Este guia fornece instruções simples para reproduzir os resultados do post no blog no TRL.

> [!TIP]
> É recomendável ler o post no blog antes de seguir este guia, ou consultar ambos os recursos em paralelo para obter os melhores resultados.

## Vantagens do LoRA em relação ao ajuste fino completo

Primeiramente, vamos relembrar os benefícios do [LoRA em relação ao fine-tuning completo](https://huggingface.co/docs/trl/en/peft_integration).

LoRA adiciona camadas de adaptador sobre o modelo base, que contém significativamente menos parâmetros do que o próprio modelo base. Esse design reduz os requisitos de memória de GPU e permite um treinamento mais eficiente. Conforme descrito no [blog](https://thinkingmachines.ai/blog/lora/), acreditava-se originalmente que essa abordagem envolvia um compromisso de desempenho, embora uma configuração cuidadosa possa superar esse compromisso e igualar o desempenho do ajuste fino completo.

## Exemplos com TRL

Vamos implementar e treinar adaptadores LoRA em scripts do TRL com base nas principais conclusões do post no blog. Em seguida, revisitaremos cada conclusão à luz dos resultados do TRL.

### Ajuste Fino Supervisionado (SFT)

O post do blog executa SFT em uma variedade de modelos e conjuntos de dados do Hub, que podemos reproduzir no TRL.

| Model | Conjunto de dados |
| --- | --- |
| [Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B) | [allenai/tulu-3-sft-mixture](https://huggingface.co/datasets/allenai/tulu-3-sft-mixture) |
| [Llama-3.2-1B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-1B) | [open-thoughts/OpenThoughts-114k](https://huggingface.co/datasets/open-thoughts/OpenThoughts-114k) |
| [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Llama-3.1-8B) | [allenai/tulu-3-sft-mixture](https://huggingface.co/datasets/allenai/tulu-3-sft-mixture) |
| [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Llama-3.1-8B) | [open-thoughts/OpenThoughts-114k](https://huggingface.co/datasets/open-thoughts/OpenThoughts-114k) |

Podemos integrar essas descobertas com a API Python do TRL da seguinte forma:

```python

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig

dataset = load_dataset("open-thoughts/OpenThoughts-114k", split="train")

peft_config = LoraConfig(r=256, lora_alpha=16, target_modules="all-linear")

training_args = SFTConfig(
    learning_rate=2e-4,
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    num_train_epochs=1,
    report_to=["trackio"],
)

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-3B-Instruct",
    train_dataset=dataset,
    peft_config=peft_config,
    args=training_args,
)

trainer.train()

```

```bash

hf jobs uv run \
    --flavor a100-large \
    --timeout 8h \
    --secrets HF_TOKEN \
    "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
    --model_name_or_path Qwen/Qwen2.5-3B-Instruct \
    --dataset_name open-thoughts/OpenThoughts-114k \
    --learning_rate 2.0e-5 \
    --num_train_epochs 1 \
    --packing \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 16 \
    --use_peft \
    --lora_r 256 \
    --lora_alpha 16 \
    --lora_target_modules all-linear \
    --output_dir Qwen2.5-3B-OpenThoughts-LoRA \
    --report_to trackio \
    --push_to_hub

```

Para usar o Hugging Face Jobs, faça login no Hub (`hf auth login`) e tenha um [saldo de créditos](https://huggingface.co/settings/billing) positivo. Consulte a [documentação do Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) para mais detalhes.

```bash

uv run "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
    --model_name_or_path Qwen/Qwen2.5-3B-Instruct \
    --dataset_name open-thoughts/OpenThoughts-114k \
    --learning_rate 2.0e-5 \
    --num_train_epochs 1 \
    --packing \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 16 \
    --eval_strategy no \
    --use_peft \
    --lora_r 256 \
    --lora_alpha 16 \
    --lora_target_modules all-linear \
    --output_dir Qwen2.5-3B-OpenThoughts-LoRA \
    --report_to trackio \
    --push_to_hub

```

Para executar o script localmente, você precisará ter o `uv` instalado. Consulte a [documentação do uv](https://docs.astral.sh/uv/) para mais detalhes.

Quando o treinamento começa, você pode monitorar o progresso no [Trackio](https://huggingface.co/trackio), que registrará a URL.

### Aprendizado por Reforço (GRPO)

O post do blog executa GRPO em uma variedade de modelos e conjuntos de dados do Hub, e, mais uma vez, podemos reproduzir os resultados no TRL.

| Model | Conjunto de dados |
| --- | --- |
| [Llama-3.1-8B-Base](https://huggingface.co/meta-llama/Llama-3.2-1B) | [GSM8k](https://huggingface.co/datasets/openai/gsm8k) |
| [Llama-3.1-8B-Base](https://huggingface.co/meta-llama/Llama-3.2-1B) | [DeepMath-103K](https://huggingface.co/datasets/zwhe99/DeepMath-103K) |
| [Qwen3-8b-base](https://huggingface.co/Qwen/Qwen3-8b-base) | [DeepMath-103K](https://huggingface.co/datasets/zwhe99/DeepMath-103K) |

Para o aprendizado por reforço, o blog utiliza uma tarefa de raciocínio matemático que podemos reproduzir como uma função em Python.

Podemos implementar essas recomendações com a API Python do TRL da seguinte forma:

```python

from datasets import load_dataset
from peft import LoraConfig
from trl import GRPOConfig, GRPOTrainer
from trl.rewards import reasoning_accuracy_reward

dataset = load_dataset("HuggingFaceH4/OpenR1-Math-220k-default-verified", split="train")

peft_config = LoraConfig(
    r=1,
    lora_alpha=32,
    target_modules="all-linear"
)

training_args = GRPOConfig(
    learning_rate=5e-5,
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    num_train_epochs=1,
    num_generations=8,
    generation_batch_size=8,
    report_to=["trackio"],
)

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    reward_funcs=reasoning_accuracy_reward,
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,
)

trainer.train()

```

> [!WARNING]
> Este trecho omite a função de recompensa, definida acima, para manter o exemplo conciso.

```bash

hf jobs uv run \
    --flavor a100-large \
    --timeout 4h \
    --secrets HF_TOKEN \
    --env PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True \
    "https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
    --model_name_or_path Qwen/Qwen3-0.6B \
    --dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
    --output_dir grpo-full-qwen3-0.6b \
    --learning_rate 1.0e-6 \
    --lr_scheduler_type cosine \
    --warmup_steps 0.0 \
    --max_grad_norm 1.0 \
    --beta 0.0 \
    --max_completion_length 4096 \
    --num_generations 16 \
    --generation_batch_size 16 \
    --gradient_accumulation_steps 8 \
    --per_device_train_batch_size 1 \
    --num_train_epochs 1 \
    --lora_r 1 \
    --lora_alpha 32 \
    --lora_dropout 0.0 \
    --lora_target_modules all-linear \
    --vllm_mode colocate \
    --save_strategy steps \
    --save_steps 50 \
    --save_total_limit 1 \
    --logging_steps 1 \
    --max_steps 200 \
    --report_to trackio
```

Para usar o Hugging Face Jobs, faça login no Hub (`hf auth login`) e tenha um [saldo de créditos](https://huggingface.co/settings/billing) positivo. Consulte a [documentação do Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) para mais detalhes.

```bash
uv run "https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
    --model_name_or_path Qwen/Qwen3-0.6B \
    --dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
    --output_dir grpo-full-qwen3-0.6b \
    --learning_rate 1.0e-6 \
    --lr_scheduler_type cosine \
    --warmup_steps 0.0 \
    --max_grad_norm 1.0 \
    --beta 0.0 \
    --max_completion_length 4096 \
    --num_generations 16 \
    --generation_batch_size 16 \
    --gradient_accumulation_steps 8 \
    --per_device_train_batch_size 1 \
    --num_train_epochs 1 \
    --lora_r 1 \
    --lora_alpha 32 \
    --lora_dropout 0.0 \
    --lora_target_modules all-linear \
    --vllm_mode colocate \
    --save_strategy steps \
    --save_steps 50 \
    --save_total_limit 1 \
    --logging_steps 1 \
    --max_steps 200 \
    --report_to trackio
```

Para executar o script localmente, você precisará ter o `uv` instalado. Consulte a [documentação do uv](https://docs.astral.sh/uv/) para mais detalhes.

O script de aprendizado por reforço com GRPO é implementado como um script personalizado no TRL, que utiliza a função de recompensa mostrada acima. Você pode consultá-lo em [`grpo.py`](https://huggingface.co/datasets/burtenshaw/lora-without-regrets/blob/main/grpo.py) - Boas práticas de aprendizado por reforço com LoRA

## Principais descobertas na otimização do LoRA

Os autores recomendam aplicar LoRA a todas as matrizes de pesos, em vez de limitá-lo às camadas de atenção, pois aumentar o rank não compensa essa restrição. No TRL, isso pode ser configurado usando `--lora_target_modules all-linear` para aplicar LoRA a todas as matrizes de pesos.

Conseguimos reproduzir os resultados do post no blog usando o TRL e o modelo SmolLM3. Treinamos o modelo por 500 passos no [conjunto de dados Math 220k](https://huggingface.co/datasets/HuggingFaceH4/OpenR1-Math-220k-default-verified) com a função de recompensa e a configuração acima. Como você pode ver na figura abaixo, a curva média de recompensa de treinamento do modelo LoRA corresponde à curva de ajuste fino completo.

![train reward](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/5.png)

E, o mais importante, o modelo LoRA usa significativamente menos memória do que o modelo de ajuste fino completo, como podemos ver na figura abaixo.

![memory usage](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/6.png)

Aqui estão os parâmetros que usamos para treinar os modelos acima

| Parâmetro | LoRA | FT completo |
| --- | --- | --- |
| `--model_name_or_path` | HuggingFaceTB/SmolLM3-3B | HuggingFaceTB/SmolLM3-3B |
| `--dataset_name` | HuggingFaceH4/OpenR1-Math-220k-default-verified | HuggingFaceH4/OpenR1-Math-220k-default-verified |
| `--learning_rate` | 1.0e-5 | 1.0e-6 |
| `--max_completion_length` | 4096 | 4096 |
| `--lora_r` | 1 | - |
| `--lora_alpha` | 32 | - |
| `--lora_dropout` | 0.0 | - |
| `--lora_target_modules` | all-linear | - |

Vamos detalhar as principais conclusões do post no blog e como conseguimos reproduzi-las.

### 1. *O LoRA apresenta melhor desempenho quando aplicado a todas as matrizes de pesos*

Os autores recomendam aplicar o LoRA a todas as matrizes de pesos, em vez de limitá-lo às camadas de atenção, pois aumentar o rank não compensa essa restrição.

![all layers](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/1.png)

LoRA apenas em camadas de atenção apresenta desempenho inferior mesmo ao usar um rank maior para igualar a contagem de parâmetros. No TRL, isso pode ser configurado usando `--lora_target_modules all-linear` para aplicar LoRA a todas as matrizes de pesos. Em Python, podemos fazer isso da seguinte forma:

```python
from peft import LoraConfig  

peft_config = LoraConfig(target_modules="all-linear")  
```

### 2. *O adaptador precisa de capacidade suficiente para aprender com o conjunto de dados*

O post no blog recomenda o uso de um rank de LoRA suficiente para aprender a partir do conjunto de dados. O rank determina o número de parâmetros treináveis no adaptador LoRA. Portanto, "Para conjuntos de dados que excedem a capacidade do LoRA, o LoRA tem desempenho inferior ao FullFT".

![learning rate](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/3.png)

No script do TRL, podemos usar `--lora_r` para definir o rank e ajustá-lo com base na tarefa e no conjunto de dados em que estamos treinando. O post no blog recomenda os seguintes ranks com base na tarefa e no tamanho do conjunto de dados:

Tarefas de aprendizado por reforço geralmente exigem menor capacidade, portanto, é possível usar ranks de LoRA menores. Isso ocorre porque os algoritmos de gradiente de política extraem aproximadamente ~1 bit de informação por episódio, exigindo uma capacidade de parâmetros mínima.

O post no blog define o tamanho ideal do conjunto de dados para o LoRA, para corresponder ao fine-tuning completo, como "Post-training scale". O que podemos usar para determinar o rank recomendado para LoRAs de SFT e RL como:

| Tipo de Tarefa | Tamanho do Conjunto de Dados | Rank Recomendado |
| --- | --- | --- |
| **SFT** | Escala de pós-treino | 256 |
| **RL** | Qualquer tamanho | 1-32 |

### 3. *"FullFT e LoRAs de alta ordem têm curvas de aprendizado semelhantes"*

Contraintuitivamente, o post do blog recomenda usar uma taxa de aprendizado maior do que a utilizada no fine-tuning completo. Na tabela acima, usamos 1.0e-5 para LoRA e 1.0e-6 para fine-tuning completo. No script do TRL, podemos usar `--learning_rate` para definir a taxa de aprendizado. A escala \\( \frac{1}{r} \\) no LoRA torna a taxa de aprendizado ótima aproximadamente independente do rank.

![learning rate](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/2.png)

### 4. *"Em alguns cenários, o LoRA é menos tolerante a tamanhos de lote grandes do que o fine-tuning completo."*

O post no blog recomenda o uso de um tamanho de lote efetivo < 32, pois os autores constataram que o LoRA é menos tolerante a tamanhos de lote grandes. Isso não pôde ser mitigado aumentando o rank do LoRA. No script do TRL, podemos usar `--per_device_train_batch_size` e `--gradient_accumulation_steps` para definir o tamanho do lote.

![learning rate](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lora_without_regret/4.png)

## Principais pontos

Usando o TRL, você pode implementar adaptadores LoRA de forma eficiente para corresponder ao desempenho do fine-tuning completo, aplicando os principais insights (direcionar todas as matrizes de pesos, escolher o rank adequado e gerenciar o tamanho do lote e a taxa de aprendizado) sem o alto custo computacional do FullFT.

## Citação

```bibtex
@article{schulman2025lora,  
    title        = {{LoRA Without Regret}},  
    author       = {John Schulman and Thinking Machines Lab},  
    year         = 2025,  
    journal      = {Thinking Machines Lab: Connectionism},  
    doi          = {10.64434/tml.20250929},  
    note         = {https://thinkingmachines.ai/blog/lora/}  
}  
```

