Archivos de entrenamiento JSONL

Qué es

JSON es la forma más común de escribir datos estructurados como texto: objetos entre llaves, listas entre corchetes, y claves y valores entre comillas. JSONL, también llamado JSON Lines o JSON delimitado por saltos de línea, añade una regla adicional: cada línea del archivo es un valor JSON completo y válido, y las líneas están separadas por un salto de línea. Para los datos de entrenamiento, cada valor es un objeto que contiene un ejemplo.

train.jsonl

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"How do I reset my password?"},{"role":"assistant","content":"Open Settings → Security…"}]}

{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello! How can I help?","weight":0},{"role":"user","content":"Export my report as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF…","weight":1}]}

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"Can I change my plan mid-month?"},{"role":"assistant","content":"Yes. The difference is prorated…"}]}

…una línea por registro, sin comas entre líneas, sin [ ] alrededor

{ … }un objeto JSON completo = un registro de entrenamiento"messages"la conversación, en orden"role"quién lo dijo: sistema, usuario o asistente"weight"aprender esta respuesta (1) o solo leerla (0)\nun salto de línea finaliza el registro

Un archivo JSONL es una pila de objetos JSON independientes, uno por línea. Cada línea se puede leer, comprobar, contar o mezclar por sí sola, razón por la cual todos los principales servicios de ajuste fino lo utilizan.

Por qué lo utiliza el entrenamiento

Procesamiento en flujo continuo: un proveedor puede leer un archivo de varios gigabytes línea por línea en lugar de cargarlo y analizarlo por completo.
Independencia: los registros pueden contarse, mezclarse, dividirse en entrenamiento y validación, o muestrearse sin necesidad de analizar el resto del archivo.
Errores claros: un registro mal formado interrumpe una sola línea, y el mensaje de error puede identificarla («línea 482: fin de entrada inesperado»).
Anexable: añadir ejemplos significa añadir líneas; nada más cambia en el archivo.

Las reglas y cómo fallan los archivos

La especificación de JSON Lines tiene tres reglas: el archivo es UTF-8, cada línea es un valor JSON válido y cada línea termina con un carácter de salto de línea. Se recomienda encarecidamente terminar el archivo con un salto de línea. Casi todos los archivos de entrenamiento defectuosos incumplen una de estas reglas:

formas comunes en las que un archivo falla

✗ {"messages": [ ...          ← a pretty-printed object split over lines
     {"role": "user", ... } ]}
✗ [ {"messages": ...}, {"messages": ...} ]   ← a JSON array, not one object per line
✗ {"messages": [...]},        ← trailing comma
✗                             ← a blank line in the middle
✓ {"messages":[...]}          ← one complete object, then a line break

Los saltos de línea dentro del texto de un mensaje no suponen un problema, ya que JSON los almacena con caracteres de escape (como una barra invertida seguida de una n) dentro de la cadena. Lo que no debe ocurrir es un salto de línea real en medio de un objeto, que es exactamente lo que hace la «impresión legible» (pretty-printing) de un archivo para facilitar su lectura.

Mismo formato, diferentes estructuras

Todos los principales servicios de ajuste fino aceptan JSONL, pero cada uno define su propio esquema para el contenido de una línea. Algunos utilizan una lista messages con los roles system, user y assistant; otros colocan el prompt del sistema en un campo separado; algunos llaman a la lista contents y al rol del asistente model; algunos admiten un peso (weight) en cada mensaje del asistente para que las respuestas anteriores sirvan únicamente como contexto.

un ejemplo, tres formatos de proveedor

// chat "messages" (with an optional weight per assistant reply)
{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello!","weight":0},{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF.","weight":1}]}

// "contents" with user / model roles
{"contents":[{"role":"user","parts":[{"text":"Export as PDF"}]},{"role":"model","parts":[{"text":"Open the report, click Export → PDF."}]}]}

// separate system field
{"system":"You are a support assistant.","messages":[{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF."}]}

Cuando un formato no tiene un peso por mensaje, una conversación de varios turnos con varios objetivos se escribe como un registro por objetivo, cada uno cortado justo después de su respuesta objetivo. En esos registros, las respuestas anteriores del asistente también se aprenden, ya que el formato no tiene forma de marcarlas únicamente como contexto.

Ejemplo práctico: una conversación, dos archivos

Una conversación tiene cuatro mensajes: «Hola», un saludo, «Exportar mi informe como PDF» y las instrucciones. Solo las instrucciones están marcadas como objetivo.
Para un proveedor que admite pesos: una línea, con el saludo en weight: 0 y las instrucciones en weight: 1.
Para un proveedor sin pesos: también una línea, que termina en las instrucciones. Si el saludo también hubiera sido un objetivo, habría dos líneas —una que termina en el saludo y otra en las instrucciones— y el saludo se aprendería dos veces.
Ambos archivos contienen el mismo texto limpio y anonimizado. Solo difiere el formato contenedor.

Errores comunes

Aplicar un formato de impresión legible (pretty-printing) a un archivo de entrenamiento para que cada objeto ocupe varias líneas.
Guardar una matriz JSON de registros y nombrarla .jsonl.
Editar manualmente un archivo en una herramienta que cambia la codificación o añade comillas tipográficas, lo que corrompe el JSON.
Reutilizar el archivo de un proveedor con otro proveedor: el formato es el mismo, pero el esquema interno no lo es.

Referencias y lecturas adicionales

Las fuentes externas se abren en una pestaña nueva.