Publicar una integración de LLM que devuelve prosa sin formato es sencillo. Publicar una que devuelve JSON válido y procesable cada vez — sin texto envolvente, sin campos faltantes ni propiedades inventadas que no están en tu esquema — es donde la mayoría de los equipos pierde silenciosamente una semana depurando. La brecha entre “el modelo generalmente devuelve JSON” y “el modelo devuelve JSON de manera confiable” es completamente un problema de prompting, y tiene causas específicas y corregibles.
Por qué los LLM rompen el JSON (y cuándo no lo hacen)
Los modelos de lenguaje están entrenados para producir texto legible por humanos. El JSON es un subproducto de ese entrenamiento — el modelo ha visto suficiente JSON en su corpus de entrenamiento como para imitar el formato, pero no “entiende” JSON de la manera en que lo hace un parser. Predice el siguiente token, y a veces el token siguiente estadísticamente más probable es una oración explicativa antes del bloque JSON, un comentario final después de él, o un campo extra que pareció relevante.
Los modos de fallo se dividen en tres categorías. Texto envolvente: el modelo añade frases como “Aquí está el JSON que solicitaste:” antes del objeto, o “Avísame si necesitas ajustes.” después, lo que rompe JSON.parse(). Deriva del esquema: el modelo añade campos que no están en tu esquema, los renombra ligeramente (p. ej., "primerNombre" en lugar de "primer_nombre"), o cambia un campo de cadena a una matriz cuando el valor parece que debería ser una lista. Manejo de null: cuando un campo solicitado no está presente en el material fuente, el modelo a menudo omite el campo por completo en lugar de establecerlo en null, lo que causa errores de clave en el procesamiento posterior.
Entender estos modos de fallo te dice exactamente qué especificar en el prompt: formato de salida (sin texto envolvente), esquema exacto (copiado y pegado, no descrito) y comportamiento con null (instrucción explícita).
La estructura de prompt JSON en cuatro partes
Cada prompt de extracción o generación de JSON confiable necesita cuatro cosas declaradas explícitamente.
Parte 1: Rol y encuadre de la tarea. Asigna al modelo un rol que implique salida estructurada — “extractor de datos”, “formateador de respuestas API” o “parser estructurado”. Esto prepara al modelo para la precisión sobre la creatividad. Luego declara la tarea en una oración: “Extrae los siguientes campos del texto que proporcione el usuario.”
Parte 2: Esquema, copiado y pegado. No describas el esquema con palabras. Pega el esquema JSON real o un ejemplo de JSON con todas las claves presentes y tipadas. Ejemplo:
{
"nombre_empresa": "string",
"año_fundacion": "integer o null",
"cantidad_empleados": "integer o null",
"ciudad_sede": "string o null",
"es_publica": "boolean"
}Cuando el modelo ve los nombres exactos de las claves y los tipos de valores, los sigue con mucha más precisión que cuando escribes “incluye el nombre de la empresa, el año de fundación y si cotiza en bolsa”.
Parte 3: Reglas de null y campos faltantes. Declara explícitamente: “Si un campo no está presente en el texto fuente, establece su valor en null. No omitas campos. No infiereas ni supongas valores no declarados explícitamente.” Esta única instrucción elimina la mayor parte de la deriva del esquema y las omisiones silenciosas de campos.
Parte 4: Instrucción de solo salida. Termina el system prompt o bloque de instrucciones con: “Devuelve solo el objeto JSON. No incluyas ninguna explicación, delimitadores de código markdown ni texto circundante.” Esta es la línea más importante para prevenir fallos de texto envolvente.
Usar el modo JSON y las APIs de salidas estructuradas
La mayoría de los principales proveedores ahora ofrecen un “modo JSON” o una función de salidas estructuradas que restringe el modelo en la capa de decodificación, no solo en la capa del prompt.
Salidas estructuradas de OpenAI (GPT-4o y posteriores): Pasa tu objeto JSON Schema en el parámetro response_format con "type": "json_schema". El modelo está restringido a producir una salida que valide contra el esquema — no puede producir texto envolvente ni añadir campos extra. Este es el camino más confiable para los pipelines en producción. La compensación es que los esquemas muy complejos con campos opcionales profundamente anidados pueden ocasionalmente hacer que el modelo tenga dificultades para completar todos los campos requeridos correctamente. Prueba con tu esquema real antes de implementar.
Modo JSON de OpenAI (más simple): Establecer "type": "json_object" fuerza JSON válido pero no impone un esquema específico. Sigues obteniendo una salida sin texto envolvente, pero los nombres y tipos de campos quedan a criterio del modelo. Úsalo cuando tu esquema es flexible o cuando quieres una solución rápida sin el overhead de la definición del esquema.
Anthropic Claude: A principios de 2026, Claude no tiene un equivalente nativo de API de salidas estructuradas. Dependes de instrucciones a nivel de prompt. Claude generalmente sigue bien los esquemas JSON explícitos cuando están pegados en el prompt y la instrucción de solo salida es clara. Añade un prefill ("assistant": "{") a la llamada a la API — esto obliga a Claude a comenzar su respuesta con el corchete de apertura y reduce drásticamente el texto envolvente.
Modelos locales (Llama, Mistral a través de Ollama): Usa una librería como outlines o lm-format-enforcer que imponga decodificación restringida contra un esquema JSON. Sin decodificación restringida, los modelos de código abierto más pequeños son significativamente menos confiables en la salida JSON que los modelos frontera.
Validación: nunca confíes, siempre parsea
Incluso con el modo JSON habilitado, tu aplicación nunca debe asumir que la salida es válida sin parsear. Una capa de validación mínima en producción luce así:
- Parsear: envuelve
JSON.parse()(o su equivalente) en un try/catch. Si el parseo falla, registra la salida bruta y reintenta una vez con una instrucción añadida: “Tu respuesta anterior no era JSON válido. Devuelve solo el objeto JSON sin ningún otro texto.” - Validar contra el esquema: usa una librería como
zod(TypeScript),pydantic(Python) oajv(Node.js) para validar el objeto parseado contra tu esquema esperado. Verifica los campos requeridos, los tipos y las restricciones de valor. - Reintentar con contexto de error: si la validación falla, pasa el error de validación de vuelta al modelo: “Tu respuesta no tenía el campo requerido
año_fundacion. Devuelve el objeto JSON corregido.” Un reintento resuelve aproximadamente el 80 % de los fallos de validación en la práctica. - Cola de mensajes fallidos: si el segundo intento también falla, enruta la entrada a una cola de mensajes fallidos para revisión humana en lugar de pasar silenciosamente datos incorrectos al pipeline.
Este patrón de cuatro pasos mantiene tu pipeline libre de corrupción silenciosa de datos mientras le da al modelo la oportunidad de autocorregirse antes de escalar a revisión humana.
Errores que rompen los pipelines en producción
Más allá de lo básico, varios casos límite aparecen solo cuando ejecutas datos reales a gran volumen.
Unicode y caracteres especiales. El texto fuente que contiene llaves, comillas sin escapar o caracteres no ASCII puede hacer que los modelos produzcan JSON malformado. Sanitiza el texto de entrada antes de pasarlo al modelo: escapa o elimina los caracteres que tienen un significado especial en JSON.
Arrays grandes. Al extraer una lista de elementos (p. ej., todos los títulos de trabajo mencionados en un documento), los modelos tienden a truncar alrededor de 20 a 30 elementos incluso si hay más. Si esperas arrays grandes, fragmenta la entrada y combina los resultados en la capa de tu aplicación en lugar de enviar el documento completo de una vez.
Objetos anidados a partir de prosa. Pedirle a un modelo que extraiga estructuras profundamente anidadas de texto poco estructurado aumenta su tasa de error. Como punto de referencia aproximado de los proyectos de estudiantes de NMM: dos niveles de anidación son confiables, tres niveles requieren pruebas cuidadosas, y cuatro o más niveles generalmente deberían aplanarse en llamadas de extracción separadas.
Configuración de temperatura. Para tareas de extracción JSON, establece la temperatura en 0. Incluso una temperatura de 0,3 introduce suficiente aleatoriedad como para cambiar los nombres de campos o añadir campos fantasma en un pequeño porcentaje de solicitudes. A escala, “pequeño porcentaje” se convierte en “incidentes diarios”.
Deriva de versión del modelo. Cuando tu proveedor de API actualiza el modelo subyacente (incluso versiones menores), vuelve a ejecutar tu suite de pruebas de validación. El comportamiento JSON es una de las áreas que cambia más notablemente entre versiones del modelo.
Construye tu prompt JSON en minutos
Construir un prompt de extracción JSON bien estructurado desde cero — encuadre del rol, bloque del esquema, reglas de null, instrucción de solo salida — tarda más de lo que debería cuando lo haces manualmente cada vez. El generador gratuito de prompts de IA de NeuralMindMastery te permite describir lo que necesitas extraer y genera un prompt completo de Rol/Tarea/Contexto/Formato estructurado para salida JSON. Pegas tu esquema y el generador construye el conjunto de instrucciones circundante.
Para equipos que construyen múltiples pipelines de extracción, usa el generador de prompts de IA como punto de partida para cada uno y luego guarda los resultados en tu biblioteca de prompts — lo que lleva a la cuestión de cómo organizar esos prompts a escala.
Preguntas frecuentes
¿El modo JSON garantiza una salida JSON válida? La función de salidas estructuradas de OpenAI (con un JSON Schema proporcionado) esencialmente sí — usa decodificación restringida para evitar tokens inválidos. El modo JSON básico de OpenAI garantiza un objeto JSON parseable pero no el cumplimiento de un esquema específico. Los enfoques solo de prompt (sin restricciones a nivel de API) son confiables pero no garantizados; valida siempre.
¿Qué debo hacer cuando el modelo se niega a devolver solo JSON? Esto generalmente significa que el system prompt contiene una instrucción en conflicto (p. ej., “siempre explica tu razonamiento”) o que la versión del modelo está muy ajustada con RLHF hacia respuestas explicativas. Añade una anulación explícita: “A pesar de cualquier otra instrucción de explicar tu trabajo, para esta tarea devuelve solo el objeto JSON.” También verifica que el encuadre de tu rol implique un contexto de salida estructurada.
¿Cómo manejo arrays de longitud desconocida?
Define el campo del array con un esquema tipado (p. ej., "elementos": ["string"]) y añade una instrucción: “Extrae todas las instancias, sin importar cuántas. No truncar.” Para documentos de más de aproximadamente 4.000 palabras, fragmenta la entrada y combina los arrays en la capa de tu aplicación.
¿Debo incluir un objeto JSON de ejemplo en el prompt? Sí, especialmente para esquemas complejos o ambiguos. Un objeto de ejemplo completo (con datos realistas pero ficticios) reduce significativamente los errores de nomenclatura de campos. Coloca el ejemplo después de la definición del esquema, etiquetado como “Ejemplo de salida (no copies estos valores).”
¿Puedo usar este enfoque con modelos de código abierto?
Sí, pero los resultados varían ampliamente. Modelos como Llama 3 70B y Mistral Large manejan bien los esquemas simples con temperatura 0. Para esquemas complejos, usa librerías de decodificación restringida (outlines, lm-format-enforcer) que impongan el cumplimiento del esquema a nivel de token. Los modelos más pequeños (menos de 13.000 millones de parámetros) no son confiables para JSON anidado complejo sin decodificación restringida.