> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LoRA & PEFT

> Fine-tuning eficiente com adaptadores

# LoRA & PEFT

O Fine-Tuning Eficiente em Parâmetros permite treinar modelos grandes com menos memória.

## O que é LoRA?

LoRA (Low-Rank Adaptation) adiciona pequenas matrizes treináveis ao modelo enquanto mantém os pesos base congelados. Isso reduz drasticamente o uso de memória e o tempo de treinamento.

## Início Rápido

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./data.jsonl \
  --project-name lora-model \
  --peft \
  --lora-r 16 \
  --lora-alpha 32
```

## Python API

```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams
from autotrain.project import AutoTrainProject

params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-1B",
    data_path="./data.jsonl",
    project_name="lora-model",

    trainer="sft",

    # LoRA configuration
    peft=True,
    lora_r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules="all-linear",  # Default: all-linear

    epochs=3,
    batch_size=4,
    lr=2e-4,  # Higher LR works with LoRA
)

project = AutoTrainProject(params=params, backend="local", process=True)
project.create()
```

## Parâmetros

| Parâmetro        | Descrição                      | Padrão       |
| ---------------- | ------------------------------ | ------------ |
| `peft`           | Habilitar LoRA                 | `False`      |
| `lora_r`         | Rank (tamanho dos adaptadores) | `16`         |
| `lora_alpha`     | Fator de escala                | `32`         |
| `lora_dropout`   | Taxa de dropout                | `0.05`       |
| `target_modules` | Módulos para adaptar           | `all-linear` |

### Rank (lora\_r)

Rank maior = mais parâmetros = mais capacidade:

| Rank  | Caso de Uso                                |
| ----- | ------------------------------------------ |
| 8     | Tarefas simples, muito limitado em memória |
| 16    | Padrão (recomendado)                       |
| 32-64 | Tarefas complexas, mais memória disponível |
| 128+  | Capacidade próxima ao fine-tuning completo |

### Alpha

A razão alpha/rank afeta o aprendizado:

```python theme={null}
# Scaling padrão
lora_r=16
lora_alpha=32  # alpha/r = 2

# Mais agressivo
lora_r=16
lora_alpha=64  # alpha/r = 4

# Conservador
lora_r=16
lora_alpha=16  # alpha/r = 1
```

### Módulos Alvo

Por padrão, LoRA direciona todas as camadas lineares (`all-linear`). Você pode personalizar:

```python theme={null}
# All linear layers (default)
target_modules="all-linear"

# Attention layers only
target_modules="q_proj,k_proj,v_proj,o_proj"

# Include MLP
target_modules="q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj"
```

## Com Quantização

Combine LoRA com quantização para máxima economia de memória:

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-8B \
  --data-path ./data.jsonl \
  --project-name quantized-lora \
  --peft \
  --quantization int4
```

```python theme={null}
params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-8B",
    data_path="./data.jsonl",
    project_name="quantized-lora",

    peft=True,
    lora_r=16,
    quantization="int4",  # or "int8"
)
```

## Comparação de Memória

| Modelo | Fine-tune Completo | LoRA  | LoRA + 4bit |
| ------ | ------------------ | ----- | ----------- |
| 1B     | 8 GB               | 4 GB  | 3 GB        |
| 7B     | 56 GB              | 16 GB | 8 GB        |
| 13B    | 104 GB             | 32 GB | 16 GB       |

## Mesclando Adaptadores

Por padrão, os adaptadores LoRA são **automaticamente mesclados** no modelo base após o treinamento. Isso simplifica a inferência - você obtém um único arquivo de modelo pronto para usar.

### Comportamento Padrão (Mesclado)

```python theme={null}
params = LLMTrainingParams(
    ...
    peft=True,
    # merge_adapter=True is the default
)
```

### Salvar Apenas Adaptadores

Para salvar apenas os arquivos de adaptador (menores, mas requer modelo base para inferência):

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./data.jsonl \
  --project-name lora-model \
  --peft \
  --no-merge-adapter
```

### Mesclar Manualmente Depois

```bash theme={null}
aitraining tools merge-llm-adapter \
  --base-model-path meta-llama/Llama-3.2-1B \
  --adapter-path ./lora-model \
  --output-folder ./merged-model
```

<Note>
  Você deve especificar `--output-folder` para salvar localmente ou `--push-to-hub` para fazer upload para o Hugging Face Hub.
</Note>

#### Parâmetros da Ferramenta de Mesclagem

| Parâmetro              | Descrição                             | Obrigatório |
| ---------------------- | ------------------------------------- | ----------- |
| `--base-model-path`    | Modelo base para mesclar adaptador    | Sim         |
| `--adapter-path`       | Caminho para adaptador LoRA           | Sim         |
| `--output-folder`      | Diretório de saída local              | Um destes   |
| `--push-to-hub`        | Enviar para Hugging Face Hub          | obrigatório |
| `--token`              | Token Hugging Face (para push no hub) | Não         |
| `--pad-to-multiple-of` | Preencher tamanho do vocabulário      | Não         |

Ou em Python:

```python theme={null}
from peft import PeftModel
from transformers import AutoModelForCausalLM

# Load base model
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")

# Load and merge adapter
model = PeftModel.from_pretrained(model, "./lora-model")
model = model.merge_and_unload()

# Save merged model
model.save_pretrained("./merged-model")
```

### Converter para Formato Kohya

Converta adaptadores LoRA para formato `.safetensors` compatível com Kohya:

```bash theme={null}
aitraining tools convert_to_kohya \
  --adapter-path ./lora-model \
  --output-path ./kohya-lora.safetensors
```

## Carregando Adaptadores

Use adaptadores sem mesclar:

```python theme={null}
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

# Load base model
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")

# Load adapter
model = PeftModel.from_pretrained(model, "./lora-model")

# Use for inference
inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
```

## Melhores Práticas

### Treinamento

* Use taxa de aprendizado maior (2e-4 a 1e-3)
* LoRA se beneficia de treinamento mais longo
* Considere direcionar todas as camadas lineares para tarefas complexas

### Memória

* Comece com `lora_r=16`
* Adicione quantização se necessário
* Use gradient checkpointing (ativado por padrão)

### Qualidade

* Rank maior geralmente = melhor qualidade
* Teste em sua tarefa específica
* Compare com fine-tuning completo se memória permitir

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Quantization" href="/advanced/quantization">
    Redução adicional de memória
  </Card>

  <Card title="DPO Training" href="/advanced/dpo-training">
    Otimização de preferências
  </Card>
</CardGroup>