Lista de verificación para implementar observabilidad de IA: 5 pasos hasta producción

La observabilidad de IA solo resulta útil cuando los ingenieros pueden actuar sobre ella durante un despliegue o un incidente. Un panel lleno de recuentos de tokens y percentiles de latencia no basta si nadie puede responder qué solicitud falló la validación, por qué se activó un fallback o si un pico de costo provino del tráfico, de los reintentos o de un cambio de modelo.

Esta lista de verificación para implementar la observabilidad de IA convierte el problema en cinco pasos ordenados:

1. Definir el contrato de telemetría.
2. Instrumentar cada intento del modelo.
3. Validar la calidad y el costo.
4. Establecer objetivos de nivel de servicio y alertas.
5. Desplegar con responsabilidad y gobernanza.

El orden importa. Los equipos que empiezan con paneles suelen descubrir más tarde que sus campos son inconsistentes, que sus trazas ocultan reintentos o que su métrica de éxito cuenta como solicitudes saludables salidas que no se pueden usar.

Si primero necesitas un mapa más amplio de señales y diseño de paneles, lee la guía de observabilidad de la API de LLM. Este artículo se centra en la secuencia de implementación y en los criterios de salida de cada etapa.

Lista de verificación para implementar observabilidad de IA de un vistazo

Paso 1: Define el contrato de telemetría antes de elegir paneles

Empieza por las preguntas que los operadores deben responder y luego define el registro común más pequeño que las admita. El contrato debe sobrevivir a cambios de proveedor y al fallback del modelo. Los campos específicos de cada proveedor pueden añadirse como atributos opcionales, pero no deben sustituir los nombres internos estables.

Campos requeridos a nivel de solicitud

Usa un único request_id interno para la operación del producto y un trace_id para el rastreo distribuido. Añade un attempt_id para cada llamada al proveedor.

{
  "telemetry_schema_version": "1.0",
  "request_id": "req_...",
  "trace_id": "...",
  "attempt_id": "attempt_1",
  "environment": "production",
  "feature": "support_reply",
  "route_policy": "quality_primary_cost_fallback",
  "provider": "provider_a",
  "requested_model": "model_alias",
  "response_model": "resolved_model_version",
  "prompt_version": "support_reply_v12",
  "attempt_number": 1,
  "streaming": true,
  "status": "completed",
  "validation_status": "passed"
}

La respuesta exacta del proveedor puede usar nombres diferentes. Normaliza esos campos en el borde para que los paneles posteriores no necesiten consultas separadas para cada proveedor.

OpenTelemetry mantiene convenciones semánticas de IA generativa para spans, métricas y eventos. Úsalas donde encajen, pero versiona también tu contrato interno de telemetría. Las convenciones semánticas pueden evolucionar, mientras que las consultas de incidentes y las comparaciones históricas deben seguir siendo comprensibles.

Separa las dimensiones acotadas de las pruebas de alta cardinalidad

Las métricas necesitan etiquetas acotadas. Las buenas dimensiones incluyen:

• environment
• feature
• provider
• model_family
• route_policy
• status
• error_type
• validation_status

Mantén los IDs de solicitud, IDs de trazas, IDs de solicitud del proveedor, IDs de usuario, huellas de prompts y mensajes de error en trazas o registros, no en etiquetas de métricas. De lo contrario, un solo despliegue puede crear millones de series temporales y hacer que el sistema de monitoreo sea más lento o más costoso que la aplicación que observa.

Decide explícitamente el modo de privacidad

No hagas que la captura de prompts en bruto sea el valor predeterminado. Define una política a nivel de campo con al menos tres modos:

La Hoja de referencia de registro de OWASP recomienda excluir o proteger datos sensibles como tokens de acceso, contraseñas e información personal. Aplica el mismo principio a la telemetría de IA: nunca asumas que un backend de observabilidad es un archivo de prompts adecuado.

Criterios de salida del paso 1

• Existe un esquema versionado para eventos de solicitud, intento, validación y coste.
• Los reintentos y los fallbacks usan valores separados de attempt_id.
• Las etiquetas de métricas están acotadas.
• La captura de prompt y salida tiene un modo de privacidad explícito.
• Los campos específicos del proveedor se asignan a campos internos estables.
• La propiedad del esquema y la revisión de cambios están asignadas.

