Exportación multiformato desde un único pipeline de datos: JSONL, COCO, YOLO y chunks para RAG

Has ingerido, limpiado, etiquetado y aumentado tu dataset. Ahora necesitas exportarlo — y el sistema destino determina el formato.

¿Ajustar un modelo de lenguaje? JSONL. ¿Entrenar un modelo de detección de objetos? YOLO o COCO. ¿Construir un pipeline RAG? Texto segmentado con metadatos. ¿Entrenar un clasificador de ML clásico? CSV. ¿Alimentar un agente de IA? JSON estructurado con esquemas de llamadas a herramientas.

El problema: la mayoría de las herramientas de preparación de datos exportan un formato. Quizás dos. Si tu proyecto requiere tres formatos de exportación — lo cual es común cuando un cliente quiere fine-tuning, RAG y un dashboard, todo desde los mismos datos fuente — terminas manteniendo tres scripts de exportación, cada uno con sus propios bugs específicos de formato y brechas de validación.

Esta guía cubre lo que cada formato requiere, dónde fallan y cómo exportar de manera confiable desde un único pipeline.

---

Requisitos de formato: lo que cada uno realmente necesita

JSONL para fine-tuning de LLM

JSONL (JSON Lines) es el formato estándar para ajustar modelos de lenguaje. Cada línea es un objeto JSON autocontenido que representa un ejemplo de entrenamiento.

Formato de fine-tuning por instrucciones:

{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}

Requisitos clave:

• JSON válido en cada línea — una línea mal formada puede hacer fallar el script de entrenamiento
• Esquema consistente en todas las líneas (mismos campos, mismos roles)
• Codificación UTF-8, sin BOM
• Sin comas finales, sin comentarios
• Conteo de tokens por ejemplo dentro de la ventana de contexto del modelo

Errores comunes:

• Comillas sin escapar en el contenido de texto (el error de formato JSONL número 1)
• Saltos de línea dentro de campos de contenido no escapados correctamente
• Esquemas mixtos (algunas líneas con prompt/completion, otras con messages)
• Campos vacíos o nulos que el framework de entrenamiento no maneja

Formato COCO para visión por computadora

El formato COCO (Common Objects in Context) usa un único archivo JSON que contiene metadatos de imagen, definiciones de categorías y anotaciones.

Estructura:

{
  "images": [{"id": 1, "file_name": "img001.jpg", "width": 1920, "height": 1080}],
  "categories": [{"id": 1, "name": "defect"}, {"id": 2, "name": "normal"}],
  "annotations": [{"id": 1, "image_id": 1, "category_id": 1, "bbox": [x, y, w, h], "area": 1234}]
}

Requisitos clave:

• Todos los IDs deben ser únicos y referenciados cruzadamente de forma correcta
• El formato de bounding box es [x, y, ancho, alto] (origen arriba-izquierda)
• El área debe coincidir con las dimensiones del bounding box
• Las dimensiones de imagen deben coincidir con las dimensiones reales del archivo
• Las máscaras de segmentación (si se usan) deben ser polígonos válidos

Errores comunes:

• Discrepancias de ID entre imágenes y anotaciones
• Bounding boxes que se extienden fuera de los límites de la imagen
• Anotaciones de área cero por errores de etiquetado
• IDs de categoría que no coinciden con la lista de categorías

Formato YOLO para detección de objetos

YOLO usa una estructura de directorios con un archivo de texto por imagen, cada línea representando una anotación.

Estructura:

<class_id> <x_center> <y_center> <width> <height>

Todas las coordenadas están normalizadas a 0-1 relativas a las dimensiones de la imagen.

Requisitos clave:

• Un archivo .txt por imagen, mismo nombre de archivo (extensión diferente)
• Coordenadas normalizadas a [0, 1]
• IDs de clase son enteros indexados desde cero
• Un archivo data.yaml que mapea IDs de clase a nombres

Errores comunes:

• Coordenadas no normalizadas (usando valores de píxeles en lugar de rango 0-1)
• Discrepancias de nombre de archivo entre archivos de imagen y archivos de anotación
• IDs de clase comenzando en 1 en lugar de 0
• Archivos de anotación faltantes para imágenes sin objetos (YOLO espera un archivo vacío, no un archivo faltante)

Texto segmentado para RAG

Los pipelines RAG (Generación Aumentada por Recuperación) necesitan texto dividido en chunks con metadatos para la recuperación.

Estructura típica:

{"chunk_id": "doc001_chunk_003", "text": "...", "metadata": {"source": "policy_v2.pdf", "page": 12, "section": "Termination"}}

Requisitos clave:

• Tamaño de chunk apropiado para el modelo de embedding (típicamente 256-512 tokens)
• Superposición entre chunks adyacentes (típicamente 10-20% del tamaño del chunk) para evitar dividir contexto relevante
• Metadatos de fuente preservados para citación
• Límites de chunk que no dividan oraciones o unidades semánticas

Errores comunes:

• Chunks que dividen a mitad de oración, produciendo fragmentos que se embeben mal
• Metadatos de fuente faltantes o incorrectos (hace imposible la citación)
• Inconsistencia en el tamaño de chunks (algunos de 50 tokens, otros de 2,000)
• Contenido de tablas segmentado como texto plano, perdiendo la estructura de filas y columnas

CSV para ML clásico

Formato tabular plano con una fila por ejemplo y una columna por característica.

Requisitos clave:

• Conteo de columnas consistente en todas las filas
• Escape adecuado de comas, comillas y saltos de línea dentro de valores de campos
• Fila de encabezado con nombres de columna descriptivos
• Tipos de datos consistentes por columna (sin mezclar cadenas y números)

Errores comunes:

• Campos de texto que contienen comas que rompen el parseo
• Representación inconsistente de nulos (cadena vacía vs. "null" vs. "N/A" vs. "None")
• Problemas de codificación en texto no ASCII
• Campos de texto grandes que hacen el CSV difícil de manejar para herramientas no textuales

JSON estructurado para agentes de IA

Los datos de entrenamiento de agentes requieren esquemas de llamadas a herramientas, pares acción-observación y registros estructurados de decisiones.

Requisitos clave:

• Los esquemas de llamadas a herramientas coinciden con las firmas reales de las herramientas
• Las secuencias acción-observación están ordenadas cronológicamente
• Cada punto de decisión incluye las acciones disponibles y la acción elegida
• Los casos de error y casos extremos están representados

---

El problema de los pipelines paralelos

Cuando cada formato requiere un pipeline de exportación separado, terminas manteniendo rutas de código paralelas:

Datos fuente → Script exportación JSONL → jsonl_output/
Datos fuente → Script exportación COCO  → coco_output/
Datos fuente → Script chunks RAG        → chunks_output/
Datos fuente → Script exportación CSV   → csv_output/

Cada script es una fuente potencial de:

Bugs de formato: Una comilla sin escapar en el exportador JSONL que solo se activa con ciertos registros. Un error de normalización de coordenadas en el exportador YOLO que produce valores fuera de rango para ciertas dimensiones de imagen.

Deriva de datos: Si actualizas los datos fuente y re-exportas, ¿los cuatro scripts recogen los cambios? Si el script JSONL procesa los datos actualizados pero el script COCO apuntaba a una copia en caché, tus exportaciones son inconsistentes.

Brechas de validación: Cada script puede o no incluir validación. El script JSONL podría validar la sintaxis JSON pero no verificar campos vacíos. El script COCO podría verificar referencias de ID pero no verificar dimensiones de bounding box.

Carga de mantenimiento: Cuatro scripts en cuatro formatos de archivo, cada uno con casos extremos específicos del formato, cada uno requiriendo actualizaciones cuando el esquema de datos fuente cambia.

