Salidas estructuradas con IA: cómo definir, forzar y validar el formato sin perder fiabilidad

1. Diseña el esquema a partir del uso downstream

Una salida estructurada es una respuesta del modelo ajustada a una forma de datos prevista, como un objeto JSON con campos definidos. Su objetivo no es solo que la respuesta «parezca JSON»: es que el sistema que la recibe pueda interpretarla de manera consistente. Para lograrlo, empieza por el consumidor downstream y trabaja hacia atrás: identifica qué campos necesita, qué hará con ellos y qué debe ocurrir cuando la entrada no contenga la información solicitada.

Mantén el esquema tan pequeño como permita el caso de uso. Para cada campo, documenta el tipo, si es obligatorio, los valores permitidos, las unidades y la procedencia esperada. Decide también cómo representar datos ausentes. Un valor nulo, una cadena vacía y un campo omitido pueden tener significados distintos; no los intercambies sin una regla explícita. Si una fecha debe alimentar una base de datos, por ejemplo, prefiere un formato normalizado y una zona horaria definida en vez de aceptar expresiones como «el viernes».

Separa la estructura de las instrucciones semánticas. El esquema puede exigir que `fecha` sea una cadena, pero eso no impide por sí solo que el modelo invente una fecha. Las descripciones de campos y el prompt pueden orientar la extracción, pero la aplicación debe establecer qué evidencia acepta y qué resultado usar cuando no la encuentra. Una opción segura es admitir un estado explícito como `no_encontrado` o un campo de evidencia, en lugar de forzar una respuesta afirmativa.

La documentación de Azure OpenAI describe el uso de una definición de esquema JSON en una llamada de inferencia y muestra ejemplos con Pydantic y Zod. La documentación de Gemini también presenta respuestas en JSON ajustadas a un esquema y ejemplos de uso de modelos de datos. Esas capacidades documentadas son específicas de las API y configuraciones descritas; no prueban que todos los esquemas, modelos o proveedores acepten exactamente las mismas restricciones.

2. Elige el mecanismo de salida según la tarea y el proveedor

Hay tres enfoques habituales, pero no son equivalentes. El prompting puro pide al modelo que devuelva un formato concreto mediante instrucciones en lenguaje natural. Puede bastar en un prototipo o cuando la salida es solo para lectura humana, pero el formato puede degradarse: aparecen explicaciones fuera del JSON, claves inesperadas o valores de tipos incorrectos. Si el resultado alimenta código, trátalo como una opción menos controlable y valida siempre la respuesta.

El modo JSON solicita una respuesta JSON. La documentación de Azure distingue ese modo de las salidas estructuradas con esquema: el primero garantiza JSON válido, pero no garantiza que se cumpla estrictamente el esquema proporcionado. Por tanto, que una respuesta se pueda analizar como JSON no demuestra que tenga las claves, tipos o restricciones que necesita la aplicación.

Las salidas estructuradas con esquema permiten proporcionar una definición para guiar la forma de la respuesta. La documentación de Azure muestra este mecanismo en campos de formato de respuesta, así como ejemplos de integración con Pydantic y Zod. Gemini documenta también la configuración de una respuesta JSON basada en esquema y ejemplos de extracción y clasificación. La disponibilidad concreta depende de la API, el modelo y la configuración elegidos: comprueba la documentación vigente del endpoint que realmente usarás, en vez de asumir que dos productos con nombres parecidos tienen idéntico comportamiento.

Las llamadas a funciones o herramientas sirven cuando el modelo debe proponer argumentos para una operación disponible en la aplicación, como consultar un pedido. No equivalen a ejecutar la función ni a verificar que la acción sea segura: el servidor debe validar los argumentos y aplicar sus propios controles antes de actuar. En el uso de salidas estructuradas para llamadas a funciones descrito por Azure, la documentación advierte que no se admiten llamadas paralelas y recomienda desactivarlas en esa configuración. No extrapoles esa limitación a otras API sin confirmarlo.

Como regla de selección: usa una salida con esquema cuando el objetivo principal sea producir un objeto ajustado a una definición; usa una llamada a función cuando el modelo deba seleccionar una operación y proponer sus argumentos; y reserva el prompting puro para contextos de menor riesgo o para tareas en las que una validación local estricta compense la menor coerción. En cualquier caso, la respuesta debe pasar por controles de aplicación antes de llegar al sistema downstream.

3. Valida la estructura antes de procesar la respuesta

La primera barrera es analizar la respuesta con un parser del formato esperado. Para JSON, el parser debe rechazar texto inválido, valores truncados y contenido que no pueda convertirse en un objeto. Si el proveedor entrega una respuesta ya analizada por un SDK, comprueba igualmente el estado de finalización, las negativas y los campos que puedan indicar una respuesta incompleta; no des por hecho que siempre se recibió un resultado utilizable.

