# LLaMA-Factory

LLaMA-Factory es el marco de ajuste fino de código abierto más completo, que admite más de 100 modelos de lenguaje, incluidas todas las variantes de LLaMA, Qwen, Mistral, Phi, Falcon, ChatGLM y más. Ofrece LoRA, QLoRA, ajuste fino completo, RLHF, DPO y PPO, todo a través de una interfaz web intuitiva (LLaMA Board) o CLI. Los servidores GPU bajo demanda de CLORE.AI lo convierten en la plataforma perfecta para lanzar trabajos de ajuste fino a una fracción del costo de los proveedores en la nube.

{% hint style="success" %}
Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Requisitos del servidor

| Parámetro | Mínimo           | Recomendado    |
| --------- | ---------------- | -------------- |
| RAM       | 16 GB            | 32 GB+         |
| VRAM      | 8 GB (QLoRA)     | 24 GB+         |
| Disco     | 50 GB            | 200 GB+        |
| GPU       | NVIDIA RTX 2080+ | A100, RTX 4090 |

{% hint style="info" %}
**El método de entrenamiento determina los requisitos de GPU:**

* **QLoRA (4 bits)**: 8 GB de VRAM para modelos 7B, 16 GB para 13B
* **LoRA (float16)**: 16 GB de VRAM para modelos 7B, 40 GB para 13B
* **Ajuste fino completo**: \~14 GB de VRAM por cada 7B parámetros (+ estados del optimizador)
* Multi-GPU (DeepSpeed/FSDP) escala a través de cualquier número de GPUs
  {% endhint %}

## Despliegue rápido en CLORE.AI

**Imagen Docker:** `hiyouga/llamafactory:latest`

**Puertos:** `22/tcp`, `7860/http`

**Variables de entorno:**

| Variable               | Ejemplo     | Descripción                                       |
| ---------------------- | ----------- | ------------------------------------------------- |
| `HF_TOKEN`             | `hf_xxx...` | Token de HuggingFace para modelos restringidos    |
| `WANDB_API_KEY`        | `xxx...`    | Weights & Biases para seguimiento de experimentos |
| `CUDA_VISIBLE_DEVICES` | `0,1`       | GPUs a usar                                       |

## Configuración paso a paso

### 1. Alquila un servidor GPU en CLORE.AI

