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

# Entrenamiento LLM

> Entrena modelos de lenguaje grandes con el CLI

# Entrenamiento LLM

El comando `aitraining llm` entrena modelos de lenguaje grandes con soporte para múltiples trainers y técnicas.

## Inicio Rápido

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --trainer sft
```

## Trainers Disponibles

| Trainer                       | Descripción                                                          |
| ----------------------------- | -------------------------------------------------------------------- |
| `default` / `sft` / `generic` | Fine-tuning supervisado                                              |
| `dpo`                         | Optimización Directa de Preferencias                                 |
| `orpo`                        | Optimización de Razón de Probabilidades de Preferencias              |
| `ppo`                         | Optimización de Política Proximal                                    |
| `grpo`                        | Optimización de Política Relativa de Grupo (entornos personalizados) |
| `reward`                      | Entrenamiento de modelo de recompensa                                |
| `distillation`                | Distilación de conocimiento                                          |

<Note>
  `generic` es un alias para `default`. Los tres (`default`, `sft`, `generic`) producen el mismo comportamiento.
</Note>

<Warning>
  **Requisitos del Trainer PPO**: PPO requiere `--rl-reward-model-path` (ruta a un modelo de recompensa entrenado) o `--model-ref` (modelo de referencia para divergencia KL). Ver [Entrenamiento PPO](/advanced/ppo-rl-training) para documentación completa.
</Warning>

<Warning>
  **Requisitos del Trainer GRPO**: GRPO requiere `--rl-env-module` (ruta del módulo Python) y `--rl-env-class` (nombre de la clase) para el entorno personalizado. Ver [Entrenamiento GRPO](/advanced/grpo-training) para documentación completa.
</Warning>

## Grupos de Parámetros

Los parámetros están organizados en grupos lógicos:

### Parámetros Básicos

| Parameter        | Description             | Default               |
| ---------------- | ----------------------- | --------------------- |
| `--model`        | Base model to fine-tune | `google/gemma-3-270m` |
| `--data-path`    | Path to training data   | `data`                |
| `--project-name` | Output directory name   | `project-name`        |
| `--train-split`  | Training data split     | `train`               |
| `--valid-split`  | Validation data split   | `None`                |

<Note>
  **Siempre especifica estos parámetros**: Aunque `--model`, `--data-path` y `--project-name` tienen valores predeterminados, siempre debes establecerlos explícitamente para tu caso de uso. El parámetro `--project-name` establece la carpeta de salida - usa una ruta como `--project-name ./models/my-experiment` para controlar dónde se guarda el modelo entrenado.
</Note>

### Configuración de Entrenamiento

| Parameter                 | Description               | Default       |
| ------------------------- | ------------------------- | ------------- |
| `--trainer`               | Training method           | `default`     |
| `--epochs`                | Number of training epochs | `1`           |
| `--batch-size`            | Training batch size       | `2`           |
| `--lr`                    | Learning rate             | `3e-5`        |
| `--mixed-precision`       | fp16/bf16/None            | `None`        |
| `--gradient-accumulation` | Accumulation steps        | `4`           |
| `--warmup-ratio`          | Warmup ratio              | `0.1`         |
| `--optimizer`             | Optimizer                 | `adamw_torch` |
| `--scheduler`             | LR scheduler              | `linear`      |
| `--weight-decay`          | Weight decay              | `0.0`         |
| `--max-grad-norm`         | Max gradient norm         | `1.0`         |
| `--seed`                  | Random seed               | `42`          |

### Checkpointing y Evaluación

| Parameter                  | Description                                             | Default |
| -------------------------- | ------------------------------------------------------- | ------- |
| `--eval-strategy`          | When to evaluate (`epoch`, `steps`, `no`)               | `epoch` |
| `--save-strategy`          | When to save (`epoch`, `steps`, `no`)                   | `epoch` |
| `--save-steps`             | Save every N steps (if save-strategy=steps)             | `500`   |
| `--save-total-limit`       | Max checkpoints to keep                                 | `1`     |
| `--logging-steps`          | Log every N steps (-1 for auto)                         | `-1`    |
| `--resume-from-checkpoint` | Resume from checkpoint path, or `auto` to detect latest | `None`  |

### Rendimiento y Memoria

| Parameter                          | Description                                                           | Default |
| ---------------------------------- | --------------------------------------------------------------------- | ------- |
| `--auto-find-batch-size`           | Automatically find optimal batch size                                 | `False` |
| `--disable-gradient-checkpointing` | Disable memory optimization                                           | `False` |
| `--unsloth`                        | Use Unsloth for faster training (SFT only, llama/mistral/gemma/qwen2) | `False` |
| `--use-sharegpt-mapping`           | Use Unsloth's ShareGPT mapping                                        | `False` |
| `--use-flash-attention-2`          | Use Flash Attention 2 for faster training                             | `False` |
| `--attn-implementation`            | Attention implementation (`eager`, `sdpa`, `flash_attention_2`)       | `None`  |

<Note>
  **Requisitos de Unsloth**: Unsloth solo funciona con trainers `sft`/`default` y arquitecturas de modelo específicas (llama, mistral, gemma, qwen2). Ver [Integración Unsloth](/advanced/unsloth-integration) para detalles.
</Note>

### Backend y Distribución

| Parameter               | Description                               | Default |
| ----------------------- | ----------------------------------------- | ------- |
| `--backend`             | Where to run (`local`, `spaces`)          | `local` |
| `--distributed-backend` | Distribution backend (`ddp`, `deepspeed`) | `None`  |
| `--ddp-timeout`         | DDP/NCCL timeout in seconds               | `7200`  |

<Note>
  **Comportamiento Multi-GPU**: Con múltiples GPUs y `--distributed-backend` no establecido, DDP se usa automáticamente. Establece `--distributed-backend deepspeed` para optimización DeepSpeed Zero-3. El entrenamiento se lanza vía Accelerate.
</Note>

<Warning>
  **Checkpointing DeepSpeed**: Al usar DeepSpeed, el guardado del modelo usa `accelerator.get_state_dict()` y desempaqueta el modelo. El guardado del adaptador PEFT se maneja de forma diferente bajo DeepSpeed.
</Warning>

### Parámetros PEFT/LoRA

| Parameter          | Description               | Default      |
| ------------------ | ------------------------- | ------------ |
| `--peft`           | Enable LoRA training      | `False`      |
| `--lora-r`         | LoRA rank                 | `16`         |
| `--lora-alpha`     | LoRA alpha                | `32`         |
| `--lora-dropout`   | LoRA dropout              | `0.05`       |
| `--target-modules` | Modules to target         | `all-linear` |
| `--quantization`   | int4/int8 quantization    | `None`       |
| `--merge-adapter`  | Merge LoRA after training | `True`       |

### Procesamiento de Datos

| Parameter                | Description                                                 | Default                |
| ------------------------ | ----------------------------------------------------------- | ---------------------- |
| `--text-column`          | Text column name                                            | `text`                 |
| `--block-size`           | Max sequence length                                         | `-1` (model default)   |
| `--model-max-length`     | Maximum model input length                                  | Auto-detect from model |
| `--padding`              | Padding side (`left` or `right`)                            | `right`                |
| `--add-eos-token`        | Append EOS token                                            | `True`                 |
| `--chat-template`        | Chat template to use                                        | Auto by trainer        |
| `--packing`              | Enable sequence packing (requires flash attention)          | `None`                 |
| `--auto-convert-dataset` | Auto-detect and convert dataset format                      | `False`                |
| `--max-samples`          | Limit dataset size for testing                              | `None`                 |
| `--save-processed-data`  | Save processed data: `auto`, `local`, `hub`, `both`, `none` | `auto`                 |

<Note>
  **Selección Automática de Plantilla de Chat**: Los trainers SFT/DPO/ORPO/Reward usan `tokenizer` (plantilla integrada del modelo) por defecto. Usa `--chat-template none` para entrenamiento de texto plano.
</Note>

<Note>
  **Guardado de Datos Procesados**: Por defecto (`auto`), los datos procesados se guardan localmente en `{project}/data_processed/`. Si el dataset fuente era del Hub, también se sube como dataset privado. Las columnas originales se renombran a `_original_*` para prevenir conflictos.
</Note>

## Ejemplos de Entrenamiento

### SFT with LoRA

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

### Entrenamiento DPO

Para DPO, debes especificar los nombres de las columnas para prompt, respuesta elegida y respuesta rechazada:

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./preferences.jsonl \
  --project-name llama-dpo \
  --trainer dpo \
  --prompt-text-column prompt \
  --text-column chosen \
  --rejected-text-column rejected \
  --dpo-beta 0.1 \
  --peft \
  --lora-r 16
```

