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.
¿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`);