Cómo hacer que los resultados estructurados de LLM sean portátiles en OpenAI, Anthropic y Gemini

Los resultados estructurados del LLM se vuelven frágiles cuando los equipos tratan el soporte del proveedor como intercambiable. OpenAI, Anthropic y Gemini pueden producir datos estructurados, pero no exponen el mismo contrato. La sintaxis de esquema, los sobres de llamada de herramientas, las garantías de rigor, el comportamiento de rechazo, el comportamiento de transmisión y los modos de error de validación difieren lo suficiente como para que un analizador que funciona con un modelo pueda fallar silenciosamente con otro.

La solución práctica es dejar de tratar las funciones de salida estructuradas específicas del proveedor como el contrato comercial. Defina un contrato de salida canónico para cada flujo de trabajo, compílelo en el formato de solicitud admitido por cada proveedor, valide cada respuesta con el esquema canónico y pruebe cada modelo antes de que se le permita atender tráfico de producción.

¿Qué es la salida estructurada portátil?

La salida estructurada portátil significa que la aplicación puede confiar en la misma forma de respuesta a nivel empresarial incluso cuando cambia el proveedor del modelo subyacente. Esto no significa que todos los proveedores reciban exactamente el mismo esquema JSON. Tampoco significa que la validación por parte del proveedor sea suficiente.

Un contrato portátil tiene cinco capas:

• Esquema canónico: la forma de datos neutral del proveedor del flujo de trabajo.
• Linting de portabilidad: comprueba que el esquema evite construcciones que no sean compatibles, que no se apliquen correctamente o que sean riesgosas para todos los proveedores.
• Compilación del proveedor: traducción del contrato canónico a OpenAI, Anthropic, Gemini o la superficie de salida estructurada nativa de otro proveedor.
• Validación en tiempo de ejecución: validación del lado de la aplicación del objeto devuelto frente al esquema canónico.
• Pruebas de contrato: pruebas repetibles que demuestran que cada modelo maneja campos obligatorios, enumeraciones, rechazos, truncamientos, solicitudes con formato incorrecto y casos extremos semánticos antes de cambios en la ruta de producción.

Este patrón es especialmente importante para un LLM empresarial API donde varios equipos, inquilinos o flujos de trabajo de socios dependen de contratos de producción predecibles.

Hechos: los resultados estructurados del proveedor no son un estándar

Antes de diseñar la capa de portabilidad, separe el comportamiento documentado del proveedor de las suposiciones.

OpenAI

OpenAI documenta resultados estructurados a diferencia del modo JSON. El modo JSON está destinado a garantizar que JSON sea válido, mientras que las salidas estructuradas están destinadas a coincidir con un esquema JSON proporcionado. OpenAI admite resultados estructurados a través del formato de respuesta y mediante llamadas a funciones con estricto cumplimiento del esquema, pero el comportamiento documentado incluye restricciones de modelo y versión y un subconjunto de esquemas admitidos. Los esquemas no admitidos en modo estricto pueden producir API errores y las aplicaciones aún necesitan manejar casos extremos.

Anthropic

Anthropic documenta el uso de la herramienta Claude como llamadas estructuradas a herramientas basadas en herramientas proporcionadas por el desarrollador con un input_schema. El modelo devuelve un bloque tool_use y la aplicación ejecuta la herramienta solicitada. Esto se parece a una llamada a función, pero no es el mismo contrato que una respuesta de esquema OpenAI con formato de respuesta JSON. La guía de ingeniería de Anthropic también señala que JSON Schema puede definir estructura, campos obligatorios y enumeraciones, pero no puede expresar patrones de uso, como cuándo se deben incluir parámetros opcionales o qué combinaciones de campos tienen sentido comercial.

Gemini

Google dice que la salida estructurada se puede configurar para JSON respuestas y que el modo de salida estructurada Gemini admite un subconjunto de la especificación del esquema JSON. Esto es importante porque un esquema que sea válido JSON Schema aún puede no ser adecuado como esquema de solicitud de proveedor portátil.

Observabilidad

Las convenciones semánticas de OpenTelemetry GenAI incluyen atributos para proveedor, modelo solicitado, modelo de respuesta, tipo de salida, motivos de finalización, uso de token, definiciones de herramientas, argumentos de llamada de herramientas y campos de solicitud y respuesta de GenAI relacionados. Estos campos pueden admitir la depuración entre proveedores cuando las fallas de salida estructurada son difíciles de distinguir de problemas de solicitud, esquema, modelo o proveedor.

