Guía del formato JSONL de OpenAI
Todo lo que necesitas saber sobre el formato JSONL utilizado por OpenAI para fine-tuning de modelos y la Batch API. Incluye especificaciones de formato, ejemplos de código y errores comunes.
Última actualización: febrero 2026
¿Qué es el formato JSONL de OpenAI?
OpenAI usa JSONL (JSON Lines) como formato de archivo estándar para datasets de fine-tuning y solicitudes de Batch API. Cada línea del archivo es un objeto JSON completo e independiente — sin array envolvente, sin comas entre líneas.
Este formato se elige porque permite streaming eficiente y procesamiento línea por línea. Cada ejemplo de entrenamiento o solicitud de API puede validarse independientemente, y los archivos pueden procesarse sin cargar todo el dataset en memoria.
Comprender los requisitos exactos del formato es crítico. Incluso pequeños errores de formato — como una coma final o un campo faltante — harán que todo el archivo sea rechazado.
Formato JSONL para Fine-tuning
Para 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 turnos de 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 requeridos
- messages — Array de objetos de mensaje (requerido)
- role — Uno de: "system", "user" o "assistant" (requerido)
- content — El contenido de texto del mensaje (requerido)
El mensaje del sistema es opcional pero recomendado. Cada conversación debe tener al menos un mensaje de usuario y uno de asistente. El mensaje del asistente es lo que el modelo aprende a generar.
Formato JSONL para Batch API
La Batch API usa un formato JSONL diferente donde cada línea es una solicitud de 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 requeridos
- custom_id — Un identificador único para cada solicitud (requerido)
- method — Método HTTP, típicamente "POST" (requerido)
- url — Ruta del endpoint de API (requerido)
- body — El cuerpo de la solicitud, igual que una llamada de API regular (requerido)
Requisitos de formato
Sigue estas reglas para asegurar que tu archivo JSONL sea aceptado por OpenAI:
- Cada línea debe ser JSON válido — no se permiten errores de sintaxis
- Cada línea debe ser un objeto JSON (comienza con '{' y termina con '}')
- Los archivos de fine-tuning deben incluir un array "messages" en cada línea
- Cada mensaje debe tener 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)
- Sin comas finales, comentarios ni espacios en blanco extra entre líneas
- Las líneas vacías están permitidas y serán ignoradas
Errores comunes
Estos son los errores más frecuentes al crear archivos JSONL para OpenAI:
Usar un array JSON en lugar de JSONL
Incorrecto: envolver todos los objetos en [ ]. Los archivos JSONL deben tener un objeto por línea sin array envolvente.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Campos requeridos faltantes
Cada mensaje debe tener tanto "role" como "content". Omitir cualquiera causará que la validación falle.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Comas finales en JSON
JSON no permite comas finales después del último elemento en un array u objeto.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'Caracteres BOM o codificación incorrecta
Guarda tu archivo como UTF-8 sin BOM. Algunos editores de texto agregan caracteres BOM invisibles que rompen el parseo JSON.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Ejemplos de código
Así es como crear archivos JSONL para OpenAI programáticamente:
import jsontraining_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`);