Contratos para aplicaciones de IA: detectar cambios de modelo, SDK o herramientas antes de producción

Una demo que responde no demuestra compatibilidad

En una aplicación de IA, un cambio puede no producir un error de transporte y, aun así, romper el producto. El modelo puede seguir devolviendo texto útil para una persona, pero omitir un campo que consume un servicio posterior, elegir una herramienta no permitida, cambiar el significado práctico de una etiqueta o fundamentar una conclusión en un fragmento recuperado que no la respalda. Por eso, comprobar que “sigue respondiendo” no equivale a comprobar que conserva el comportamiento operativo esperado.

Un contrato es una especificación verificable de las propiedades que deben mantenerse en una frontera concreta del flujo. No es una promesa de que el modelo redactará siempre la misma frase ni un intento de eliminar la variabilidad generativa. Define qué entradas son admitidas, qué forma debe tener la salida, qué invariantes de negocio no pueden violarse, qué acciones están autorizadas y qué evidencia se requiere antes de afirmar algo o ejecutar una operación.

La unidad de análisis debe ser el cambio incompatible concreto. Puede ser una sustitución de modelo, una actualización del SDK, una modificación del prompt de sistema, un cambio de esquema, una definición nueva de herramienta o una política actualizada del proveedor. El objetivo es responder antes de promocionar el cambio: ¿se ha preservado el contrato?, ¿la degradación está dentro de un límite aceptado?, ¿hay que adaptar el flujo?, ¿o debe bloquearse?

Los contratos complementan las evaluaciones agregadas de calidad, pero resuelven otro problema. Una evaluación puede indicar que la utilidad media sigue siendo alta aunque uno de cien casos emita una orden de cancelación sin confirmación. Ese caso aislado es una incompatibilidad crítica si la acción tiene efectos externos. Del mismo modo, JSON válido no prueba que un argumento sea seguro, que una cita corresponda a la fuente o que una clasificación conserve su significado.

Inventario de fronteras y dependencias

Antes de escribir pruebas, dibuje el recorrido completo de un caso de usuario. Una frontera existe donde un componente entrega una representación que otro componente interpreta: la solicitud enviada al proveedor, el identificador de modelo, la respuesta del modelo, el adaptador del SDK, el recuperador de contexto, la llamada a una herramienta, el sistema de destino y la acción externa. Cada frontera puede tener un contrato distinto y un propietario distinto.

El inventario debe identificar versiones y configuraciones efectivas, no solo nombres genéricos. Registre el modelo o instantánea solicitada, versión del SDK y de la API cuando sea aplicable, prompt de sistema, parámetros de generación, esquema de salida, lista de herramientas, definición de permisos, versión del índice de recuperación y adaptadores internos. Sin esa información, un fallo posterior difícilmente podrá atribuirse a una causa concreta.

No todas las fronteras exigen la misma clase de aserción. La petición al modelo requiere comprobar parámetros admitidos y valores normalizados. Una salida estructurada necesita validar esquema y campos obligatorios. La recuperación necesita comprobar procedencia, vigencia y suficiencia de evidencia. Las herramientas requieren, además de sintaxis, autorización y simulación de efectos. El sistema de destino necesita idempotencia, control transaccional o compensación según el riesgo.

La documentación de los proveedores indica que los ciclos de vida de modelos y las interfaces pueden cambiar. En particular, las retiradas de modelos y determinados cambios de parámetros pueden convertir solicitudes antes válidas en errores. Esto hace necesario que la migración se pruebe como un cambio de dependencia, incluso si el código de negocio no ha cambiado.

Qué debe convertirse en contrato

Empiece por los elementos deterministas. Son buenos candidatos los tipos, campos obligatorios, límites numéricos, enumeraciones, identificadores, presencia de una fuente, formato de fechas, herramientas permitidas y reglas de autorización. También lo son las invariantes de negocio: una devolución no puede superar el importe pagado, un agente no puede modificar datos de otro cliente y una operación que exige aprobación humana no puede ejecutarse sin ese estado.

Después añada restricciones operativas. Defina un presupuesto de latencia y coste por caso, con una medición especificada: por ejemplo, percentil sobre una muestra controlada, no una impresión aislada. Establezca máximos de reintentos, herramientas por ejecución, documentos recuperados y tamaño de contexto. Un aumento puede ser compatible técnicamente y resultar inaceptable para el producto; el contrato debe separar ambos planos.

Las etiquetas merecen un tratamiento semántico explícito. Si una salida contiene `riesgo_alto`, el contrato debe explicar qué hechos la justifican y qué consecuencias activa. Una coincidencia literal de la etiqueta no basta si cambió el criterio de asignación. Use casos de frontera con anotación humana y aserciones sobre las condiciones observables que deben llevar a cada clase.