Step 2: Instrument the full request path, not one SDK call

El trace debe comenzar en la operación visible para el usuario y continuar a través de la recuperación, el enrutamiento, cada intento del modelo, la validación, la ejecución de herramientas y la persistencia. Instrumentar solo la llamada final del SDK oculta las decisiones que causan la mayoría de los incidentes en producción.

Una jerarquía de spans útil se ve así:

POST /assistant/run
├── load_context
├── select_route
├── model_attempt 1
│   ├── stream_first_token
│   └── tool_call weather_lookup
├── validate_output
├── model_attempt 2 fallback
│   └── stream_first_token
└── persist_result

Record latency in components

Una duración de extremo a extremo no puede distinguir entre retraso de red, tiempo de generación del proveedor, puesta en cola, validación o ejecución de herramientas. Como mínimo, capture:

• Duración total visible para el usuario
• Retraso de gateway o cola
• Duración del intento del proveedor
• Tiempo hasta el primer token para respuestas en streaming
• Tiempo entre el primer y el último token
• Duración de la validación
• Duración de la llamada a la herramienta

Para streaming, defina con precisión el reloj del primer token. Inícielo cuando su servicio acepta la solicitud, no después de que se complete el enrutamiento, si la métrica pretende representar la experiencia del usuario.

Make retries and fallbacks visible

Una respuesta exitosa después de tres intentos no es equivalente a un éxito en el primer intento. Emita un span por cada intento e incluya:

• Número de intento
• Motivo del reintento o fallback
• Categoría del error anterior
• Duración del backoff
• Proveedor y modelo seleccionados
• Estado del circuit-breaker
• Si se emitió algún contenido parcial

El streaming parcial requiere un cuidado especial. Si los bytes ya han llegado al cliente, repetir silenciosamente una solicitud contra otro modelo puede duplicar el contenido o crear acciones de herramientas inconsistentes. El trace debe mostrar si el sistema se detuvo, reconcilió o continuó. Use el manual de enrutamiento de fallback de la API de LLM para definir ese comportamiento antes de habilitar el failover automatizado.

Emit metrics from normalized events

Genere métricas a partir de los registros normalizados de solicitud e intento en lugar de añadir contadores puntuales dentro de cada integración. Un conjunto mínimo de métricas es:

ai_requests_total
aI_attempts_total
ai_request_duration_seconds
ai_time_to_first_token_seconds
ai_input_tokens_total
ai_output_tokens_total
ai_validation_failures_total
ai_fallbacks_total
ai_estimated_cost_usd_total

Los objetos de uso del proveedor pueden diferir, especialmente para tokens almacenados en caché o tokens de razonamiento. Conserve el objeto de uso sin procesar en almacenamiento de diagnóstico restringido cuando sea apropiado, pero asigne los campos necesarios para la elaboración de informes entre proveedores a un registro de coste común.

Step 2 exit criteria

• Un rastro conecta la operación del producto con cada intento del modelo.
• La latencia del primer token y de extremo a extremo tiene puntos de inicio y fin documentados.
• Los reintentos, las rutas de respaldo y las decisiones del disyuntor son visibles.
• Las llamadas a herramientas tienen spans secundarios y campos de resultado.
• Las métricas se derivan de eventos normalizados y versionados.
• Las pruebas de carga confirman que la telemetría no crea una latencia o cardinalidad inaceptables.

Step 3: Validar el éxito de la aplicación y conciliar el costo

El éxito del transporte es solo una capa de salud. Una respuesta de IA puede devolver HTTP 200 y aun así incumplir el contrato del producto porque está vacía, mal formada, rechazada, no es compatible o no es segura de ejecutar.

Definir una máquina de estados de éxito validado

Usa estados explícitos en lugar de un solo booleano:

received
→ transport_succeeded
→ parsed
→ contract_validated
→ business_rule_validated
→ accepted

Los fallos deben detenerse en la etapa correcta, por ejemplo:

