> ## 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 con adaptadores

# LoRA & PEFT

El Fine-Tuning Eficiente en Parámetros te permite entrenar modelos grandes con menos memoria.

## ¿Qué es LoRA?

LoRA (Low-Rank Adaptation) añade pequeñas matrices entrenables al modelo mientras mantiene los pesos base congelados. Esto reduce drásticamente el uso de memoria y el tiempo de entrenamiento.

## Inicio 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        | Descripción                   | Por Defecto  |
| ---------------- | ----------------------------- | ------------ |
| `peft`           | Habilitar LoRA                | `False`      |
| `lora_r`         | Rango (tamaño de adaptadores) | `16`         |
| `lora_alpha`     | Factor de escala              | `32`         |
| `lora_dropout`   | Tasa de dropout               | `0.05`       |
| `target_modules` | Módulos a adaptar             | `all-linear` |

### Rango (lora\_r)

Rango mayor = más parámetros = más capacidad:

| Rango | Caso de Uso                              |
| ----- | ---------------------------------------- |
| 8     | Tareas simples, muy limitado en memoria  |
| 16    | Estándar (recomendado)                   |
| 32-64 | Tareas complejas, más memoria disponible |
| 128+  | Capacidad cercana a fine-tuning completo |

### Alpha

La razón alpha/rango afecta el aprendizaje:

```python theme={null}
# Escalado estándar
lora_r=16
lora_alpha=32  # alpha/r = 2

# Más agresivo
lora_r=16
lora_alpha=64  # alpha/r = 4

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

### Módulos Objetivo

Por defecto, LoRA apunta a todas las capas lineales (`all-linear`). Puedes 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"
```

## Con Cuantización

Combina LoRA con cuantización para máximo ahorro de memoria:

```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"
)
```

## Comparación de Memoria

| 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       |

## Fusionando Adaptadores

Por defecto, los adaptadores LoRA se **fusionan automáticamente** en el modelo base después del entrenamiento. Esto simplifica la inferencia - obtienes un único archivo de modelo listo para usar.

### Comportamiento Por Defecto (Fusionado)

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

### Guardar Solo Adaptadores

Para guardar solo los archivos de adaptador (más pequeños, pero requiere modelo base para inferencia):

```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
```

### Fusionar Manualmente Después

```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>
  Debes especificar `--output-folder` para guardar localmente o `--push-to-hub` para subir a Hugging Face Hub.
</Note>

#### Parámetros de la Herramienta de Fusión

| Parámetro              | Descripción                           | Requerido    |
| ---------------------- | ------------------------------------- | ------------ |
| `--base-model-path`    | Modelo base para fusionar adaptador   | Sí           |
| `--adapter-path`       | Ruta al adaptador LoRA                | Sí           |
| `--output-folder`      | Directorio de salida local            | Uno de estos |
| `--push-to-hub`        | Subir a Hugging Face Hub              | requerido    |
| `--token`              | Token Hugging Face (para push al hub) | No           |
| `--pad-to-multiple-of` | Rellenar tamaño del vocabulario       | No           |

O en 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")
```

### Convertir a Formato Kohya

Convierte adaptadores LoRA a formato `.safetensors` compatible con Kohya:

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

## Cargando Adaptadores

Usa adaptadores sin fusionar:

```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)
```

## Mejores Prácticas

### Entrenamiento

* Usa tasa de aprendizaje mayor (2e-4 a 1e-3)
* LoRA se beneficia de entrenamiento más largo
* Considera apuntar a todas las capas lineales para tareas complejas

### Memoria

* Comienza con `lora_r=16`
* Añade cuantización si es necesario
* Usa gradient checkpointing (activado por defecto)

### Calidad

* Rango mayor generalmente = mejor calidad
* Prueba en tu tarea específica
* Compara con fine-tuning completo si la memoria lo permite

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Quantization" href="/advanced/quantization">
    Reducción adicional de memoria
  </Card>

  <Card title="DPO Training" href="/advanced/dpo-training">
    Optimización de preferencias
  </Card>
</CardGroup>