Visita [CLORE.AI Marketplace](https://clore.ai/marketplace) y seleccione según su tarea:

| Tarea          | VRAM  | GPU recomendada    |
| -------------- | ----- | ------------------ |
| QLoRA 7B       | 8 GB  | RTX 3070/2080      |
| QLoRA 13B      | 16 GB | RTX 3090/A4000     |
| LoRA 7B        | 16 GB | RTX 3090/A4000     |
| LoRA 13B       | 40 GB | A6000/A100 40GB    |
| FT completo 7B | 80 GB | A100 80GB          |
| Multi-GPU      | Varía | 2-8× cualquier GPU |

### 2. Conéctate por SSH a tu servidor

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. Crear directorios de trabajo

```bash
mkdir -p /root/llamafactory/{data,models,output,saves}
```

### 4. Obtener la imagen Docker

```bash
docker pull hiyouga/llamafactory:latest
```

### 5. Lanzar LLaMA-Factory

**Lanzar con UI web (LLaMA Board):**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**Con seguimiento de Weights & Biases:**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  -e WANDB_API_KEY=your_wandb_key \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**Multi-GPU con DeepSpeed (4 GPUs):**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  --shm-size 16g \
  --ipc host \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -e CUDA_VISIBLE_DEVICES=0,1,2,3 \
  hiyouga/llamafactory:latest \
  bash -c "llamafactory-cli webui"
```

### 6. Acceder a la interfaz web

Verifique los registros y obtenga la URL:

```bash
docker logs -f llamafactory
```

Su URL http\_pub de CLORE.AI para el puerto 7860:

```
https://<order-id>-7860.clore.ai/
```

***

## Ejemplos de uso

### Ejemplo 1: Ajuste fino LoRA mediante la UI web (LLaMA Board)

1. Abra LLaMA Board en su URL de CLORE.AI
2. Vaya a la **Entrenar** pestaña
3. Configurar:
   * **Nombre del modelo**: `LLaMA-3` → `Meta-Llama-3-8B-Instruct`
   * **Etapa de entrenamiento**: `Ajuste fino supervisado`
   * **Conjunto de datos**: Seleccione su conjunto de datos (o cargue uno personalizado)
   * **Método de ajuste fino**: `lora`
   * **Rango LoRA**: `8` (más alto = más parámetros entrenados)
   * **Tasa de aprendizaje**: `1e-4`
   * **Épocas**: `3`
   * **Directorio de salida**: `llama3-finetuned`
4. Haz clic **Iniciar** para comenzar el entrenamiento
5. Monitoree las curvas de pérdida en el **Pérdida** gráfico

### Ejemplo 2: Ajuste fino QLoRA desde CLI

Prepare un archivo de configuración YAML de entrenamiento:

```bash
docker exec -it llamafactory bash

cat > /app/LLaMA-Factory/configs/qlora_mistral.yaml << 'EOF'
### Modelo
model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3

### Método
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05

### Conjunto de datos
dataset: alpaca_en
template: mistral
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### Salida
output_dir: saves/mistral-qlora
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

### Entrenamiento
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
learning_rate: 0.0001
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
fp16: true

### Cuantización
quantization_method: bitsandbytes
quantization_bit: 4
EOF

# Ejecutar entrenamiento
llamafactory-cli train /app/LLaMA-Factory/configs/qlora_mistral.yaml
```

### Ejemplo 3: Subir conjunto de datos personalizado

Cree un conjunto de datos personalizado en formato Alpaca:

```bash
# Crear archivo de conjunto de datos
cat > /root/llamafactory/data/my_dataset.json << 'EOF'
[
  {
    "instruction": "Eres un agente de servicio al cliente para una empresa de tecnología. Responde de manera útil.",
    "input": "Mi portátil no enciende después de la actualización. ¿Qué debo hacer?",
    "output": "Entiendo lo frustrante que puede ser. Vamos a solucionar paso a paso:\n\n1. **Mantén pulsado el botón de encendido durante 10 segundos** para forzar el apagado\n2. **Quita el cable de alimentación** y la batería si es extraíble, espera 30 segundos\n3. **Vuelve a conectar la alimentación** e intenta encenderlo\n4. Si aún no responde, presiona **F8/F11** durante el arranque para acceder al modo de recuperación\n\n¿Le gustaría que le guíe en cualquiera de estos pasos en detalle?"
  },
  {
    "instruction": "Eres un agente de servicio al cliente para una empresa de tecnología.",
    "input": "¿Cómo restablezco mi contraseña?",
    "output": "¡Restablecer su contraseña es fácil! Así es como:\n\n1. Vaya a la página de inicio de sesión y haga clic en **'¿Olvidó su contraseña'**\n2. Introduzca su **dirección de correo electrónico registrada**\n3. Revise su correo electrónico para un enlace de restablecimiento (revise la carpeta de spam también)\n4. Haga clic en el enlace y **cree una nueva contraseña**\n\nEl enlace de restablecimiento expira en 24 horas. Si no recibe el correo dentro de 5 minutos, contacte a nuestro equipo de soporte."
  }
]
EOF

# Registrar conjunto de datos en dataset_info.json
docker exec -it llamafactory bash -c "
cat >> /app/LLaMA-Factory/data/dataset_info.json << 'EOF2'
,
\"my_dataset\": {
  \"file_name\": \"/root/llamafactory/data/my_dataset.json\"
}
EOF2
"
```

Luego seleccione `my_dataset` en el desplegable Dataset de LLaMA Board.

### Ejemplo 4: DPO (Optimización Directa por Preferencias)

```yaml
### configs/dpo_llama.yaml

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct

### Método - DPO
stage: dpo
do_train: true
finetuning_type: lora
lora_rank: 8

### Específico de DPO
pref_beta: 0.1
pref_loss: sigmoid  # sigmoid, hinge, ipo

### Conjunto de datos (debe estar en formato de preferencias)
dataset: dpo_en_demo
template: llama3
cutoff_len: 2048