Paso 1: Definir el esquema comercial canónico

Comience con el flujo de trabajo empresarial, no con el proveedor API. Un flujo de trabajo de clasificación de soporte, un flujo de trabajo de extracción de facturas, una recomendación de aprobación o un punto final de automatización orientado a los socios deben tener cada uno un esquema canónico que represente lo que la aplicación necesita en sentido posterior.

Por ejemplo, un flujo de trabajo de clasificación de soporte podría utilizar esta forma canónica:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "requires_human_review"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "security", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "requires_human_review": {
      "type": "boolean"
    },
    "customer_risk_signals": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Este esquema es el contrato en el que confía el resto de la aplicación. A partir de él se generan formatos de solicitud específicos del proveedor; no son la fuente de la verdad.

Utilice campos obligatorios explícitos, matrices limitadas, cadenas limitadas, enumeraciones cerradas y additionalProperties: false donde su validador lo admita. Evite aceptar objetos anidados arbitrarios a menos que el sistema posterior esté diseñado para manejar claves arbitrarias.

Paso 2: Agregar un paso Lint de portabilidad de esquema

Un linter de portabilidad debe rechazar esquemas que sean técnicamente válidos JSON Esquema pero riesgosos para el uso de múltiples modelos. El objetivo no es la expresividad completa del JSON esquema. El objetivo es un contrato de salida estable que pueda compilarse en varias superficies de proveedores sin debilitar la garantía de la aplicación.

Las comprobaciones de pelusa útiles incluyen:

• Rechace las palabras clave de composición no admitidas a menos que su compilador tenga asignaciones de proveedores explícitas para ellas.
• Rechazar object campos sin restricciones que permitan propiedades arbitrarias.
• Requerir enumeraciones para los campos de clasificación que impulsan el enrutamiento, la facturación, las aprobaciones o el estado visible del socio.
• Requiere maxItems para matrices utilizadas en automatización o visualización de interfaz de usuario.
• Requiere maxLength para los campos de texto que ingresan a bases de datos, colas o API de socios.
• Marcar campos opcionales cuya ausencia cambie el significado comercial.
• Rechace esquemas cuyo anidamiento o tamaño supere los límites de proveedores conocidos en su matriz de capacidades.

El linter debe ejecutarse en CI y antes de la implementación del esquema. No espere hasta que una solicitud de producción encuentre un error de proveedor porque una palabra clave de esquema no era compatible.

Paso 3: compilar en formatos de solicitud específicos del proveedor

La compilación del proveedor traduce el esquema canónico a la superficie API que realmente admite cada modelo. El compilador debe ser determinista y versionado. También debería dejar un registro de auditoría que muestre qué versión de esquema canónico produjo qué carga útil de solicitud de proveedor.

OpenAI compilación

Para OpenAI, el compilador puede apuntar a resultados estructurados mediante formato de respuesta para tareas de extracción y clasificación, o llamadas estrictas a funciones para flujos de trabajo orientados a acciones. La carga útil compilada debe incluir el subconjunto admitido del esquema y la configuración de rigor específica del proveedor cuando esté disponible.

Anthropic compilation

Para Anthropic, el compilador a menudo representará el resultado deseado como una herramienta con un input_schema. Luego, la aplicación espera un bloqueo de uso de la herramienta y valida la entrada de la herramienta con el esquema canónico. Esto significa que el adaptador debe normalizar el sobre de respuesta, no solo analizar JSON.

Gemini compilation

Para Gemini, el compilador debe apuntar a su configuración de respuesta estructurada JSON utilizando solo el subconjunto de esquemas admitidos. Si un esquema canónico utiliza restricciones que Gemini no aplica de forma nativa, el compilador debe registrar esas restricciones como que requieren validación del lado de la aplicación.

La salida del adaptador debe normalizarse en un tipo de resultado interno:

type StructuredResult = {
  provider: "openai" | "anthropic" | "gemini";
  model: string;
  schema_version: string;
  status: "ok" | "refusal" | "truncated" | "provider_error" | "invalid";
  raw_response: unknown;
  parsed_output?: unknown;
  finish_reason?: string;
};

Esta normalización evita que el código de flujo de trabajo posterior dependa de los sobres del proveedor.

Paso 4: Validar cada respuesta según el esquema canónico

