What is JSONL?

Un formato de datos basado en texto donde cada línea es un objeto JSON válido, ampliamente utilizado para estructurar datasets de fine-tuning, logging y pipelines de datos en streaming en flujos de trabajo de IA/ML.

Definition

JSONL (JSON Lines), a veces llamado JSON delimitado por saltos de línea (NDJSON), es un formato de datos ligero en el que cada línea de un archivo es un objeto JSON autocontenido y válido terminado por un carácter de nueva línea. A diferencia del JSON estándar, que envuelve un dataset completo en un solo array, JSONL trata cada línea de forma independiente. Esta estructura orientada a líneas lo hace trivialmente transmisible por streaming: un parser puede leer, validar y procesar un registro a la vez sin cargar el archivo completo en memoria.

En el contexto de IA y aprendizaje automático, JSONL se ha convertido en el formato dominante para datasets de fine-tuning. Cada línea típicamente representa un solo ejemplo de entrenamiento — por ejemplo, un par de instrucción-respuesta, una conversación de chat con múltiples turnos, o una muestra de clasificación con texto de entrada y una etiqueta. OpenAI, Mistral, Llama y la mayoría de los principales frameworks de fine-tuning aceptan JSONL como su formato de entrada principal, convirtiéndolo en una lingua franca para datos de entrenamiento.

La simplicidad del formato es su mayor fortaleza. No requiere definición de esquema, ni herramientas especiales, ni análisis binario — cualquier editor de texto, lenguaje de scripting o herramienta de línea de comandos Unix puede crear, inspeccionar y manipular archivos JSONL. Esta baja barrera de entrada lo hace ideal para la curación iterativa de datasets, donde los científicos de datos frecuentemente agregan, eliminan, filtran y transforman ejemplos de entrenamiento.

Why It Matters

La calidad de un modelo ajustado es directamente proporcional a la calidad de sus datos de entrenamiento, y JSONL es el formato en el que viven esos datos. Hacer bien la preparación de JSONL — esquema consistente, texto limpio, categorías balanceadas, distribución de longitud apropiada — es posiblemente más importante que cualquier elección de hiperparámetro. Un archivo JSONL bien estructurado también permite la reproducibilidad: sirve como un registro auditable de exactamente con qué se entrenó el modelo, lo cual es crítico para el cumplimiento en industrias reguladas. Además, debido a que los archivos JSONL están orientados a líneas, se integran naturalmente con el control de versiones (los diffs de git son significativos) y los pipelines de datos (ingestión por streaming, procesamiento map-reduce).

How It Works

Un archivo JSONL es simplemente un archivo de texto UTF-8 donde cada línea es un objeto JSON completo. Para fine-tuning, un esquema común usa tres campos: "instruction" (el prompt o pregunta), "input" (contexto adicional opcional) y "output" (la respuesta deseada del modelo). Los datasets estilo chat usan un array "messages" que contiene objetos con campos "role" y "content". Durante el fine-tuning, el framework de entrenamiento lee el archivo línea por línea, tokeniza cada ejemplo y alimenta lotes al modelo. La validación típicamente implica verificar que cada línea se analice como JSON válido, que los campos requeridos estén presentes y que ningún ejemplo exceda la longitud máxima de contexto del modelo.

jsonl

{"instruction": "What is your return policy?", "output": "We offer a 30-day no-questions-asked return policy for all unused items. Simply initiate a return from your account dashboard and ship the item back with the prepaid label we provide."}
{"instruction": "How do I reset my password?", "output": "Navigate to Settings > Security > Change Password. Enter your current password, then your new password twice. You will receive a confirmation email once the change is saved."}
{"instruction": "Can I upgrade my plan mid-cycle?", "output": "Yes — upgrades take effect immediately. You will be charged a prorated amount for the remainder of the current billing cycle, and the new rate applies from the next cycle onward."}

Un dataset de fine-tuning JSONL de ejemplo con pares instrucción-salida para un modelo de soporte al cliente.

Example Use Case

Un equipo de soporte al cliente exporta 5,000 tickets resueltos de su plataforma de helpdesk, cada uno conteniendo la pregunta del cliente y la respuesta verificada del agente. Un script de Python transforma cada ticket en una línea JSONL con campos "instruction" y "output", filtra los ejemplos más cortos de 20 tokens o más largos de 2,048 tokens, y deduplica las entradas casi idénticas. El archivo JSONL resultante de 4,200 líneas se sube a Ertas Studio, donde impulsa un trabajo de fine-tuning que produce un modelo capaz de redactar respuestas iniciales que coinciden con el estilo y los estándares de precisión del equipo.

Key Takeaways

JSONL almacena un objeto JSON por línea, haciéndolo transmisible por streaming y fácil de procesar incrementalmente.
Es el formato de entrada estándar para datasets de fine-tuning en todos los principales frameworks de LLM.
La calidad de los datos en el archivo JSONL es el factor más importante que determina el éxito del fine-tuning.
La estructura orientada a líneas funciona bien con el control de versiones, herramientas Unix y pipelines de streaming.
La validación — verificaciones de esquema, filtrado por longitud, deduplicación — siempre debe realizarse antes del entrenamiento.

How Ertas Helps

Ertas Studio acepta JSONL como su formato principal de dataset para trabajos de fine-tuning. La plataforma incluye un validador de datasets integrado que verifica la conformidad del esquema, señala ejemplos excesivamente largos o cortos, detecta duplicados y proporciona un puntaje de calidad antes de que comience el entrenamiento. Para equipos que aún no tienen un archivo JSONL, Ertas ofrece plantillas de datasets y utilidades de conversión que transforman exportaciones de CSV, Parquet y logs de chat en JSONL correctamente formateado — bajando la barrera desde datos crudos hasta un dataset listo para entrenamiento.