### Salida
output_dir: saves/llama3-dpo
logging_steps: 10
save_steps: 100

### Entrenamiento
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 5e-5
num_train_epochs: 1.0
fp16: true
```

```bash
docker exec -it llamafactory bash -c "llamafactory-cli train /configs/dpo_llama.yaml"
```

### Ejemplo 5: Inferencia con modelo ajustado

Después del entrenamiento, pruebe su modelo:

```bash
docker exec -it llamafactory bash

# Chat interactivo
llamafactory-cli chat \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora
```

O exporte el modelo fusionado:

```bash
llamafactory-cli export \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora \
  --export_dir /app/LLaMA-Factory/output/mistral-merged \
  --export_size 4 \
  --export_legacy_format false
```

***

## Configuración

### Parámetros clave de entrenamiento

| Parámetro                     | Valor típico | Descripción                           |
| ----------------------------- | ------------ | ------------------------------------- |
| `lora_rank`                   | 8–64         | Rango LoRA (más alto = más expresivo) |
| `lora_alpha`                  | 2× rango     | Escalado alpha de LoRA                |
| `lora_dropout`                | 0.0–0.1      | Dropout para capas LoRA               |
| `lora_target`                 | `all`        | En qué capas aplicar LoRA             |
| `learning_rate`               | `1e-4`       | Tasa de aprendizaje inicial           |
| `num_train_epochs`            | 1–5          | Épocas de entrenamiento               |
| `per_device_train_batch_size` | 1–4          | Tamaño de batch por GPU               |
| `gradient_accumulation_steps` | 4–16         | Multiplicador efectivo de batch       |
| `cutoff_len`                  | 1024–4096    | Longitud máxima de secuencia          |
| `quantization_bit`            | 4 u 8        | Bits de cuantización QLoRA            |
| `warmup_ratio`                | 0.05–0.1     | Fracción de calentamiento de LR       |
| `lr_scheduler_type`           | `cosine`     | Programa de LR                        |

### Métodos de ajuste fino compatibles

| Método               | Uso de memoria | Calidad   | Cuándo usar             |
| -------------------- | -------------- | --------- | ----------------------- |
| `completo`           | Muy alto       | Mejor     | VRAM ilimitada          |
| `freeze`             | Medio          | Bueno     | Congelar capas base     |
| `lora`               | Bajo           | Muy bueno | Elección predeterminada |
| `qlora` (lora+cuant) | Más bajo       | Bueno     | VRAM limitada           |

### Entrenamiento Multi-GPU con DeepSpeed

Para entrenar en múltiples GPUs, lance con `torchrun`:

```bash
docker exec -it llamafactory bash -c "
FORCE_TORCHRUN=1 NNODES=1 RANK=0 MASTER_ADDR=127.0.0.1 MASTER_PORT=29500 \
llamafactory-cli train configs/qlora_mistral.yaml \
  --deepspeed examples/deepspeed/ds_z3_config.json