<Warning>
  DPO y ORPO requieren que se especifiquen `--prompt-text-column` y `--rejected-text-column`.
</Warning>

### Entrenamiento ORPO

ORPO combina SFT y optimización de preferencias:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-2-2b \
  --data-path ./preferences.jsonl \
  --project-name gemma-orpo \
  --trainer orpo \
  --prompt-text-column prompt \
  --text-column chosen \
  --rejected-text-column rejected \
  --peft
```

### Entrenamiento GRPO

Entrena con Group Relative Policy Optimization usando tu propio entorno de recompensa:

```bash theme={null}
aitraining llm --train \
  --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
  --trainer grpo \
  --rl-env-module my_envs.hotel_env \
  --rl-env-class HotelEnv \
  --rl-num-generations 4 \
  --rl-max-new-tokens 256 \
  --peft \
  --lr 1e-5
```

<Note>
  GRPO genera múltiples completaciones por prompt, las puntúa mediante tu entorno (0-1), y optimiza la política. Ver [Entrenamiento GRPO](/advanced/grpo-training) para detalles de la interfaz del entorno.
</Note>

### Distilación de Conocimiento

Entrena un modelo más pequeño para imitar uno más grande:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --teacher-model google/gemma-2-2b \
  --data-path ./prompts.jsonl \
  --project-name distilled-model \
  --use-distillation \
  --distill-temperature 3.0
```