transport_failed
parse_failed
schema_failed
tool_policy_failed
business_rule_failed
cancelled
timed_out

Esto permite al equipo distinguir la disponibilidad del proveedor de la calidad de la aplicación. Tu denominador principal de fiabilidad normalmente debería ser las operaciones de usuario aceptadas, no las respuestas brutas del proveedor.

Agregar primero validadores deterministas

Antes de construir una evaluación subjetiva del modelo, implementa comprobaciones que produzcan resultados reproducibles:

• Análisis de JSON o de esquema
• Presencia de campos obligatorios
• Nombres de herramientas permitidos y tipos de argumentos
• Presencia de citas cuando la función requiera citas
• Gestión del estado de rechazo
• Límites de longitud y formato de salida
• Reglas de negocio como IDs, fechas, monedas o valores de enum válidos

Une las evaluaciones offline muestreadas con la telemetría de producción mediante un ID de muestra estable. No coloques texto de evaluación sin límite en las etiquetas de métricas. Para los cambios de modelo, usa un flujo de trabajo de pruebas de prompts multimodelo repetible, de modo que la latencia y el costo se comparen junto con la tasa de salida aceptada.

Calcular el costo por tarea aceptada

El costo en tokens por solicitud es útil, pero el costo por tarea aceptada es la mejor medida operativa:

cost_per_accepted_task =
  total_cost_of_all_attempts / accepted_user_operations

Incluye en el numerador los intentos fallidos, reintentos, rutas de respaldo y salidas rechazadas. De lo contrario, los problemas de fiabilidad se verán como una erosión inexplicada del margen.

Mantén dos estados de costo:

1. Costo estimado calculado inmediatamente a partir del uso de la respuesta y una tabla de precios versionada.
2. Costo conciliado actualizado más tarde a partir de la facturación del proveedor o exportaciones de uso cuando estén disponibles.

Almacena la price_version o la marca de tiempo efectiva usada para cada estimación. Sin eso, los cambios históricos de costo se vuelven imposibles de explicar después de una actualización de precios. Para el diseño de finanzas y operaciones, consulta la guía de gestión del gasto en API de IA.

Criterios de salida del paso 3

• El éxito aceptado es independiente del éxito HTTP.
• Los validadores deterministas cubren el contrato crítico del producto.
• Las muestras de evaluación pueden vincularse a solicitudes de producción.
• El coste incluye cada intento, incluidas las salidas rechazadas.
• El coste estimado y el coste conciliado son campos separados.
• Las versiones de precio se conservan para el análisis histórico.

Paso 4: Establecer SLO y alertas en torno a los resultados del usuario

Las alertas deben describir el daño para el usuario o el riesgo operativo de evolución rápida. Un solo error del proveedor no siempre perjudica al usuario si el fallback tiene éxito dentro del presupuesto de latencia. Por el contrario, un proveedor completamente disponible aún puede producir resultados inutilizables.

Empiece con cuatro indicadores de nivel de servicio

Establezca objetivos por función y nivel de riesgo. Un asistente de programación síncrono, un clasificador de documentos en segundo plano y un flujo de trabajo de soporte de pagos no deben compartir el mismo objetivo de latencia o validación.

Use alertas de tasa de consumo y de cambio

Los umbrales estáticos generan ruido. Combínelos con ventanas y líneas base:

• Consumo rápido: el éxito validado cae bruscamente durante 5–15 minutos.
• Consumo lento: el presupuesto de error se agota durante varias horas.
• Alerta de cambio: el éxito en el primer intento cae después de una implementación o una actualización de la política de enrutamiento.
• Anomalía de coste: el coste por tarea aceptada aumenta mientras el tráfico permanece estable.
• Anomalía de enrutamiento: la proporción de fallback o la mezcla de proveedores cambia inesperadamente.
• Anomalía de calidad: los fallos de esquema, política de herramientas o regla de negocio superan la línea base.

Toda alerta debe enlazar a una primera vista de diagnóstico que muestre la versión de implementación, la política de enrutamiento, el proveedor, el modelo, la categoría de error, la etapa de validación, el número de reintentos y la diferencia de coste.

