Guía del formato JSONL de OpenAI
Todo lo que necesitas saber sobre el formato JSONL que usa OpenAI para el fine-tuning de modelos y la Batch API. Incluye las especificaciones del formato, ejemplos de código y errores habituales.
¿Qué es el formato JSONL de OpenAI?
OpenAI usa JSONL (JSON Lines) como formato de archivo estándar para los datasets de fine-tuning y las solicitudes a la Batch API. Cada línea del archivo contiene un objeto JSON completo e independiente, sin un array que englobe los objetos ni comas entre líneas.
Este formato permite procesar los datos en streaming y línea por línea de forma eficiente. Cada ejemplo de entrenamiento o solicitud a la API se puede validar por separado, y los archivos se pueden procesar sin cargar todo el dataset en memoria.
Es fundamental conocer los requisitos exactos del formato. Incluso un pequeño error, como una coma al final o la ausencia de un campo, hará que se rechace el archivo completo.
Formato JSONL para fine-tuning
Para el fine-tuning de modelos de chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), cada línea debe contener un array "messages" con los mensajes de la conversación.
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}Campos obligatorios
- messages — Array de objetos de mensaje (obligatorio)
- role — Uno de estos valores: "system", "user" o "assistant" (obligatorio)
- content — Contenido de texto del mensaje (obligatorio)
El mensaje del sistema es opcional, pero se recomienda incluirlo. Cada conversación debe contener al menos un mensaje del usuario y uno del asistente. El mensaje del asistente es el que el modelo aprende a generar.
Formato JSONL para la Batch API
La Batch API usa un formato JSONL distinto: cada línea contiene una solicitud a la API con un ID personalizado.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, how are you?"}]}}
{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"What is the weather today?"}]}}Campos obligatorios
- custom_id — Identificador único para cada solicitud (obligatorio)
- method — Método HTTP, normalmente "POST" (obligatorio)
- url — Ruta del endpoint de la API (obligatorio)
- body — Cuerpo de la solicitud, igual que en una llamada habitual a la API (obligatorio)
Requisitos de formato
Sigue estas reglas para que OpenAI acepte tu archivo JSONL:
- Cada línea debe contener JSON válido, sin errores de sintaxis
- Cada línea debe contener un objeto JSON (empieza con { y termina con })
- Los archivos de fine-tuning deben incluir un array "messages" en cada línea
- Cada mensaje debe incluir los campos "role" y "content"
- Los roles válidos son: "system", "user" y "assistant"
- El archivo debe estar codificado en UTF-8 sin BOM (Byte Order Mark)
- No se permiten comas al final, comentarios ni espacios en blanco adicionales entre líneas
- Se permiten líneas vacías; se ignorarán al procesar el archivo
Errores comunes
Estos son los errores más frecuentes al crear archivos JSONL para OpenAI:
Usar un array JSON en lugar de JSONL
Es incorrecto encerrar todos los objetos entre [ ]. Un archivo JSONL debe contener un objeto por línea, sin un array que los englobe.
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}Omitir campos obligatorios
Cada mensaje debe incluir tanto "role" como "content". Si falta cualquiera de los dos, la validación fallará.
{"messages":[{"role":"user"}]}{"messages":[{"role":"user","content":"Hello"}]}Comas finales en JSON
JSON no admite una coma después del último elemento de un array u objeto.
{"messages":[{"role":"user","content":"Hi",}]}{"messages":[{"role":"user","content":"Hi"}]}Caracteres BOM o codificación incorrecta
Guarda el archivo en UTF-8 sin BOM. Algunos editores de texto añaden caracteres BOM invisibles que impiden analizar el JSON correctamente.
\uFEFF{"messages":[...]}{"messages":[...]}Ejemplos de código
Estos ejemplos muestran cómo crear archivos JSONL para OpenAI mediante código:
import json
training_data = [
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is JSONL?"},
{"role": "assistant", "content": "JSONL (JSON Lines) is a text format where each line is a valid JSON object."}
]},
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "How do I fine-tune a model?"},
{"role": "assistant", "content": "Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API."}
]},
]
with open("training.jsonl", "w", encoding="utf-8") as f:
for entry in training_data:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
print(f"Created training.jsonl with {len(training_data)} examples")const fs = require('fs');
const trainingData = [
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is JSONL?' },
{ role: 'assistant', content: 'JSONL (JSON Lines) is a text format where each line is a valid JSON object.' },
]},
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'How do I fine-tune a model?' },
{ role: 'assistant', content: 'Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API.' },
]},
];
const jsonl = trainingData.map(d => JSON.stringify(d)).join('\n');
fs.writeFileSync('training.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created training.jsonl with ${trainingData.length} examples`);Herramientas y guías relacionadas
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Da formato a los archivos JSONL con una sangría adecuada para facilitar su lectura, depuración y revisión.
Divide archivos JSONL grandes en fragmentos más pequeños y manejables por número de líneas.
Aprende a estructurar archivos JSONL para la Batch API de OpenAI. Incluye el formato de las solicitudes, el parseo de las respuestas y un flujo de trabajo completo con ejemplos de código.
Aprende a preparar datos de entrenamiento en JSONL para fine-tuning de IA/ML. Incluye los formatos de datasets de OpenAI, Anthropic Claude y HuggingFace, junto con la validación y los pipelines de preparación de datos.