<Note>
  Valores predeterminados de distilación: `--distill-temperature 3.0`, `--distill-alpha 0.7`, `--distill-max-teacher-length 512`
</Note>

## Logging y Monitorización

### Weights & Biases (Predeterminado)

El logging W\&B con visualizador LEET está **habilitado por defecto**. El visualizador LEET muestra métricas de entrenamiento en tiempo real directamente en tu terminal.

```bash theme={null}
# W&B is on by default - just run training
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model
```

Para deshabilitar W\&B o el visualizador:

```bash theme={null}
# Disable W&B logging entirely
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --log none

# Keep W&B but disable terminal visualizer
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --no-wandb-visualizer
```

### TensorBoard

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --log tensorboard
```

## Push a Hugging Face Hub

Sube tu modelo entrenado:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --push-to-hub \
  --username your-username \
  --token $HF_TOKEN
```

<Note>
  El repositorio se crea como **privado** por defecto. Por defecto, el repositorio se nombrará `{username}/{project-name}`.
</Note>

### Nombre de Repositorio Personalizado u Organización

Usa `--repo-id` para subir a un repositorio específico, útil para:

* Subir a una **organización** en lugar de tu cuenta personal
* Usar un **nombre de repo diferente** a tu `project-name` local

```bash theme={null}
# Subir a una organización
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name ./local-training-output \
  --push-to-hub \
  --repo-id my-organization/my-custom-model-name \
  --token $HF_TOKEN

# Subir a cuenta personal con nombre diferente
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name ./experiment-v3 \
  --push-to-hub \
  --repo-id your-username/production-model \
  --token $HF_TOKEN
```

| Parámetro                            | Descripción                                    | Por Defecto                 |
| ------------------------------------ | ---------------------------------------------- | --------------------------- |
| `--push-to-hub`                      | Habilitar subida al Hub                        | `False`                     |
| `--hub-private` / `--no-hub-private` | Crear repo como privado o publico              | `True` (privado)            |
| `--username`                         | Usuario HF (para nombrado de repo por defecto) | `None`                      |
| `--token`                            | Token API de HF                                | `None`                      |
| `--repo-id`                          | ID completo del repo (ej: `org/model-name`)    | `{username}/{project-name}` |

<Warning>
  Al usar `--repo-id`, no necesitas `--username` ya que el ID del repo ya especifica el destino. Sin embargo, aún necesitas `--token` para autenticación.
</Warning>

## Opciones Avanzadas

### Barridos de Hiperparámetros

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name sweep-experiment \
  --use-sweep \
  --sweep-backend optuna \
  --sweep-n-trials 10
```

### Evaluación Mejorada

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --use-enhanced-eval \
  --eval-metrics "perplexity,bleu"
```

## Ver Todos los Parámetros

Ver todos los parámetros para un trainer específico:

```bash theme={null}
aitraining llm --trainer sft --help
aitraining llm --trainer dpo --help
```

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Configuraciones YAML" href="/cli/yaml-configs">
    Usar archivos de configuración
  </Card>

  <Card title="Entrenamiento DPO" href="/advanced/dpo-training">
    Inmersión profunda en DPO
  </Card>

  <Card title="LoRA/PEFT" href="/advanced/lora-peft">
    Fine-tuning eficiente
  </Card>

  <Card title="Distilación" href="/advanced/prompt-distillation">
    Distilación de conocimiento
  </Card>

  <Card title="Entrenamiento GRPO" href="/advanced/grpo-training">
    RL con entornos personalizados
  </Card>
</CardGroup>