"
```

***

## Consejos de rendimiento

### 1. Configuraciones QLoRA óptimas por GPU

**8 GB VRAM (RTX 3070):**

```yaml
quantization_bit: 4
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
cutoff_len: 1024
```

**24 GB VRAM (RTX 3090/4090):**

```yaml
quantization_bit: 4  # Aún use QLoRA para un tamaño de lote mayor
per_device_train_batch_size: 4
gradient_accumulation_steps: 4
cutoff_len: 2048
```

**80 GB VRAM (A100):**

```yaml
# No se necesita cuantización — use LoRA directamente
finetuning_type: lora
per_device_train_batch_size: 8
gradient_accumulation_steps: 2
cutoff_len: 4096
fp16: true
```

### 2. Flash Attention 2 para contextos más largos

```yaml
flash_attn: fa2  # Requiere GPU Ampere o superior
```

Esto permite entrenar con secuencias 2× más largas usando la misma VRAM.

### 3. Gradient Checkpointing

Ahorra VRAM a costa de un entrenamiento \~20% más lento:

```yaml
gradient_checkpointing: true
```

### 4. Elija el objetivo LoRA correcto

```yaml
lora_target: all  # Todas las capas lineales (por defecto, mejor calidad)
# o
lora_target: q_proj,v_proj  # Mínimo, más rápido, menor calidad
```

### 5. Congelar capas superiores para adaptación rápida

```yaml
finetuning_type: freeze
freeze_trainable_layers: 2   # Entrenar solo las 2 capas superiores
freeze_trainable_modules: all
```

Mucho más rápido que LoRA completo para adaptación a tareas sencillas.

### 6. Monitorear con TensorBoard

```bash
# En una terminal separada
docker exec -it llamafactory bash -c "
tensorboard --logdir /app/LLaMA-Factory/saves --host 0.0.0.0 --port 6006
"
```

Agregue el puerto 6006 a su pedido de CLORE.AI para acceder a TensorBoard.

***

## Solución de problemas

### Problema: "CUDA out of memory" durante el entrenamiento

1. Reduzca el tamaño del lote: `per_device_train_batch_size: 1`
2. Habilite gradient checkpointing: `gradient_checkpointing: true`
3. Reduzca la longitud del contexto: `cutoff_len: 512`
4. Use QLoRA (4 bits): `quantization_bit: 4`
5. Reduzca el rango LoRA: `lora_rank: 4`

### Problema: La pérdida de entrenamiento no disminuye

* Verifique la tasa de aprendizaje — pruebe `5e-5` o `2e-4`
* Verifique que el formato del conjunto de datos coincida con la plantilla
* Aumente `lora_rank` (8→16→32)
* Verifique que `lora_target: all` esté configurado

### Problema: Velocidad de entrenamiento lenta

```bash
# Verifique la utilización de la GPU dentro del contenedor
docker exec -it llamafactory bash -c "watch -n 1 nvidia-smi"
```

Si la GPU está < 80% utilizada:

* Aumente el tamaño del lote
* Use Flash Attention: `flash_attn: fa2`
* Eliminar `gradient_checkpointing` si la VRAM lo permite

### Problema: Modelo no encontrado en la UI web

```bash
# Pre-descargar al volumen de caché
docker exec -it llamafactory bash -c "
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3
"
```

Luego actualice la lista de modelos en LLaMA Board.

### Problema: Errores en el formato del conjunto de datos

Todos los formatos de conjuntos de datos deben coincidir con `dataset_info.json` especificación:

```bash
# Validar conjunto de datos
docker exec -it llamafactory python3 -c "
import json
with open('/app/LLaMA-Factory/data/my_dataset.json') as f:
    data = json.load(f)
print(f'Dataset has {len(data)} samples')
print('First sample keys:', list(data[0].keys()))
"
```

### Problema: Puerto WebUI no accesible

Asegúrese de que LLaMA-Factory inició el servidor Gradio:

```bash
docker logs llamafactory 2>&1 | grep -E "Running on|Error|Traceback"
```

Añade `--share` bandera para una URL pública de Gradio como alternativa.

***

## Enlaces

* [GitHub](https://github.com/hiyouga/LLaMA-Factory)
* [Documentación](https://llamafactory.readthedocs.io)
* [Docker Hub (hiyouga)](https://hub.docker.com/r/hiyouga/llamafactory)
* [Modelos compatibles](https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#supported-models)
* [Formato de conjunto de datos](https://github.com/hiyouga/LLaMA-Factory/blob/main/data/README.md)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)

***

## Recomendaciones de GPU en Clore.ai

| Caso de uso             | GPU recomendada | Coste estimado en Clore.ai |
| ----------------------- | --------------- | -------------------------- |
| Desarrollo/Pruebas      | RTX 3090 (24GB) | \~$0.12/gpu/hr             |
| Ajuste fino (7B–13B)    | RTX 4090 (24GB) | \~$0.70/gpu/hr             |
| Modelos grandes (70B+)  | A100 80GB       | \~$1.20/gpu/hr             |
| Entrenamiento Multi-GPU | 2-4x A100 80GB  | \~$2.40–$4.80/hr           |

> 💡 Todos los ejemplos en esta guía pueden desplegarse en [Clore.ai](https://clore.ai/marketplace) servidores GPU. Navega las GPUs disponibles y alquila por hora — sin compromisos, acceso root completo.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/entrenamiento/llama-factory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.