En respuestas con evidencia, el contrato debe diferenciar entre tener una cita y estar respaldado. Como mínimo, compruebe que la fuente recuperada es admisible para el dominio, que su fecha satisface la política de vigencia, que el pasaje contiene evidencia suficiente para la afirmación y que el flujo declara insuficiencia cuando falta base. La atribución no debe convertirse en una decoración generada al final del proceso.

Clasificar el cambio antes de debatir sus resultados

Clasifique cada modificación propuesta en cuatro grupos. Un cambio compatible conserva todos los contratos aplicables. Uno compatible con degradación aceptable incumple un objetivo no crítico dentro de un umbral aprobado, como una variación limitada de latencia. Un cambio incompatible viola una propiedad obligatoria, como un permiso de acción o un campo requerido. Un cambio desconocido es aquel para el que faltan casos, fixtures, telemetría o una definición suficiente para concluir.

La clasificación no debe depender de quién propone el cambio ni de que una demostración resulte convincente. Debe estar ligada a reglas de promoción publicadas previamente. Si el equipo descubre que una regla no refleja ya la necesidad del producto, puede cambiar el contrato, pero esa decisión debe ser explícita, revisada y versionada; no debe quedar implícitamente aceptada por una prueba fallida.

Fijar una versión concreta de modelo reduce una fuente de variación y facilita reproducir resultados. Los alias o modelos sujetos a actualizaciones pueden modificar el comportamiento sin que cambie el código cliente. La documentación de OpenAI recomienda fijar versiones de modelo y ejecutar evaluaciones porque las instantáneas pueden variar en el comportamiento de prompting. En consecuencia, un contrato debe registrar tanto el identificador solicitado como la política de actualización aceptada por el equipo.

Diseñar una batería mínima que sea diagnóstica

Una batería útil no necesita intentar representar toda la conversación humana posible. Debe contener casos fijos que cubran los caminos críticos, casos de borde y contraejemplos históricos. Cada caso debe declarar entrada, estado inicial, configuración del flujo, resultado esperado, severidad y aserciones. Mantenga los datos de prueba sin información sensible y asegure que puedan ejecutarse repetidamente.

Use fixtures para las herramientas y dependencias externas. Una fixture debe devolver estados controlados, registrar las llamadas y evitar efectos reales. Así puede comprobar que el modelo eligió la herramienta correcta, que los argumentos fueron interpretados por el adaptador y que no se intentó ejecutar una alternativa prohibida. Un entorno de pruebas que llama a producción no es una fixture: mezcla compatibilidad con riesgo operativo.

Los snapshots son adecuados para artefactos deliberadamente estables, como una petición normalizada, un esquema de herramienta o una lista ordenada de identificadores recuperados. Son frágiles para prosa completa producida por un modelo. Para el lenguaje natural, prefiera aserciones semánticas acotadas: presencia de hechos obligatorios, ausencia de afirmaciones prohibidas, correspondencia con evidencia y comportamiento de abstención ante datos insuficientes.

Algunas medidas no son deterministas. La tasa de éxito, la distribución de latencia y la frecuencia de una clasificación pueden requerir varias ejecuciones, una muestra fijada y un intervalo o tolerancia predefinidos. No convierta una diferencia estadística pequeña en una regresión crítica, ni permita que la incertidumbre estadística oculte una violación determinista de seguridad.

Salidas estructuradas y llamadas a herramientas: esquema no es autorización

Una salida estructurada debe validarse dos veces: primero contra su representación y después contra su significado. La primera validación comprueba JSON, tipos, campos requeridos, rangos y valores permitidos. La segunda comprueba relaciones entre campos y estado externo. Por ejemplo, que una fecha de inicio sea anterior a la de fin, que el importe pertenezca al pedido indicado y que un código de motivo sea coherente con el caso.

Las interfaces de herramientas de los proveedores pueden describir parámetros mediante JSON Schema y ofrecer modos estrictos de adhesión al esquema. Es una ayuda relevante para disminuir argumentos mal formados, pero no sustituye la validación de la aplicación. Un argumento puede estar bien tipado y designar una cuenta equivocada, una operación fuera de la política o una acción que necesita aprobación. El ejecutor debe aplicar autorización, precondiciones y límites antes de producir efectos.

El contrato también debe fijar el orden. En un flujo que consulta elegibilidad y después emite un reembolso, no acepte una secuencia invertida solo porque ambas llamadas sean válidas individualmente. Registre las herramientas permitidas por etapa, el máximo de invocaciones, los argumentos normalizados, la respuesta fixture y la ausencia de llamadas no autorizadas. Esto permite detectar cambios donde el modelo parece resolver la tarea, pero toma un atajo operativo peligroso.

