Por Jerry Fan

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.

Valida tu archivo JSONL

Antes de subir el archivo a OpenAI, compruébalo con nuestro validador gratuito. Selecciona «Formato de fine-tuning de OpenAI» para comprobar los mensajes, los roles y las respuestas de assistant en cada línea, además de la sintaxis JSON.

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.

Formato requerido
{"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.

Formato requerido
{"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.

Incorrecto
[{"messages":[...]}, {"messages":[...]}]
Correcto
{"messages":[...]}
{"messages":[...]}

Omitir campos obligatorios

Cada mensaje debe incluir tanto "role" como "content". Si falta cualquiera de los dos, la validación fallará.

Incorrecto
{"messages":[{"role":"user"}]}
Correcto
{"messages":[{"role":"user","content":"Hello"}]}

Comas finales en JSON

JSON no admite una coma después del último elemento de un array u objeto.

Incorrecto
{"messages":[{"role":"user","content":"Hi",}]}
Correcto
{"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.

Incorrecto
\uFEFF{"messages":[...]}
Correcto
{"messages":[...]}

Ejemplos de código

Estos ejemplos muestran cómo crear archivos JSONL para OpenAI mediante código:

Python — Crear un archivo JSONL para fine-tuning
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")
JavaScript — Crear un archivo JSONL para fine-tuning
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`);

Ver y editar archivos JSONL de OpenAI

Usa nuestro visor JSONL online gratuito para revisar datasets de fine-tuning y archivos de la Batch API. Ofrece una vista en paralelo, resaltado de sintaxis y validación en tiempo real.

Preguntas frecuentes

Referencias