La estructura del lado del proveedor es la primera línea de defensa, no la verificación final de corrección. Valide siempre el resultado analizado con el esquema canónico después de que el modelo responda.

La validación en tiempo de ejecución debería producir errores estructurados como:

• missing_required_field
• invalid_enum
• unexpected_property
• type_mismatch
• array_too_long
• string_too_long
• semantic_rule_failed

Mantenga la validación estructural separada de la validación semántica. JSON El esquema puede verificar la forma, las propiedades requeridas, las enumeraciones y las restricciones de tipo básico. No puede expresar completamente reglas comerciales como transiciones de estado válidas, umbrales de aprobación, políticas específicas del cliente o combinaciones de campos mutuamente dependientes.

Por ejemplo, este es un validador semántico, no una regla de esquema:

if (output.priority === "urgent" && output.requires_human_review !== true) {
  throw new SemanticValidationError(
    "urgent tickets must require human review"
  );
}

Coloque esas comprobaciones en el código de la aplicación, donde puedan usar la configuración del cliente, el estado del flujo de trabajo, el contexto de autorización y el control de versiones de las políticas.

Paso 5: Utilice la reparación limitada y luego cierre por error

Una ruta de reparación puede recuperarse de pequeños defectos de salida, pero también puede ocultar un esquema sistemático y problemas de avisos. Utilice un intento de reparación dirigido con el error de validación incluido. Si la respuesta reparada aún no supera la validación, falle el cierre o envíela a revisión.

Una política de reparación práctica es la siguiente:

• Intente reparar solo los tipos de error elegibles, como campos obligatorios faltantes, enumeraciones no válidas o JSON.
• No repare rechazos de proveedores, bloqueos de seguridad, fallas de autorización ni resultados sensibles a políticas.
• Incluya la versión del esquema canónico y el error de validación en el mensaje de reparación.
• Permitir como máximo un intento de reparación para flujos de trabajo visibles para el cliente o que activan acciones.
• Registrar el recuento de reparaciones, el éxito de las reparaciones, el uso de tokens y el estado final.

Para trabajos de extracción interna de bajo riesgo, un segundo intento de reparación puede ser aceptable si la latencia no es importante. Para los flujos de trabajo que activan pagos, cambios de acceso, respuestas del socio API o acciones de cumplimiento, una política de cierre fallido suele ser más segura.

Paso 6: Crear pruebas de contrato para cada modelo de producción

Las pruebas de contrato deciden si un modelo es apto para un flujo de trabajo. Deben ejecutarse antes del lanzamiento inicial, antes de las actualizaciones del modelo y antes de los cambios en la política de enrutamiento.

Como mínimo, pruebe cada modelo y adaptador de proveedor para:

• Salida de ruta feliz válida.
• Faltan campos obligatorios.
• Valores de enumeración no válidos.
• Propiedades adicionales cuando el esquema está cerrado.
• Demasiados elementos de matriz.
• Cadenas demasiado largas.
• Negativa o incapacidad para cumplir.
• Salida truncada.
• Las llamadas de herramientas no coinciden o faltan llamadas de herramientas.
• Resultado estructuralmente válido pero semánticamente incorrecto.

Utilice mensajes contradictorios que presionen al modelo para que viole el contrato. Por ejemplo, pídale que agregue un campo explicativo adicional, que devuelva una prioridad fuera de la enumeración u omita un booleano obligatorio. La prueba pasa solo si el proveedor, el adaptador y el validador producen el estado esperado de la aplicación.

Para cada flujo de trabajo, mantenga un registro de compatibilidad simple:

{
  "workflow": "support_triage",
  "schema_version": "2026-09-24",
  "model": "provider-model-name",
  "supports_strict_schema": true,
  "supports_tool_calling": true,
  "supports_streaming_structured_output": false,
  "refusal_signal_normalized": true,
  "contract_tests_passed": true,
  "known_limitations": ["max schema depth 4"]
}

Esta matriz de capacidades pertenece al plano de control, no a constantes de aplicación dispersas.

Paso 7: Instrumentar la confiabilidad de la salida estructurada

Sin telemetría, los equipos no pueden determinar si los errores se deben a incompatibilidad de proveedores, deriva del modelo, defectos de esquema, defectos de aviso, truncamiento o validadores posteriores.

Registra estos campos para cada solicitud de salida estructurada:

• Nombre del flujo de trabajo y versión del esquema.
• Proveedor, modelo solicitado y modelo de respuesta.
• Modo de salida, como esquema de respuesta, llamada a herramienta o modo JSON.
• Estado de validación y tipo de error.
• Recuento de reparaciones y resultado de la reparación.
• Motivo de finalización y estado de rechazo.
• Tokens de aviso, tokens de finalización, costo total y latencia.
• Versión del adaptador y versión del compilador.

Utilice estos datos para comparar modelos antes de cambiar la ruta. Un modelo más económico no es más barato si aumenta los intentos de reparación, la revisión manual, las fallas del socio API o el manejo de incidentes posteriores.

Compensaciones para decidir explícitamente

Los esquemas de mínimo común denominador mejoran la portabilidad pero debilitan las restricciones. Si el esquema de solicitud del proveedor debe simplificarse, mantenga controles más estrictos en la validación canónica y los validadores semánticos.

La compilación específica del proveedor preserva las fortalezas nativas pero agrega mantenimiento. Esto generalmente vale la pena para los flujos de trabajo de producción, pero solo si los compiladores están versionados y cubiertos por pruebas por contrato.

Los esquemas estrictos reducen los errores del analizador, pero requieren un mejor diseño de la tarea. Si la tarea no está suficientemente especificada, el rigor expone la ambigüedad antes. Esto es útil, pero puede ralentizar el desarrollo inicial.

La reparación mejora las tasas de finalización, pero añade costos y latencia. La reparación limitada es un mecanismo de recuperación, no un sustituto del diseño de esquema.

La llamada a herramientas y el formato de respuesta JSON sirven para flujos de trabajo diferentes. La llamada a herramientas suele ser más adecuada para flujos de trabajo orientados a la acción. El formato de respuesta JSON es más sencillo para la extracción, clasificación y resumen. Una plataforma multimodelo puede admitir ambos, pero la política de flujo de trabajo debe ser explícita.

Predicciones: hacia dónde se dirige la portabilidad de la producción estructurada

Es probable que el soporte del proveedor para la salida estructurada siga mejorando, pero JSON no se debe asumir la portabilidad completa del esquema entre modelos. Los proveedores tienen diferentes arquitecturas de modelos, API historiales, patrones de uso de herramientas y comportamientos de seguridad. Incluso cuando la compatibilidad con el esquema se vuelva más sólida, las aplicaciones seguirán necesitando validación canónica porque la corrección empresarial depende de algo más que la JSON forma.

Los equipos deberían esperar que las decisiones de enrutamiento de resultados estructurados se basen más en datos. La confiabilidad, la tasa de reparación, el manejo de rechazos, la latencia y el costo serán importantes junto con la calidad del modelo. La pregunta operativa pasará de "¿este modelo admite JSON?" a "¿este modelo satisface el contrato de este flujo de trabajo a un costo y una tasa de falla aceptables?"

Lista de verificación de implementación

• Defina un esquema canónico por flujo de trabajo.
• Verifique los esquemas y mantenga reproducibles las cargas útiles de las solicitudes del proveedor.
• Agregue linting de CI para funciones de esquema riesgosas o no compatibles.
• Compilar esquemas canónicos en formatos específicos del proveedor.
• Normalizar los sobres del proveedor en un tipo de resultado interno.
• Validar cada respuesta analizada según el esquema canónico.
• Añadir validadores semánticos para reglas de negocio.
• Permitir sólo intentos de reparación limitados.
• Error cerrado o ruta para revisión para flujos de trabajo de alto riesgo.
• Ejecutar pruebas de contrato antes de agregar o actualizar modelos de producción.
• Mantener una matriz de capacidades del modelo en el plano de control.
• Registra los campos de validación, reparación, costo, latencia, proveedor y modelo para cada solicitud.

Conclusión procesable

La portabilidad de salida estructurada es un API problema de contrato, no un problema de formato rápido. El patrón confiable es definir un esquema comercial canónico, vincularlo para su portabilidad, compilarlo en la superficie nativa de cada proveedor, validar cada respuesta después de que el proveedor la devuelva y utilizar pruebas de contrato para decidir qué modelos son elegibles para producción.

Este diseño agrega algo de trabajo de ingeniería inicial, pero evita el modo de falla más costoso: los sistemas posteriores asumen un contrato estable mientras el enrutamiento del modelo, el comportamiento del proveedor o la aplicación del esquema cambian silenciosamente debajo de ellos.

Lecturas relacionadas

• enrutamiento alternativo que protege los contratos de salida estructurados