JSON fiable con LLM: esquemas, validación y reintentos
Obtener JSON válido de un LLM exige más que pedirlo bien. Usa esquemas, salida estructurada, validación y reintentos, y evita los fallos habituales.
En este artículo
- ¿Por qué los modelos rompen el JSON?
- Paso 1: describe la salida con precisión en el prompt
- Paso 2: usa la salida estructurada de la API
- Paso 3: valida todo, incluso con esquema obligatorio
- Paso 4: reintenta con el error, no a ciegas
- ¿Dónde va el razonamiento en una respuesta JSON?
- Errores comunes al diseñar esquemas de salida
- ¿Basta alguna vez con el prompt?
Para obtener JSON fiable de un modelo de lenguaje, define la estructura como un JSON Schema, usa la función de salida estructurada del proveedor cuando exista, valida cada respuesta en el código y reintenta con el error de validación cuando falle. La redacción del prompt te lleva casi hasta el final; el último porcentaje de fiabilidad viene de la API y de tu propia validación.
La distinción importa porque "casi" no basta para el código. Un parser que falla en el 2% de las respuestas supone una función rota para alguien cada pocos minutos a escala.
¿Por qué los modelos rompen el JSON?
Antes de arreglarlo conviene saber qué falla realmente. Más o menos en el orden en que los vas a encontrar:
- Bloques de markdown. El modelo devuelve
```json ... ```porque los modelos de chat están entrenados para presentar bien el código. - Introducciones charlatanas. "¡Claro! Aquí tienes el JSON que pediste:" seguido del objeto.
- Claves incorrectas o inventadas.
customerNameen lugar decustomer_name, o un campo extranotesque nunca pediste. - Tipos incorrectos.
"price": "19.99"como cadena,"count": "three", un solo objeto donde querías un array. - Truncamiento. La respuesta alcanza el límite máximo de tokens y se corta a mitad del objeto.
- Sinsentidos sintácticamente válidos. JSON perfecto, contenido erróneo: una fecha con formato equivocado, un teléfono alucinado,
nulldonde el valor estaba justo en la entrada.
Las funciones de salida estructurada eliminan los cinco primeros, en su mayoría. Nada elimina el sexto salvo un buen prompt, anclaje en datos y comprobaciones.
Paso 1: describe la salida con precisión en el prompt
Incluso con esquema obligatorio, el prompt es donde explicas qué significa cada campo. Un esquema dice que due_date es una cadena; solo el prompt puede decir que debe ser ISO 8601 y que las fechas relativas se resuelven con la fecha de envío del correo.
Un prompt débil:
Extrae los datos de la factura de este correo como JSON.
Uno más sólido:
Extrae los datos de la factura del correo de abajo.
Devuelve un único objeto JSON con exactamente estas claves:
- "vendor": cadena, la empresa que emitió la factura
- "invoice_number": cadena, tal como está escrito (conserva los ceros a la izquierda)
- "total": número, en la moneda de la factura, sin símbolo de moneda
- "currency": cadena, código ISO 4217 como "USD" o "EUR"
- "due_date": cadena con formato YYYY-MM-DD, o null si no se indica
Si un valor no aparece en el correo, usa null. No adivines.
Devuelve solo el objeto JSON, sin markdown y sin explicaciones.
<email>
{{email_text}}
</email>
Dos detalles pesan mucho aquí. "Conserva los ceros a la izquierda" evita que el modelo convierta, "con buena intención", 00417 en 417. Y "usa null, no adivines" le da una salida legítima. Sin una opción de null explícita, un modelo sometido a un campo obligatorio inventará un valor verosímil en lugar de dejarlo vacío.
Paso 2: usa la salida estructurada de la API
La mayoría de los grandes proveedores ofrecen ya alguna forma de restringir la salida a un esquema. Los nombres y los detalles varían y cambian con el tiempo, así que consulta la documentación actual, pero las opciones principales son estas:
- OpenAI tiene un JSON mode básico que garantiza JSON sintácticamente válido, y Structured Outputs, donde pasas un JSON Schema con modo estricto y la salida queda restringida para coincidir con él.
- Google Gemini permite fijar el tipo MIME de la respuesta como JSON y aportar un esquema de respuesta.
- Anthropic permite definir una herramienta con un esquema de entrada y hacer que Claude la llame, lo que produce argumentos con la forma del esquema; su documentación también describe soporte nativo de salida estructurada.
La distinción importante es JSON mode frente a esquema obligatorio. El JSON mode solo promete que el texto se puede parsear. Tus claves aún pueden estar mal. El esquema obligatorio (que suele lograrse con decodificación restringida, que limita qué tokens puede generar el modelo a continuación) promete la forma.
Un esquema para el ejemplo de la factura:
{
"type": "object",
"properties": {
"vendor": { "type": ["string", "null"] },
"invoice_number": { "type": ["string", "null"] },
"total": { "type": ["number", "null"] },
"currency": { "type": ["string", "null"], "enum": ["USD", "EUR", "GBP", null] },
"due_date": { "type": ["string", "null"], "description": "YYYY-MM-DD" }
},
"required": ["vendor", "invoice_number", "total", "currency", "due_date"],
"additionalProperties": false
}
Fíjate en los tipos que admiten null. En los modos estrictos, todos los campos suelen ser obligatorios, así que "opcional" hay que expresarlo como "obligatorio pero puede ser null". Fíjate también en additionalProperties: false, que evita campos sorpresa. Los modos estrictos suelen admitir solo un subconjunto de JSON Schema, así que comprueba qué palabras clave se permiten antes de construir algo elaborado.
Si usas Python o TypeScript, define el esquema como un modelo de Pydantic o un esquema de Zod y genera el JSON Schema a partir de él. Así la misma definición valida la respuesta y ambas no pueden desincronizarse.
Paso 3: valida todo, incluso con esquema obligatorio
El esquema obligatorio garantiza la estructura. No garantiza:
- que
due_datesea una fecha real (el 30 de febrero es una cadena válida), - que
totalcoincida con la suma de las líneas, - que
vendoraparezca en algún lugar del correo original, - que el modelo no haya omitido la tercera línea de cinco.
Escribe las comprobaciones que importan en tu dominio. Parsea las fechas. Comprueba que los totales no sean negativos. En tareas de extracción, comprueba que las cadenas extraídas aparezcan de verdad en la entrada; esta única prueba detecta una cantidad sorprendente de alucinaciones.
Paso 4: reintenta con el error, no a ciegas
Cuando la validación falle, no reenvíes la misma solicitud esperando que salga bien. Devuelve el error:
Tu respuesta anterior no superó la validación:
- "due_date": "March 3rd" no cumple el formato YYYY-MM-DD
- "currency": "dollars" no es uno de USD, EUR, GBP
Devuelve solo el objeto JSON corregido.
Los modelos corrigen bien errores concretos y con nombre. Limita los reintentos a uno o dos, registra cada fallo y revisa los registros cada semana. Los fallos repetidos en el mismo campo suelen indicar que el prompt o el esquema no están claros, no que el modelo sea inestable. Bibliotecas como Instructor (Python) envuelven este bucle de validar y reintentar, pero el patrón es lo bastante simple como para escribirlo tú mismo.
Para roturas solo de sintaxis en proveedores sin esquema obligatorio, un parser tolerante que elimine los bloques y el texto sobrante antes de JSON.parse resuelve los casos más comunes. Trátalo como un recurso de reserva, no como una estrategia.
¿Dónde va el razonamiento en una respuesta JSON?
Si la tarea requiere criterio (una clasificación con justificación, una puntuación de riesgo), pon un campo de razonamiento antes del campo de decisión:
{
"evidence": "El cliente menciona un cargo duplicado en la factura de marzo.",
"category": "billing",
"confidence": "high"
}
Los modelos generan los campos en orden. Una decisión escrita primero se justifica después en lugar de apoyarse en el razonamiento. Lo vemos con más detalle en chain-of-thought prompting explicado.
La otra cara: los campos de razonamiento cuestan tokens en cada llamada. Para extracciones simples, déjalos fuera.
Errores comunes al diseñar esquemas de salida
Anidación profunda sin motivo. Tres niveles de objetos donde bastaría una lista plana. Cada nivel es otro lugar donde el modelo puede colocar mal un valor.
Campos de texto libre que deberían ser enums. Si el código posterior se bifurca según status, hazlo un enum. Si no, obtendrás "Pending", "pending", "In progress" y "awaiting review" para lo mismo.
Nombres de campo ambiguos. date en una factura podría ser la fecha de emisión, de vencimiento o de pago. Llámalo due_date y descríbelo.
Pedir demasiado en una sola llamada. Un esquema de cuarenta campos extraídos de un contrato de veinte páginas invita a las omisiones. Divídelo: una llamada por sección, o una llamada para localizar los pasajes relevantes y otra para extraer de ellos.
Olvidar el caso vacío. ¿Cuál debe ser la salida si el correo no es una factura? Añade un booleano is_invoice o permite un resultado vacío, o el modelo extraerá una factura de una invitación a comer.
¿Basta alguna vez con el prompt?
Para prototipos, scripts que ejecutas a mano o modelos sin soporte de salida estructurada, sí. Una descripción precisa del formato, un ejemplo de la salida exacta y un parser defensivo te llevan a una fiabilidad alta. Para cualquier cosa de cara al usuario, usa el esquema obligatorio donde esté disponible y valida siempre.
La habilidad de fondo es la misma en todos los casos: describir la salida con tanta precisión que solo haya una manera razonable de rellenarla. El tema de salida estructurada entrena esas decisiones, y si el JSON que produces es una llamada a una herramienta y no una respuesta final, las llamadas a herramientas y los agentes de IA retoman el tema desde aquí. Para la extracción basada en documentos fuente, consulta qué es RAG.
Preguntas frecuentes
¿Cómo fuerzo a un LLM a devolver JSON válido?
Usa la función de salida estructurada del proveedor con un JSON Schema cuando exista, porque restringe la generación al esquema. Después valida igualmente el resultado en el código y reintenta o repara cuando la validación falle.
¿Cuál es la diferencia entre JSON mode y structured outputs?
El JSON mode hace que el modelo produzca JSON sintácticamente válido, pero no garantiza tus claves ni tus tipos. Los structured outputs con un esquema estricto limitan la salida para que coincida con el esquema que aportas.
¿Por qué mi LLM envuelve el JSON en bloques de código markdown?
Los modelos ajustados para chat están entrenados para formatear bien el código para las personas. Dile al modelo que devuelva solo el objeto JSON sin formato, o usa un modo de salida estructurada, y elimina los bloques en tu parser por precaución.
¿Debo validar el JSON de un LLM aunque use un esquema?
Sí. Un esquema garantiza la forma, no la verdad. El JSON puede ser perfectamente válido y aun así contener una fecha incorrecta, un valor inventado o un campo vacío donde sí había datos.
- #salida estructurada
- #JSON
- #JSON schema
- #validación