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

# Datasets y Formatos

> Cómo estructurar tus datos de entrenamiento

# Datasets y Formatos

Tu modelo es tan bueno como tus datos. Aquí está cómo formatearlos correctamente.

## Formatos de Archivo Soportados

AITraining soporta múltiples fuentes de datos:

| Formato          | Cómo Se Carga                  | Caso de Uso                       |
| ---------------- | ------------------------------ | --------------------------------- |
| JSONL            | `pandas.read_json(lines=True)` | Entrenamiento LLM, conversaciones |
| CSV              | `pandas.read_csv()`            | Clasificación, datos tabulares    |
| HF Dataset ID    | `datasets.load_dataset()`      | Datasets remotos del Hub          |
| Local HF Dataset | `load_from_disk()`             | Datasets pre-procesados           |

<Note>
  Los archivos Parquet son soportados indirectamente a través de datasets HuggingFace que exponen formato Parquet.
</Note>

## Formatos Comunes

### CSV (Más Común)

Simple y universal. Funciona para clasificación, regresión y tareas básicas.

```csv theme={null}
text,label
"This product is amazing",positive
"Terrible experience",negative
"Average quality",neutral
```

### JSON/JSONL

Mejor para datos complejos, conversaciones y estructuras anidadas.

```json theme={null}
{"messages": [
  {"role": "user", "content": "What is Python?"},
  {"role": "assistant", "content": "Python is a programming language"}
]}
```

### Carpetas para Imágenes

Organiza imágenes por categoría:

```
dataset/
  cats/
    cat1.jpg
    cat2.jpg
  dogs/
    dog1.jpg
    dog2.jpg
```

## Básicos de Calidad de Datos

### Balancea Tus Clases

Mal:

* 1000 ejemplos positivos
* 50 ejemplos negativos

Bueno:

* 500 ejemplos positivos
* 500 ejemplos negativos

### Limpia Tus Datos

Elimina:

* Duplicados
* Valores vacíos
* Errores obvios
* Formato inconsistente

### Directrices de Tamaño

| Tipo de Tarea        | Mínimo | Bueno | Excelente |
| -------------------- | ------ | ----- | --------- |
| Text Classification  | 100    | 1,000 | 10,000+   |
| Image Classification | 200    | 2,000 | 20,000+   |
| Language Generation  | 50     | 500   | 5,000+    |

## Columnas Requeridas por Entrenador

Diferentes entrenadores requieren columnas específicas:

| Entrenador        | Columnas Requeridas            | Opcional |
| ----------------- | ------------------------------ | -------- |
| `sft` / `default` | `text` (o `messages`)          | -        |
| `dpo`             | `prompt`, `chosen`, `rejected` | -        |
| `orpo`            | `prompt`, `chosen`, `rejected` | -        |
| `reward`          | `text` (chosen), `rejected`    | -        |

<Warning>
  Si faltan columnas requeridas, obtendrás un error de validación claro listando las columnas faltantes y disponibles.
</Warning>

## Formatos Especiales

### DPO/ORPO (Datos de Preferencia)

```json theme={null}
{
  "prompt": "Explain gravity",
  "chosen": "Gravity is a force that attracts objects...",
  "rejected": "gravity is thing that make stuff fall"
}
```

### Token Classification

```
John    B-PERSON
Smith   I-PERSON
visited O
Paris   B-LOCATION
```

### Formato de Conversación

Las conversaciones esperan listas de objetos `{role, content}`:

```json theme={null}
{"messages": [
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi there!"}
]}
```

O formato ShareGPT (detectado y convertido automáticamente):

```json theme={null}
{"conversations": [
  {"from": "human", "value": "Hello"},
  {"from": "assistant", "value": "Hi there!"}
]}
```

#### Soporte para Rol Tool

AITraining soporta el rol `tool` para datos de entrenamiento con llamadas a funciones:

```json theme={null}
{"messages": [
  {"role": "user", "content": "¿Cuánto es 2+2?"},
  {"role": "assistant", "content": "Déjame calcularlo."},
  {"role": "tool", "content": "4"},
  {"role": "assistant", "content": "La respuesta es 4."}
]}
```

<Note>
  **Compatibilidad automática**: Para modelos que no soportan el rol `tool` nativamente (como Gemma), AITraining convierte automáticamente los mensajes `tool` a mensajes `user` con el prefijo `[Tool Result]`. Los modelos con soporte nativo de tool (Llama 3.1+, Qwen, etc.) usan su formato nativo.
</Note>

<Note>
  **Soporte de formato legado**: El rol `function` antiguo de OpenAI (usado antes de que se introdujera `tool`) también es soportado y manejado de forma idéntica al rol `tool`.
</Note>

#### Tool Calls (Llamadas a Funciones)

AITraining también soporta el campo `tool_calls` para entrenar modelos a hacer llamadas a funciones:

```json theme={null}
{"messages": [
  {"role": "user", "content": "¿Cómo está el clima en París?"},
  {
    "role": "assistant",
    "content": "Déjame verificar.",
    "tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}}]
  },
  {"role": "tool", "content": "Soleado, 20C"},
  {"role": "assistant", "content": "Está soleado y 20C en París."}
]}
```

<Note>
  **Deteccion inteligente de formato**: AITraining detecta si tu modelo soporta `tool_calls` nativamente:

  * **Qwen, Llama 3.1+**: Usa formato nativo `<tool_call>`
  * **Gemma, modelos antiguos**: Serializa tool calls como JSON formato OpenAI en el contenido

  En inferencia, parsea el JSON del output del asistente para extraer los tool calls.
</Note>

#### Transformacion de Formato de Tool Call