Para proveedores de servicios que manejan múltiples proyectos de clientes, esto escala mal. Un bug de formato que afecta un proyecto probablemente afecta a otros — pero los scripts de cada proyecto son separados.

---

Validación de exportación: qué verificar

La validación debería ser un paso obligatorio, no opcional. Verifica estos puntos antes de considerar cualquier exportación como completa:

Verificaciones universales (todos los formatos)

• Conteo de registros: La exportación contiene el número esperado de registros
• Completitud: Sin campos faltantes, sin valores nulos donde se requieren valores
• Codificación: UTF-8 en todo, sin artefactos de codificación
• Deduplicación: Sin registros duplicados en la exportación
• Trazabilidad: Cada registro exportado se mapea a un registro fuente en el pipeline

Verificaciones específicas por formato

Verificaciones de compatibilidad downstream

• JSONL: Carga en el framework de entrenamiento objetivo y verifica que parsee sin errores
• COCO: Ejecuta la API de evaluación COCO en una muestra para verificar compatibilidad de formato
• YOLO: Carga en el script de entrenamiento YOLO objetivo y verifica que lea las anotaciones correctamente
• Chunks RAG: Embebe una muestra y verifica que la recuperación produzca resultados esperados

---

Arquitectura de exportación de pipeline único

La alternativa a los scripts paralelos es un único pipeline que produce múltiples formatos de exportación desde un modelo de datos:

Datos fuente → Pipeline unificado → Módulo de exportación → JSONL
                                                          → COCO
                                                          → YOLO
                                                          → Chunks RAG
                                                          → CSV
                                                          → JSON estructurado

Esta arquitectura tiene ventajas específicas:

Un modelo de datos: Todos los registros existen en una única representación. La exportación a cada formato es una transformación desde esa representación — no un pipeline separado con su propia lógica de parseo.

Un pase de validación: Valida los datos una vez en el modelo unificado. La validación específica del formato ocurre en el límite de exportación, no antes.

Exportaciones consistentes: Cuando los datos fuente cambian, cada formato de exportación refleja el cambio. Sin deriva entre formatos.

Registro de auditoría: Cada exportación se registra con el formato de exportación, marca de tiempo, conteo de registros y resultados de validación. Cuando un equipo de cumplimiento pregunta "¿qué exactamente había en el dataset de entrenamiento?", la respuesta está en un solo lugar.

---

Recomendaciones prácticas

1. Exporta temprano, valida inmediatamente. No esperes al día del fine-tuning para descubrir un problema de formato. Exporta una muestra de 100 registros en cada formato objetivo durante la configuración del pipeline.

2. Versiona tus exportaciones. Etiqueta cada exportación con un identificador de versión vinculado al estado del pipeline. Cuando re-exportas después de actualizaciones de datos, la versión anterior permanece disponible para comparación.

3. Incluye metadatos de exportación. Cada exportación debería incluir un manifiesto: conteo de registros, formato de exportación, versión del pipeline, resultados de validación y un hash de los datos exportados.

4. Prueba downstream. La validación más confiable es cargar la exportación en el sistema downstream y verificar que funciona. Un archivo JSONL que se ve correcto pero hace fallar el framework de entrenamiento tiene un problema de formato que la validación estática no detectó.

El módulo de exportación de Ertas Data Suite produce todos los formatos principales — JSONL, COCO, YOLO, CSV, texto segmentado y JSON estructurado — desde un único proyecto. Cada exportación incluye validación de esquema, verificaciones de compatibilidad downstream y un registro de auditoría completo. Cambiar entre formatos de exportación no requiere reconfigurar el pipeline — los mismos datos preparados se exportan a cualquier formato con un clic.

---

Conexión con el pipeline

La exportación es la etapa final del pipeline de preparación de datos. La calidad de cada etapa anterior — ingesta, limpieza, etiquetado y aumento — determina si el dataset exportado produce un modelo que funciona en producción.

Para la visión general del pipeline completo, consulta Cómo construir un pipeline de preparación de datos on-premise para fine-tuning de LLM.