Si el proveedor modifica el modelo, la definición de herramienta o el adaptador del SDK, ejecute los mismos fixtures. Una prueba de JSON válido detectaría un objeto mal formado; esta batería puede detectar que se eligió una herramienta distinta, que se omitió la consulta previa o que el sistema intentó repetir una acción ya confirmada.

Contratos para recuperación y respuestas con fuentes

En un flujo RAG, el contrato comienza antes de redactar. Establezca qué colecciones puede consultar el caso, qué metadatos mínimos debe devolver cada fragmento y cómo se resuelve la vigencia. Si una respuesta depende de una política actual, un documento antiguo puede ser recuperable técnicamente pero inadmisible para fundamentarla. La prueba debe inspeccionar la procedencia, no solo el texto final.

Defina una evidencia mínima por tipo de afirmación. Una conclusión normativa puede requerir un pasaje explícito de una fuente autorizada; una síntesis puede requerir varios fragmentos coherentes; una cifra puede requerir coincidencia exacta con el documento. Si los resultados no satisfacen esa condición, la conducta correcta puede ser pedir más contexto, declarar incertidumbre o no responder la afirmación. Esa abstención es una salida contractual, no un error de experiencia por defecto.

Pruebe contradicciones y contexto insuficiente. Incluya fixtures con documentos desactualizados, fuentes de autoridad menor, fragmentos que mencionan términos similares y conjuntos que contienen información conflictiva. El contrato debe indicar si el flujo prioriza una fuente, expone el conflicto o escala a revisión. No es razonable afirmar que una cita es correcta solo porque comparte palabras con la respuesta.

Conserve para cada ejecución el conjunto de documentos candidatos, los seleccionados, sus identificadores y metadatos relevantes, la versión del índice, la consulta transformada y el resultado final. Esta telemetría permite distinguir si el incumplimiento surgió en recuperación, en la interpretación del modelo o en la representación de la evidencia.

Integración en CI/CD, decisión y reversión

Ejecute la batería cuando cambie cualquiera de los artefactos registrados: versión de modelo, SDK, prompt de sistema, parámetros, esquema, definición de herramientas, recuperador, índice o política. El cambio debe producir un manifiesto comparable que incluya versiones, hashes o identificadores internos, resultados por caso, duración, consumo medido cuando esté disponible y trazas de herramientas y recuperación. Evite que una actualización implícita quede fuera del control de cambios.

Organice las puertas de CI por severidad. Las aserciones críticas, como autorizaciones, efectos no permitidos, aislamiento de clientes o evidencia obligatoria, deben bloquear. Las de severidad alta normalmente bloquean hasta tener una adaptación aprobada. Las métricas de calidad o rendimiento con tolerancia pueden requerir revisión. Un resultado desconocido no debe convertirse automáticamente en compatible por falta de señal.

Cuando falla un contrato, primero localice la frontera. Compare la solicitud normalizada, el artefacto del modelo, la respuesta sin procesar, la adaptación del SDK, los documentos recuperados y el registro de herramientas. Después elija entre corregir la integración, adaptar el contrato porque cambió una necesidad legítima, versionar el flujo para mantener ambos comportamientos o rechazar el cambio. Documente por qué la decisión es válida y quién la aprobó.

La reversión debe estar diseñada antes de la promoción. Conserve la configuración anterior que permita restaurar modelo, prompt, esquema, herramientas y adaptadores compatibles. Si el proveedor retira una versión, quizá no exista una reversión exacta; en ese caso, la alternativa es un flujo versionado con adaptación probada. Las políticas de retirada publicadas por los proveedores son una razón adicional para planificar migraciones antes de la fecha límite, no después de detectar un incidente.

Plantilla de manifiesto de contrato por flujo

Un manifiesto breve convierte la intención en un artefacto revisable. Debe vivir junto al flujo y cambiar mediante el mismo proceso de revisión que el código. No necesita contener secretos ni todas las conversaciones de prueba; debe apuntar a identificadores internos de fixtures y definir con precisión qué propiedades gobierna.

Incluya: nombre y propósito del flujo; propietario técnico y de producto; versión del contrato; identificadores de modelo, SDK y configuraciones; prompt o referencia a su versión; esquema de salida; herramientas permitidas y permisos; dependencias de recuperación; lista de casos; umbrales de rendimiento y coste; severidad de cada regla; política de promoción; telemetría exigida; estrategia de reversión; y fecha de revisión. Si una regla carece de propietario o de criterio de fallo, todavía no es un contrato operativo.

La plantilla no elimina el juicio técnico. Las fuentes disponibles documentan mecanismos de versionado, retirada, esquemas y uso estricto de herramientas, pero no pueden decidir qué evidencia es suficiente para su dominio ni qué acción requiere aprobación humana. Esas decisiones corresponden al equipo responsable y deben formularse como políticas comprobables. La ventaja del manifiesto es obligar a hacerlas visibles antes de que una actualización las contradiga.

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.