Escriba runbooks antes de escalar alertas

Para cada alerta, defina:

1. Quién es responsable.
2. Qué impacto en el usuario implica.
3. Qué consulta o vista de trazas abrir primero.
4. Qué cambios recientes inspeccionar.
5. Qué mitigación segura está permitida: revertir, deshabilitar una ruta, reducir la concurrencia, abrir un circuito o cambiar a un fallback verificado.
6. Qué evidencia cierra el incidente.

Criterios de salida del paso 4

• Los SLO están definidos por función o nivel de riesgo.
• El éxito validado y el éxito en el primer intento son visibles.
• Las alertas usan ventanas, líneas base o consumo del presupuesto de error.
• Las anomalías de coste y de fallback tienen alertas dedicadas.
• Cada alerta enlaza a un runbook y a una primera consulta de diagnóstico.
• La propiedad de las alertas se prueba durante un ejercicio de guardia.

Paso 5: Implementar la observabilidad con gobernanza

La instrumentación es un cambio de producción. Implántela gradualmente, mida su sobrecarga y haga que el ciclo de vida de los datos forme parte de la implementación, no de una política añadida después.

Use un despliegue gradual

1. Local y pruebas: verifique nombres de campos, spans padre-hijo, redacción y validadores con prompts sintéticos.
2. Telemetría en sombra: emita eventos con forma de producción sin activar paginación ni afectar las decisiones de enrutamiento.
3. Pequeño canary: habilite la telemetría para una parte limitada del tráfico de producción e inspeccione la cardinalidad, el coste de ingesta y la completitud de las trazas.
4. Despliegue por funcionalidad: amplíe por característica del producto o ruta, no para toda la carga de trabajo a la vez.
5. Activación operativa: habilite la generación de informes de SLO y las alertas solo después de que existan datos base y runbooks.

Mida la sobrecarga de la telemetría durante el canary. Incluya el batching del lado del cliente, los fallos del exportador, la presión de la cola y qué ocurre cuando el backend de observabilidad no está disponible. Las solicitudes del modelo no deben fallar porque un exportador de telemetría no crítico esté caído.

Gestione la retención y el acceso

Defina la retención por clase de datos:

• Las métricas agregadas normalmente pueden conservarse durante más tiempo.
• Los metadatos de las solicitudes deben tener un período de retención operativa documentado.
• Las muestras redactadas deben usar una retención más corta y un acceso más restringido.
• Los prompts o salidas sin procesar, si se permiten en absoluto, necesitan un propósito explícito, cifrado, registros de auditoría, comportamiento de eliminación y procedimientos ante incidentes.

Mantenga las claves de API y las credenciales del proveedor fuera de cualquier ruta de telemetría. Siga un patrón de gestión segura de claves API que almacene los secretos en el servidor y evite que los encabezados o las variables de entorno se serialicen en eventos.

Trate el esquema y los paneles como código

Versione el esquema de telemetría, las reglas del validador, las definiciones de SLO, los paneles y las alertas junto con la aplicación. Un cambio de política de ruta debería actualizar tanto la implementación como la observabilidad en la misma versión.

Asigne un responsable para:

• Evolución del esquema
• Reglas de redacción
• Tablas de precios de coste
• Versiones del validador
• Corrección de los paneles
• Ajuste de alertas
• Revisiones de retención y acceso a los datos

Criterios de salida del paso 5

• Las fases de sombra y canary se completaron sin captura insegura de prompts.
• Se probaron la sobrecarga de la telemetría y el comportamiento ante fallos del exportador.
• La retención y el acceso basado en roles están documentados por clase de datos.
• Se excluyen los secretos y los encabezados de autorización.
• Los esquemas, validadores, paneles y alertas están bajo control de versiones.
• Un responsable designado revisa los cambios de telemetría después de actualizaciones del modelo o del enrutamiento.

Un plan de despliegue de observabilidad de IA de 30 días

El cronograma es deliberadamente secuencial. Si el contrato de telemetría cambia durante la semana final, pausa la activación de alertas y repara primero el esquema. Generar paginaciones sobre datos inconsistentes crea una falsa confianza.

Errores comunes de implementación