La segunda barrera es validar contra un esquema local. JSON Schema permite expresar tipos, campos obligatorios, enumeraciones, restricciones de longitud y reglas para propiedades adicionales, entre otras condiciones. Las bibliotecas de validación pueden convertir esas reglas en errores accionables antes de que la salida llegue a una base de datos o a una API. La implementación concreta depende del lenguaje y de la versión del esquema: verifica la compatibilidad de la biblioteca elegida con las palabras clave y dialecto que usa tu contrato, y prueba la combinación en integración continua.

No copies sin revisión el esquema que acepta el proveedor como contrato definitivo de la aplicación. El proveedor puede aceptar solo un subconjunto de las reglas, o transformar un modelo de datos de una biblioteca en una definición compatible con su API. Mantén una fuente de verdad de tu contrato y, si el proveedor exige una representación reducida, genera o adapta el esquema de llamada sin eliminar las reglas críticas de validación local.

La validación debe ser estricta en los límites del sistema. Rechaza propiedades inesperadas si podrían alterar el comportamiento; convierte tipos solo cuando la conversión sea inequívoca y esté documentada; y evita «arreglar» automáticamente valores dudosos. Si un campo debe ser un entero, convertir `12,5` en `12` no es una reparación inocua: puede cambiar el significado. Guarda el error, el identificador de la solicitud y la versión del esquema para poder diagnosticar fallos sin aceptar silenciosamente datos defectuosos.

4. Comprueba el contenido y representa la incertidumbre

Una respuesta estructuralmente correcta puede ser semánticamente falsa. Para medir esa diferencia, evalúa los campos frente a la entrada original y a las fuentes de referencia disponibles, no frente a la fluidez de la explicación del modelo. En extracción, conserva evidencia textual suficiente para localizar el dato en el documento. En clasificación, guarda la regla o señal que permitió asignar la categoría. En enriquecimiento, identifica qué valores proceden de la entrada y cuáles dependen de una fuente externa autorizada.

Diseña una representación explícita para la incertidumbre. Según el caso, puede ser un valor nulo acompañado por un estado, una lista de candidatos o una marca de revisión. Evita pedir un porcentaje de confianza sin definir qué significa y cómo se calibrará: una cifra generada por el propio modelo no es, por sí sola, una probabilidad comprobada. Si utilizas una puntuación, mídela con un conjunto etiquetado y decide los umbrales a partir del coste de errores y revisiones, no por intuición.

El escalado humano debe ser una ruta normal del pipeline, no una excepción improvisada. Envía a revisión los casos ambiguos, los que carezcan de evidencia, los que infrinjan reglas de negocio y los que impliquen una decisión de alto impacto. El revisor necesita ver la entrada, la salida propuesta, la evidencia y el motivo del escalado. Si una corrección humana se guarda como dato de entrenamiento o como ejemplo de regresión, registra también su procedencia y la política aplicable.

La evidencia disponible aquí respalda capacidades de salida basada en esquema para Azure OpenAI y Gemini, pero no cuantifica tasas de error de formato frente a tasas de error semántico. Tampoco permite establecer un umbral universal de confianza. Por ello, mide ambas clases de fallo en tu propia tarea: una tasa baja de JSON inválido no demuestra una extracción correcta, y un buen resultado en una muestra pequeña no garantiza el comportamiento en producción.

5. Prueba el sistema y vigila su comportamiento en producción

Construye un conjunto de regresión con ejemplos representativos y casos límite antes de desplegar cambios en el prompt, el esquema, el modelo o el SDK. Incluye entradas limpias, entradas incompletas, datos contradictorios, caracteres inesperados, documentos largos y casos en los que la respuesta correcta sea «no encontrado». Para cada caso, conserva una expectativa verificable: resultado esperado, campos que deben quedar ausentes y condiciones que obligan a escalar.

Mide por separado la validez sintáctica, la conformidad con el esquema, la exactitud de cada campo y la tasa de escalado. Una única métrica agregada puede ocultar que el sistema produce JSON perfecto pero clasifica mal, o que acierta la mayoría de campos y falla precisamente en los de mayor impacto. Segmenta los resultados por tipo de entrada, versión del modelo, plantilla del prompt y versión del esquema.

En producción, registra métricas que permitan detectar degradaciones: respuestas no analizables, errores de validación, campos nulos, valores fuera de rango, desacuerdos con fuentes de referencia y proporción de revisiones humanas. Define alertas y una vía de recuperación, por ejemplo retener registros dudosos o volver a una versión anterior. No guardes datos sensibles innecesarios en los logs; conserva solo lo requerido para depuración, auditoría y cumplimiento de la política aplicable.

Antes de cambiar de proveedor o mecanismo, repite las pruebas con la misma muestra y los mismos criterios de aceptación. Las funciones documentadas no son intercambiables en todos sus detalles, y una migración puede modificar qué restricciones se admiten o cómo se representan las respuestas. Trata la configuración de producción como parte del contrato: proveedor, endpoint, modelo, esquema, SDK, prompt y política de reintentos deben quedar versionados y auditables.

Continúa explorando

Correcciones y transparencia

Si detectas un dato incorrecto o desactualizado, puedes enviarnos una corrección indicando la página y la fuente que debemos revisar.