Para modelos sin soporte nativo de herramientas, AITraining serializa los tool calls como JSON formato OpenAI agregado al contenido del asistente:

**Entrada (mensaje con campo tool\_calls):**

```json theme={null}
{
  "role": "assistant",
  "content": "Dejame buscar eso.",
  "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]
}
```

**Salida (serializado en contenido):**

```json theme={null}
Dejame buscar eso.
{"content": "Dejame buscar eso.", "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]}
```

<Note>
  El formato serializado preserva la estructura completa de OpenAI con los campos `id`, `type` y `function`. Esto coincide con el formato descrito en las instrucciones del system prompt para mejor aprendizaje del modelo.
</Note>

#### Manejo de Alternancia de Mensajes

Algunos modelos (Gemma, Mistral) requieren alternancia estricta user/assistant. AITraining corrige automáticamente problemas comunes:

**Mensajes consecutivos del mismo rol** se fusionan:

```json theme={null}
// Antes (fallaría en Gemma)
[
  {"role": "assistant", "content": "¡Hola!"},
  {"role": "assistant", "content": "¿Cómo puedo ayudarte?"}
]

// Después (corregido automáticamente)
[
  {"role": "assistant", "content": "¡Hola!\n¿Cómo puedo ayudarte?"}
]
```

**User faltante antes de assistant** recibe un placeholder:

```json theme={null}
// Antes (system → assistant, sin user)
[
  {"role": "system", "content": "Eres útil"},
  {"role": "assistant", "content": "¡Hola!"}
]

// Después (corregido automáticamente)
[
  {"role": "system", "content": "Eres útil"},
  {"role": "user", "content": "[Continued]"},
  {"role": "assistant", "content": "¡Hola!"}
]
```

<Note>
  Estas correcciones solo se aplican cuando el tokenizador rechaza el formato original. Los modelos que aceptan orden flexible de mensajes mantienen la estructura original.
</Note>

## Conversión Automática de Dataset

AITraining puede detectar y convertir automáticamente formatos comunes de dataset. Sin preprocesamiento manual necesario.

### Formatos Soportados

| Formato        | Detección | Columnas de Ejemplo                     |
| -------------- | --------- | --------------------------------------- |
| Alpaca         | Auto      | `instruction`, `input`, `output`        |
| ShareGPT       | Auto      | `conversations` con `from`/`value`      |
| Messages       | Auto      | `messages` con `role`/`content`         |
| Q\&A           | Auto      | `question`/`answer`, `query`/`response` |
| User/Assistant | Auto      | `user`, `assistant`                     |
| DPO            | Auto      | `prompt`, `chosen`, `rejected`          |
| Plain Text     | Auto      | `text`                                  |

El mapeo de columnas es opcional - úsalo para convertir nombres de columnas variados al formato esperado.

### Usando Auto-Conversión

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path tatsu-lab/alpaca \
  --auto-convert-dataset \
  --chat-template gemma3 \
  --trainer sft
```

### Chat Templates

Los chat templates formatean tus datos en la estructura de conversación esperada del modelo.

| Opción      | Descripción                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `tokenizer` | Usa el chat template integrado del modelo (predeterminado para SFT/DPO/ORPO) |
| `chatml`    | Formato estándar ChatML                                                      |
| `zephyr`    | Formato Zephyr/Mistral                                                       |
| `none`      | Sin template (texto plano)                                                   |

Los templates se auto-seleccionan basándose en tu entrenador, o especifica manualmente:

```bash theme={null}
--chat-template tokenizer  # Usa template del modelo (recomendado)
--chat-template chatml     # Fuerza ChatML
--chat-template none       # Deshabilita para texto plano
```

<Note>
  El renderizador unificado aplica templates consistentemente. Las rutas de template legacy todavía son soportadas para compatibilidad hacia atrás.
</Note>

### Extensión de Conversación

Fusiona ejemplos de turno único en conversaciones multi-turno:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./qa_pairs.jsonl \
  --auto-convert-dataset \
  --conversation-extension 3 \
  --trainer sft
```

## Salida del Dataset Procesado

Después del procesamiento, tu dataset tendrá:

| Columna              | Descripción                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `text`               | Datos de entrenamiento formateados con plantilla de chat aplicada |
| `_original_messages` | Columna de mensajes original (preservada para inspección)         |
| `_original_*`        | Otras columnas originales renombradas con prefijo                 |

<Note>
  Las columnas originales se renombran a `_original_*` para prevenir que otras herramientas auto-detecten y usen incorrectamente datos no procesados.
</Note>

### Guardando Datos Procesados

Controla dónde se guardan los datos procesados con `--save-processed-data`:

| Opción  | Comportamiento                                                  |
| ------- | --------------------------------------------------------------- |
| `auto`  | Guardar localmente; también subir a Hub si la fuente era de Hub |
| `local` | Guardar solo en `{project}/data_processed/`                     |
| `hub`   | Subir solo a Hub como dataset privado                           |
| `both`  | Guardar localmente y subir a Hub                                |
| `none`  | No guardar datos procesados                                     |

## Consejos Rápidos

1. **Comienza pequeño** - Prueba con 100 ejemplos antes de escalar
2. **Valida temprano** - Verifica que tu formato funciona antes de recopilar miles de ejemplos
3. **Mantén consistente** - Mismo formato en todo tu dataset
4. **Documenta todo** - Anota cualquier preprocesamiento o reglas especiales
5. **Usa auto-convert** - Deja que AITraining detecte y convierta formatos automáticamente

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Hyperparámetros" href="/foundations/hyperparameters">
    Configura tu entrenamiento
  </Card>

  <Card title="Tareas de Entrenamiento" href="/foundations/training-tasks">
    Elige tu tipo de tarea
  </Card>
</CardGroup>