Contar HTTP 200 como éxito

Corrección: Añade validación de análisis, contrato, política de herramientas y reglas de negocio antes de que la operación pase a accepted.

Ocultar reintentos dentro de un solo span del modelo

Corrección: Crea un span hijo y un registro de coste por cada intento. Conserva el motivo del reintento o del fallback.

Registrar por defecto todos los prompts

Corrección: Usa telemetría solo de metadatos por defecto. Añade contenido muestreado y redactado solo para un caso de uso explícito.

Usar IDs de solicitud como etiquetas de métricas

Corrección: Mantén identificadores de alta cardinalidad en trazas y registros. Usa dimensiones acotadas para las métricas.

Estimar el coste sin versiones de precio

Corrección: Adjunta la versión de la tabla de precios o la marca de tiempo efectiva a cada estimación y concilia después.

Generar alertas sobre errores del proveedor sin contexto del usuario

Corrección: Envía paginaciones por éxito validado, latencia, consumo del presupuesto de errores y cambios inseguros de coste. Usa los errores del proveedor como diagnóstico, salvo que causen impacto en el usuario.

Preguntas frecuentes

¿Qué es la observabilidad de IA?

La observabilidad de IA es la práctica de conectar las solicitudes al modelo con los resultados de la aplicación mediante métricas, trazas, eventos estructurados, resultados de validación, decisiones de enrutamiento, uso de tokens y coste. Va más allá de la supervisión habitual de APIs porque una solicitud de IA puede ser técnicamente correcta pero inutilizable para el producto.

¿Qué debería incluir un panel de observabilidad de IA?

Empieza con la tasa de éxito validado, la tasa de éxito en el primer intento, la latencia de extremo a extremo, el tiempo hasta el primer token, la proporción de reintentos y fallback, los fallos de validación, el uso de tokens y el coste por tarea aceptada. Añade vistas del proveedor y del modelo para el diagnóstico, pero mantén el panel principal alineado con las funciones orientadas al usuario.

¿Deberían registrarse los prompts y las salidas del modelo?

No por defecto. Usa telemetría solo de metadatos para las operaciones normales de producción. Si son necesarios ejemplos de contenido, aplica redacción, muestreo, cifrado, retención corta, controles de acceso y una finalidad explícita. Nunca registres secretos ni cabeceras de autorización.

¿Cómo supervisas las respuestas de IA en streaming?

Mide el tiempo hasta el primer token, el tiempo desde el primer token hasta el último, el estado de cancelación, los bytes o tokens emitidos y si el contenido parcial llegó al usuario antes de un fallo. Define un comportamiento seguro para reintentos y fallbacks después de que comience el streaming.

¿Cómo debe supervisarse el coste de la API de IA?

Registre el uso de entrada, salida, en caché y otro uso informado por el proveedor cuando esté disponible; calcule una estimación inmediata usando una tabla de precios versionada; y reconcílielo con los datos de facturación del proveedor. Haga un seguimiento del coste por tarea aceptada para que los intentos fallidos y las salidas rechazadas sigan siendo visibles.

¿Dónde debe instrumentarse una pasarela multmodelo?

Instrumente tanto la operación de la aplicación como la pasarela. La aplicación sabe si la salida fue útil; la pasarela sabe qué modelo, proveedor, ruta, reintento, fallback y registro de uso la produjo. Use identificadores de solicitud y de traza compartidos para unir ambas capas.

Ponga en práctica la lista de verificación

La vía más rápida hacia una observabilidad de IA útil no es instalar más paneles. Es acordar qué significa una operación de usuario exitosa, rastrear cada intento que contribuye a ello y hacer visibles las decisiones de calidad, coste y enrutamiento en la misma cadena de evidencias.

Flatkey ofrece una vía compatible con OpenAI hacia múltiples modelos de IA mediante una sola clave de API y un único endpoint. Si su equipo está evaluando una arquitectura multmodelo, empiece con la guía de integración de Flatkey y luego aplique esta lista de verificación a la primera funcionalidad en producción. También puede revisar el acceso y los precios actuales de los modelos antes de definir las referencias de coste y las rutas de fallback.