JSONL para datos de entrenamiento de IA
Una guía completa para preparar datos de entrenamiento en JSONL para IA y aprendizaje automático. Incluye fine-tuning con OpenAI, Anthropic Claude, datasets de HuggingFace, validación de datos y pipelines de datos a gran escala.
Por qué JSONL es el estándar para los datos de entrenamiento de IA
JSONL (JSON Lines) se ha convertido en el estándar de facto para los datos de entrenamiento de IA y aprendizaje automático. Los principales proveedores de IA, desde OpenAI hasta Anthropic y HuggingFace, utilizan JSONL como formato principal para sus datasets de fine-tuning. La razón es sencilla: JSONL almacena un ejemplo por línea, lo que facilita leer los datos en streaming durante el entrenamiento, mezclar los ejemplos, contar registros, dividir los datos en conjuntos de entrenamiento y prueba y añadir nuevas muestras sin reescribir todo el archivo.
A diferencia de un array JSON, que hay que parsear por completo antes de usarlo, los archivos JSONL se pueden procesar línea a línea. Esta diferencia cobra importancia cuando tus datasets de entrenamiento alcanzan millones de ejemplos y ocupan gigabytes. En esta guía aprenderás qué formatos JSONL requieren exactamente OpenAI, Anthropic Claude y HuggingFace, cómo validar y limpiar tus datos y cómo preparar datasets a gran escala para entrenamientos en producción.
Formato JSONL para fine-tuning con OpenAI
OpenAI utiliza JSONL tanto para fine-tuning como para la Batch API. Para hacer fine-tuning de modelos de chat como GPT-4o-mini, cada línea debe contener un array messages con la estructura estándar de Chat Completions. Los tres roles, system, user y assistant, definen la conversación que el modelo debe aprender a reproducir.
Cada línea corresponde a un ejemplo de entrenamiento. El mensaje system define el comportamiento, el mensaje user contiene la entrada y el mensaje assistant contiene la salida esperada que el modelo debe aprender a generar.
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "Where is my order #12345?"}, {"role": "assistant", "content": "I can see that order #12345 was shipped on February 10th via FedEx. The tracking number is FX987654321. Based on the latest update, it should arrive by February 14th."}]}
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "I want to return my purchase."}, {"role": "assistant", "content": "I would be happy to help with your return. Could you please provide the order number and the reason for the return? Our return policy allows returns within 30 days of delivery for most items."}]}Para entrenar con conversaciones de varios turnos, incluye el historial completo. El modelo aprende de cada intervención con el rol assistant en el array messages. Así le enseñas a responder a preguntas de seguimiento.
{"messages": [{"role": "system", "content": "You are a Python programming tutor."}, {"role": "user", "content": "What is a list comprehension?"}, {"role": "assistant", "content": "A list comprehension is a concise way to create lists in Python. Instead of writing a for loop to build a list, you can write it in one line: [expression for item in iterable if condition]."}, {"role": "user", "content": "Can you show me an example?"}, {"role": "assistant", "content": "Sure! Here is an example that creates a list of squares for even numbers:\n\nsquares = [x**2 for x in range(10) if x % 2 == 0]\n# Result: [0, 4, 16, 36, 64]\n\nThis is equivalent to:\nsquares = []\nfor x in range(10):\n if x % 2 == 0:\n squares.append(x**2)"}]}OpenAI exige al menos 10 ejemplos de entrenamiento, pero recomienda 50-100 para obtener mejoras apreciables. Todos los mensajes deben incluir los campos role y content. El mensaje system es opcional, aunque se recomienda para mantener un comportamiento coherente. Usa la CLI de OpenAI para validar tu archivo antes de subirlo: openai tools fine_tunes.prepare_data -f training.jsonl
Formato de entrenamiento de Anthropic Claude
Anthropic utiliza JSONL para hacer fine-tuning de los modelos Claude. El formato organiza la conversación en turnos human y assistant. Aunque el formato exacto depende del método de fine-tuning y de la versión de la API, la estructura básica sigue la de la Messages API.
Cada línea contiene una conversación con un prompt de sistema y mensajes que alternan los roles user y assistant. El modelo aprende a generar las respuestas del asistente a partir del contexto de la conversación.
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "What are the symptoms of vitamin D deficiency?"}, {"role": "assistant", "content": "Common symptoms of vitamin D deficiency include fatigue and tiredness, bone pain and muscle weakness, mood changes including depression, slow wound healing, and frequent infections. However, many people with mild deficiency may not notice symptoms. A blood test is the only way to confirm your vitamin D levels. I recommend speaking with your doctor who can order the appropriate test and recommend supplementation if needed."}]}
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "Is it safe to take ibuprofen daily?"}, {"role": "assistant", "content": "Taking ibuprofen daily for extended periods can carry risks including stomach ulcers and gastrointestinal bleeding, increased risk of heart attack and stroke, kidney problems with long-term use, and potential interactions with other medications. For occasional pain relief, short-term use at recommended doses is generally considered safe for most adults. However, if you find yourself needing daily pain relief, please consult your doctor. They can evaluate the underlying cause and recommend a safer long-term treatment plan."}]}Para entrenar con conversaciones de varios turnos, incluye la conversación completa, alternando mensajes con los roles user y assistant. El modelo aprende cómo se desarrolla la conversación y cómo mantener el contexto de un turno a otro.
{"system": "You are a cooking assistant specializing in Italian cuisine.", "messages": [{"role": "user", "content": "How do I make carbonara?"}, {"role": "assistant", "content": "Authentic carbonara uses just five ingredients: spaghetti, guanciale (cured pork cheek), eggs, Pecorino Romano cheese, and black pepper. The key technique is tempering the egg mixture with the hot pasta water so it creates a creamy sauce without scrambling."}, {"role": "user", "content": "Can I use bacon instead of guanciale?"}, {"role": "assistant", "content": "While guanciale gives the most authentic flavor, pancetta is a closer substitute. Bacon works in a pinch but its smoky flavor changes the dish significantly. If using bacon, choose an unsmoked variety. Whichever you use, cut it into small pieces and render the fat slowly over medium-low heat until crispy."}]}Datasets de HuggingFace con JSONL
La biblioteca datasets de HuggingFace admite JSONL de forma nativa como formato de entrada. Puedes cargar archivos JSONL locales, leer datasets remotos en streaming y convertirlos fácilmente de un formato a otro. JSONL es el formato recomendado para compartir datasets en el HuggingFace Hub.
Usa la biblioteca datasets para cargar archivos JSONL en un objeto Dataset. Así dispones de acceso eficiente mediante mapeo en memoria, funciones integradas para dividir los datos en conjuntos de entrenamiento y prueba e integración directa con la Trainer API.
from datasets import load_dataset
# Load a local JSONL file
dataset = load_dataset('json', data_files='training.jsonl')
print(dataset)
# DatasetDict({
# train: Dataset({
# features: ['messages', 'system'],
# num_rows: 5000
# })
# })
# Load with train/test split
dataset = load_dataset('json', data_files={
'train': 'train.jsonl',
'test': 'test.jsonl'
})
# Stream a large remote dataset
dataset = load_dataset(
'json',
data_files='https://example.com/large_dataset.jsonl',
streaming=True
)
for example in dataset['train']:
print(example)
breakConvierte cualquier dataset de HuggingFace a JSONL para usarlo en otros pipelines de entrenamiento. El método to_json escribe cada ejemplo en una línea JSON independiente.
from datasets import load_dataset
# Load a dataset from the Hub
dataset = load_dataset('squad', split='train')
# Export to JSONL
dataset.to_json('squad_train.jsonl')
print(f'Exported {len(dataset)} examples')
# Export with specific columns
dataset.select_columns(['question', 'context', 'answers']).to_json(
'squad_filtered.jsonl'
)
# Process and export
def format_for_finetuning(example):
return {
'messages': [
{'role': 'user', 'content': example['question']},
{'role': 'assistant', 'content': example['answers']['text'][0]}
]
}
formatted = dataset.map(format_for_finetuning, remove_columns=dataset.column_names)
formatted.to_json('squad_chat_format.jsonl')Validación y limpieza de datos
La calidad de los datos de entrenamiento influye directamente en el rendimiento del modelo. Un JSON no válido, la ausencia de campos, los ejemplos demasiado largos y los registros duplicados pueden empeorar los resultados del fine-tuning. Valida y limpia siempre tus archivos JSONL antes de iniciar un entrenamiento.
Este script comprueba cada línea de tu archivo JSONL para detectar problemas habituales: JSON no válido, ausencia de campos obligatorios, contenido vacío y problemas con la longitud en tokens. Ejecútalo antes de subir el archivo para detectar los problemas a tiempo.
import json
import sys
from collections import Counter
def validate_training_data(path: str) -> dict:
"""Validate a JSONL file for AI fine-tuning."""
stats = Counter()
errors = []
with open(path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
stats['total'] += 1
# Check valid JSON
try:
data = json.loads(line)
except json.JSONDecodeError as e:
errors.append(f'Line {line_num}: Invalid JSON - {e}')
stats['invalid_json'] += 1
continue
# Check messages field exists
if 'messages' not in data:
errors.append(f'Line {line_num}: Missing "messages" field')
stats['missing_messages'] += 1
continue
messages = data['messages']
# Check message structure
for i, msg in enumerate(messages):
if 'role' not in msg:
errors.append(f'Line {line_num}, msg {i}: Missing "role"')
stats['missing_role'] += 1
if 'content' not in msg:
errors.append(f'Line {line_num}, msg {i}: Missing "content"')
stats['missing_content'] += 1
elif not msg['content'].strip():
errors.append(f'Line {line_num}, msg {i}: Empty content')
stats['empty_content'] += 1
# Check has at least one assistant message
roles = [m.get('role') for m in messages]
if 'assistant' not in roles:
errors.append(f'Line {line_num}: No assistant message')
stats['no_assistant'] += 1
stats['valid'] += 1
return {'stats': dict(stats), 'errors': errors[:50]}
result = validate_training_data('training.jsonl')
print(f"Total: {result['stats'].get('total', 0)}")
print(f"Valid: {result['stats'].get('valid', 0)}")
if result['errors']:
print(f"\nFirst {len(result['errors'])} errors:")
for err in result['errors']:
print(f' {err}')Los ejemplos de entrenamiento duplicados consumen recursos de cómputo innecesariamente y pueden sesgar el modelo hacia patrones sobrerrepresentados. Este script elimina los duplicados exactos a partir del hash del contenido de cada línea.
import json
import hashlib
def deduplicate_jsonl(input_path: str, output_path: str) -> dict:
"""Remove duplicate training examples from a JSONL file."""
seen_hashes = set()
total = 0
unique = 0
with open(input_path, 'r') as fin, open(output_path, 'w') as fout:
for line in fin:
line = line.strip()
if not line:
continue
total += 1
# Hash the normalized JSON to catch formatting differences
data = json.loads(line)
canonical = json.dumps(data, sort_keys=True)
content_hash = hashlib.sha256(canonical.encode()).hexdigest()
if content_hash not in seen_hashes:
seen_hashes.add(content_hash)
fout.write(json.dumps(data) + '\n')
unique += 1
duplicates = total - unique
print(f'Total: {total}, Unique: {unique}, Removed: {duplicates}')
return {'total': total, 'unique': unique, 'duplicates': duplicates}
deduplicate_jsonl('training.jsonl', 'training_deduped.jsonl')Preparación de datos a gran escala
Los datasets que se usan para entrenar modelos en producción suelen contener cientos de miles o millones de ejemplos. A esta escala, necesitas pipelines automatizados para mezclar, dividir y fragmentar tus datos JSONL. Una preparación adecuada evita problemas de entrenamiento, como el olvido catastrófico, y permite reproducir los experimentos.
Este script mezcla los datos de forma aleatoria y los divide en conjuntos de entrenamiento y prueba. Mezclarlos es fundamental porque los archivos JSONL suelen generarse siguiendo un orden, y entrenar con datos ordenados puede reducir la capacidad de generalización del modelo.
import json
import random
from pathlib import Path
def prepare_training_data(
input_path: str,
output_dir: str,
test_ratio: float = 0.1,
seed: int = 42
) -> dict:
"""Shuffle and split JSONL into train/test sets."""
random.seed(seed)
output = Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
# Load all examples
examples = []
with open(input_path, 'r') as f:
for line in f:
line = line.strip()
if line:
examples.append(json.loads(line))
# Shuffle
random.shuffle(examples)
# Split
split_idx = int(len(examples) * (1 - test_ratio))
train_data = examples[:split_idx]
test_data = examples[split_idx:]
# Write output files
train_path = output / 'train.jsonl'
test_path = output / 'test.jsonl'
for data, path in [(train_data, train_path), (test_data, test_path)]:
with open(path, 'w') as f:
for example in data:
f.write(json.dumps(example) + '\n')
print(f'Train: {len(train_data)} examples -> {train_path}')
print(f'Test: {len(test_data)} examples -> {test_path}')
return {'train': len(train_data), 'test': len(test_data)}
prepare_training_data(
'all_examples.jsonl',
'./prepared_data/',
test_ratio=0.1,
seed=42
)Cuando los datasets son demasiado grandes para un solo archivo o necesitas distribuir el entrenamiento entre varias GPUs, divide el archivo JSONL en fragmentos más pequeños. Cada fragmento se puede procesar de forma independiente.
import json
from pathlib import Path
def shard_jsonl(
input_path: str,
output_dir: str,
shard_size: int = 50000
) -> int:
"""Split a large JSONL file into smaller shards."""
output = Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
shard_num = 0
line_count = 0
current_file = None
with open(input_path, 'r') as fin:
for line in fin:
line = line.strip()
if not line:
continue
if line_count % shard_size == 0:
if current_file:
current_file.close()
shard_path = output / f'shard_{shard_num:04d}.jsonl'
current_file = open(shard_path, 'w')
shard_num += 1
current_file.write(line + '\n')
line_count += 1
if current_file:
current_file.close()
print(f'Created {shard_num} shards from {line_count} examples')
return shard_num
shard_jsonl('large_dataset.jsonl', './shards/', shard_size=50000)Valida tus datos de entrenamiento en línea
Usa nuestras herramientas gratuitas desde el navegador para validar, formatear y convertir tus datos de entrenamiento en JSONL antes de subirlos a OpenAI, Anthropic o HuggingFace.
Guía completa para preparar archivos JSONL para OpenAI. Incluye el formato de los datos de fine-tuning, las solicitudes de Batch API, los errores habituales y consejos de validación.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Divide archivos JSONL grandes en fragmentos más pequeños y manejables por número de líneas.
Convierte hojas de cálculo CSV al formato JSONL. Útil para migrar datos y procesarlos por lotes.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.