# ¿Por qué deja de funcionar la salida JSON estructurada tras migrar una API de LLM? > El JSON estructurado suele fallar después de una migración de API de LLM porque las pilas anterior y nueva aplican contratos diferentes. Compara los esquemas de solicitud, los modos de respuesta, el streaming, los envoltorios de llamadas a herramientas, los rechazos y las reglas de validación antes de culpar al prompt. Una migración cambia mucho más que el nombre del servidor. Puede cambiar el modelo, la serialización del SDK, las palabras clave de esquema admitidas, el orden de los eventos de streaming, los valores de muestreo predeterminados, el comportamiento de seguridad y la ubicación exacta de la carga generada. Por eso, una solicitud que parece equivalente en el código de la aplicación puede representar un contrato distinto en la red. El diagnóstico más rápido consiste en guardar una solicitud fallida y su respuesta sin modificar en ambos proveedores. Compara los cuerpos HTTP reales, no los objetos envoltorio que presenta el SDK. Esa comparación suele revelar si la rotura se produce antes de la generación, durante ella o cuando la aplicación extrae y valida el resultado. ## Separa los fallos de sintaxis de los fallos de contrato La frase «el JSON se rompió» puede describir defectos diferentes. Tratarlos como un único problema lleva a modificar prompts de forma que se oculta la causa real. * Un fallo de sintaxis produce texto que un analizador JSON no puede leer. * Un fallo de esquema produce JSON válido con claves, tipos, niveles de anidación o valores enum incorrectos. * Un fallo de extracción ocurre cuando hay datos estructurados válidos, pero aparecen en otro campo de la respuesta. * Un fallo de streaming ocurre cuando se intentan analizar fragmentos parciales como si fueran documentos completos. * Un rechazo o un truncamiento sustituye el objeto esperado por un mensaje de seguridad o una carga incompleta. * Un fallo de llamada a herramientas devuelve argumentos dentro de un envoltorio de herramienta mientras la aplicación espera texto del asistente. Registra estas categorías por separado. Una excepción del analizador, la ausencia de un campo obligatorio y un `400` de la API no deben compartir un contador de reintentos genérico. ## Compara los dos contratos de solicitud Empieza con una matriz de migración campo por campo. Los nombres parecidos no siempre significan lo mismo. | Área del contrato | Pila anterior | Pila nueva | Pregunta de prueba | |---|---|---|---| | Modo de salida | Objeto JSON | Objeto sujeto a esquema | ¿Garantiza solo la sintaxis o todo el esquema? | | Ubicación del esquema | Parámetros de herramienta | Formato de respuesta | ¿Está el esquema asociado al campo correcto? | | Rigurosidad | Implícita | Indicador explícito | ¿Debe activarse el modo estricto? | | Palabras clave no admitidas | Se ignoran | Se rechazan | ¿Se aceptan uniones, formatos, valores predeterminados o referencias? | | Claves adicionales | Permitidas | Bloqueadas | ¿Se procesa `additionalProperties` de la misma forma? | | Streaming | Deltas de texto | Eventos tipados | ¿Qué evento contiene el objeto completo? | | Rechazos | Texto del asistente | Campo dedicado | ¿Puede el extractor distinguir un rechazo de una salida? | Captura la solicitud serializada final después del procesamiento del SDK. Los valores predeterminados que añadía el cliente anterior pueden desaparecer durante la migración. También puede ocurrir lo contrario: un SDK nuevo puede añadir un indicador estricto o cambiar el nombre de un campo de formato de respuesta sin producir un error evidente en la aplicación. ## Reduce el esquema antes de cambiar el prompt Prueba primero el esquema más pequeño posible. Empieza con una sola cadena obligatoria y sin ramas opcionales. Añade enteros, matrices, objetos anidados, enumeraciones y estructuras condicionales de uno en uno. Así aislarás las funciones no admitidas mucho más rápido que reescribiendo repetidamente un prompt de producción. Por ejemplo, una base portable podría ser esta: ```json { "type": "object", "properties": { "decision": {"type": "string", "enum": ["approve", "review", "reject"]}, "reason": {"type": "string"} }, "required": ["decision", "reason"], "additionalProperties": false } ``` Si funciona, el transporte y la ruta básica de aplicación del esquema son correctos. Si el esquema de producción falla después de añadir una función, ya tienes una cuestión concreta de compatibilidad en vez de un problema impreciso de calidad del modelo. ## Comprueba dónde se encuentra la carga estructurada Las migraciones de proveedor suelen romper el código de extracción. Una pila puede devolver JSON en un mensaje del asistente, otra en una propiedad ya analizada y otra como argumentos de herramienta convertidos en cadena. El streaming puede exponer una secuencia de eventos tipados en lugar de deltas de texto normales. Crea un resultado interno normalizado antes de que el resto de la aplicación vea la respuesta: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` Conserva `raw` durante el periodo de migración. Es la evidencia necesaria para distinguir un defecto de salida del modelo de un defecto del adaptador. Elimina la información sensible antes de almacenar registros y establece un periodo de conservación apropiado para la aplicación. ## No analices un stream sin terminar Un documento JSON suele ser inválido hasta que llega su último byte. Intentar analizar cada delta genera errores esperables que parecen fallos de producción. Acumula la salida completa, utiliza un analizador JSON incremental admitido por el proveedor o consume un evento documentado que represente la respuesta estructurada final. La prueba de streaming debe cubrir más que el caso ideal: * cadenas divididas entre fragmentos; * comillas escapadas y caracteres Unicode; * matrices con muchos elementos; * una desconexión antes de la llave de cierre; * un evento de rechazo; * un objeto final válido seguido de metadatos de uso; * argumentos de herramientas entregados en varios deltas. Trata una interrupción de red como una generación incompleta, no como una salida mal formada del modelo. Reintentar puede ser seguro para una clasificación de solo lectura, pero no necesariamente si el resultado activa un efecto externo. ## Valida dos veces, pero repara con cuidado Aunque el proveedor aplique un esquema, la aplicación debe validar el resultado normalizado en su límite de confianza. Esto la protege frente a errores del adaptador, regresiones de funciones y supuestos que el proveedor nunca prometió. Una secuencia práctica es: 1. Confirma que la solicitud HTTP terminó correctamente. 2. Detecta de forma explícita rechazos, truncamientos o la finalización de llamadas a herramientas. 3. Extrae la carga estructurada completa. 4. Analízala una sola vez. 5. Valídala con la versión del esquema de la aplicación. 6. Rechaza valores desconocidos o inseguros antes de ejecutar lógica de negocio. Evita un bucle ilimitado de «arreglar este JSON». Un modelo reparador puede cambiar el significado mientras corrige la sintaxis. Si la reparación es aceptable, limítala a un intento, aporta los errores de validación, conserva la salida original y vuelve a validar el objeto reparado. Para acciones de alto impacto, envía el caso a revisión. ## Crea un conjunto de reproducción para la migración Antes de redirigir tráfico de producción, reúne un corpus pequeño basado en formas de solicitud reales. Elimina datos personales o confidenciales e incluye casos que ejerciten los límites del contrato. | Grupo de casos | Qué debe incluir | Condición de aprobación | |---|---|---| | Normal | Entradas breves habituales | Objeto válido con los valores esperados | | Campos opcionales | Variantes con y sin campos | El comportamiento obligatorio y opcional respeta el contrato | | Ambiguo | Entrada conflictiva o insuficiente | Objeto válido con un estado de incertidumbre permitido | | Contexto largo | Cerca del máximo normal de la aplicación | Sin truncamiento y con extracción válida | | Adversarial | Texto que pide ignorar el esquema | El esquema permanece intacto | | Rechazo | Solicitud no permitida o insegura | Se detecta el rechazo sin confundirlo con un error del analizador | | Streaming | Límites de fragmento y desconexiones | Solo las cargas completas llegan a validación | Ejecuta ambos proveedores con parámetros estables y registra tasa de validez, acuerdo semántico, tasa de rechazo, tasa de truncamiento, latencia y número de reintentos. No siempre se espera una igualdad semántica exacta, pero la validez del esquema debe ser un requisito estricto. ## Aísla la compatibilidad detrás de un adaptador No permitas que los tipos de respuesta del proveedor se propaguen por toda la base de código. Un adaptador pequeño debe encargarse de construir solicitudes, comprobar capacidades del esquema, extraer respuestas, normalizar motivos de finalización, campos de uso y errores. El resto de la aplicación debe consumir una única interfaz interna. Una puerta de enlace compatible con OpenAI como [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) puede reducir el trabajo repetido de integración cuando una aplicación usa modelos de texto, imagen y vídeo. La compatibilidad de transporte resulta útil, pero no elimina las pruebas a nivel de modelo. Mantén indicadores de capacidad para salida estructurada, herramientas, streaming y funciones de esquema, en lugar de asumir que todos los modelos tras un endpoint compatible se comportan igual. Versiona el adaptador y el esquema juntos. Cuando cambie un esquema, guarda su versión con la salida para que los servicios posteriores sepan qué contrato han recibido. ## Usa un despliegue gradual con condiciones de parada claras Empieza con reproducción sin conexión, sigue con tráfico en sombra y después con un pequeño porcentaje de tráfico real. No confíes únicamente en el éxito agregado. Una tasa de validez del 99 % puede seguir siendo inaceptable si el 1 % de fallos se concentra en solicitudes de pago, moderación o autorización. Define las condiciones de parada antes de la prueba: * un enum inseguro llega a la lógica de negocio; * la tasa de validez del esquema cae por debajo de la referencia actual; * la gestión de rechazos se vuelve ambigua; * el truncamiento supera el umbral acordado; * los reintentos elevan el coste o la latencia por encima del presupuesto; * las respuestas sin modificar no pueden reconciliarse con los resultados normalizados. Cuando sea posible, revierte mediante la configuración de enrutamiento en vez de hacer un despliegue urgente de código. Mantén disponible el adaptador anterior hasta que la nueva ruta haya soportado tanto la carga máxima como las clases de entrada poco frecuentes. ## Conclusión Los fallos de JSON estructurado después de migrar una API de LLM suelen deberse a contratos incompatibles, errores de extracción o lógica de streaming incompleta, no a que el nuevo modelo sea incapaz de seguir instrucciones. Compara las cargas reales, reduce el esquema, normaliza las respuestas, valida en el límite de la aplicación y reproduce un corpus representativo antes de mover el tráfico. Una API compatible puede simplificar la migración, pero las pruebas explícitas de capacidades siguen siendo la forma fiable de proteger el comportamiento de producción. ## FAQ ### ¿Por qué el mismo prompt JSON funciona con un modelo y falla con otro? La redacción del prompt es solo una capa. Los modelos y proveedores difieren en sus modos JSON nativos, compatibilidad con esquemas, tokenización, comportamiento de rechazo y rigurosidad al respetar restricciones. ### ¿El modo JSON es lo mismo que aplicar JSON Schema? No. El modo JSON puede limitarse a garantizar un JSON sintácticamente válido, mientras que la aplicación de un esquema también restringe claves, tipos, campos obligatorios y, en algunos casos, propiedades adicionales. ### ¿Debo analizar el JSON transmitido token por token? Normalmente no. Acumula la carga estructurada completa o utiliza los eventos de streaming estructurado documentados por el proveedor y valida después del evento final. ### ¿Una API compatible con OpenAI elimina el trabajo de migración? Puede reducir los cambios de transporte y SDK, pero todavía debes verificar las funciones de esquema específicas de cada modelo, los motivos de finalización, los formatos de llamadas a herramientas y el comportamiento de los errores. ### ¿Qué debe ocurrir cuando falla la validación? Conserva la respuesta sin modificar, clasifica el fallo, reintenta únicamente los casos transitorios seguros y limita cualquier reparación determinista mediante validación, en lugar de aceptar silenciosamente datos mal formados. ### ¿Cuál es la prueba de preproducción más rápida? Reproduce un corpus fijo de solicitudes normales, ambiguas, adversariales, rechazadas, de contexto largo y de streaming en ambas pilas y compara los resultados validados campo por campo.