Lista de verificación de implementación de observabilidad de IA: 20 pasos para producción
Una lista de verificación de implementación de observabilidad de IA debería responder a una pregunta más difícil que “¿la API está activa?”. Una función de IA en producción puede devolver HTTP 200 y aun así dar la respuesta incorrecta, usar contexto de recuperación desactualizado, llamar a la herramienta equivocada, reintentar mediante un fallback costoso, filtrar datos sensibles del prompt en los registros o tardar demasiado en ser útil.
El objetivo práctico es conectar cada resultado visible para el usuario con los intentos del modelo, los pasos de recuperación, las llamadas a herramientas, las decisiones de política, la latencia, el uso de tokens y el costo que los produjo. Eso requiere telemetría de aplicación convencional además de contexto y señales de evaluación específicas de IA.
Esta guía proporciona un plan de implementación por fases para aplicaciones LLM, agentes, sistemas de generación aumentada por recuperación y pasarelas multmodelo. Es independiente del proveedor y utiliza conceptos de OpenTelemetry siempre que es posible. También incluye un mapa de señal a decisión, una matriz de pruebas de aceptación, un plan de despliegue de siete días, un contrato de telemetría, un patrón de instrumentación, un manual de respuesta a alertas y una tabla de evaluación de proveedores para que un equipo pueda pasar de los requisitos a un lanzamiento operativo.
La observabilidad de IA en una frase
La observabilidad de IA es la capacidad de explicar el comportamiento, la calidad, la fiabilidad, la seguridad y el costo de un flujo de trabajo de IA a partir de un conjunto correlacionado de trazas, métricas, registros, evaluaciones y resultados de usuario.
La supervisión te dice que un umbral se movió. La observabilidad te ayuda a determinar por qué se movió y qué solicitudes, modelos, prompts, resultados de recuperación, herramientas, inquilinos o versiones estuvieron involucrados.
Usa la lista de verificación de implementación de observabilidad de IA de esta guía como una puerta de lanzamiento, no como un ejercicio de documentación de una sola vez. Vuelve a ejecutarla cada vez que cambies un modelo, prompt, índice de recuperación, esquema de herramienta, política de enrutamiento o evaluador.
Para una aplicación de IA, una solicitud puede contener varios intentos distintos:
acción del usuario
└─ flujo de trabajo de la aplicación
├─ consulta de recuperación
├─ intento del modelo 1
├─ llamada a herramienta
├─ intento del modelo 2
└─ validación y resultado visible para el usuario
Si estos pasos no se pueden unir bajo una sola traza o identidad de solicitud, la depuración se convierte en una conjetura.
El modelo de datos mínimo de observabilidad de IA
El modelo de datos es la base de la lista de verificación de implementación de observabilidad de IA porque cada panel, alerta, evaluación y consulta de incidentes depende de campos de correlación consistentes.
Empieza con una traza a nivel de flujo de trabajo y spans secundarios para cada operación material. OpenTelemetry define trazas, métricas, registros y baggage como señales principales. Sus convenciones semánticas para IA generativa proporcionan un vocabulario en desarrollo para operaciones de modelos y agentes y, a fecha de 4 de agosto de 2026, se mantienen en el repositorio dedicado de convenciones semánticas de OpenTelemetry. Dado que esas convenciones pueden evolucionar, fija la versión que implementes y mantén una pequeña capa interna de compatibilidad en lugar de dispersar nombres de campos específicos de cada proveedor por todo el código.
Como mínimo, captura estos grupos de campos.
| Grupo de campos | Qué registrar | Por qué importa |
|---|---|---|
| Correlación | trace_id, request_id, ID de sesión, flujo de trabajo, entorno, versión |
Une la ruta completa de la solicitud |
| Ruta | proveedor, modelo solicitado, modelo resuelto, región, alias de endpoint o ruta | Explica dónde se ejecutó realmente la solicitud |
| Intento | número de intento, motivo de reintento, origen y destino del fallback | Separa una solicitud de usuario de múltiples llamadas facturables |
| Rendimiento | tiempo en cola, tiempo hasta el primer token, latencia total, latencia de herramientas y de recuperación | Localiza la etapa lenta |
| Uso | entrada, entrada en caché, salida, razonamiento o campos de uso específicos del proveedor | Explica la capacidad y el coste |
| Resultado | estado, clase de error normalizada, motivo de finalización, resultado de validación | Distingue el éxito del transporte del éxito de la tarea |
| Calidad | versión del evaluador, puntuación, aprobado/reprobado, comentarios del usuario, resultado aceptado | Rastrea si la respuesta fue útil |
| Gobernanza | inquilino, decisión de política, estado de redacción, clase de retención | Admite controles de privacidad y auditoría |
Evita tratar el prompt y la respuesta en bruto como campos obligatorios. En muchos sistemas, deberían deshabilitarse de forma predeterminada o almacenarse solo en un conjunto de datos de evaluación controlado por separado.
Mapea cada señal a una decisión operativa
Más telemetría no es automáticamente mejor. Antes de añadir un atributo, métrica o panel, nombra la decisión que respalda y la persona responsable de esa decisión.
| Señal | Pregunta a la que responde | Decisión típica | Responsable principal |
|---|---|---|---|
| Tasa de finalización aceptada | ¿El flujo de trabajo resolvió la tarea del cliente? | Revertir, cambiar prompt/modelo o investigar fallos posteriores | Producto e ingeniería de IA |
| Latencia p95 de extremo a extremo | ¿La experiencia completa es lo suficientemente rápida? | Cambiar la ruta, reducir la latencia de recuperación/herramientas o ajustar la transmisión | Ingeniería de plataforma |
| Tiempo hasta el primer token | ¿La transmisión parece receptiva? | Afinar la cola, la ruta del proveedor o el tamaño del prompt | Ingeniería de plataforma |
| Tasa de fallback | ¿La ruta principal está sana y es económica? | Investigar la salud del proveedor, la capacidad o la política de ruta | Ingeniería de confiabilidad |
| Coste por resultado aceptado | ¿Los reintentos y los resultados de baja calidad están anulando los ahorros? | Cambiar la combinación de modelos, el almacenamiento en caché, el tamaño del prompt o la validación | Ingeniería y FinOps |
| Tasa de aprobación de grounding de recuperación | ¿La respuesta utilizó contexto autorizado y relevante? | Reconstruir el índice, filtros, reranker o validación de citas | Propietario de búsqueda/RAG |
| Fallos de conciliación de herramientas | ¿Se completó de forma segura un efecto secundario externo? | Pausar la herramienta, conciliar el estado o reparar la idempotencia | Propietario de la aplicación |
| Número de fallos de redacción | ¿Los datos sensibles están llegando al exportador? | Detener la exportación, poner en cuarentena la telemetría o actualizar la política | Seguridad/privacidad |
Esta tabla evita el modo de fallo común en el que un panel contiene docenas de gráficos, pero nadie sabe qué acción debería desencadenar un cambio.
A Practical Trace Shape
Use un trace para el flujo de trabajo visible para el usuario, no un trace independiente por cada llamada al proveedor. La raíz debe describir la tarea del cliente, mientras que los spans secundarios describen las operaciones que contribuyeron al resultado.
workflow: answer_support_question
attributes: tenant_class, release, accepted_outcome, final_status
├─ retrieval.search
│ attributes: index_version, top_k, authorization_result
├─ gen_ai.attempt
│ attributes: provider, requested_model, resolved_model, attempt=1
├─ tool.lookup_order
│ attributes: tool_schema_version, idempotency_key, result
├─ gen_ai.attempt
│ attributes: provider, resolved_model, attempt=2, fallback_reason
└─ evaluation.validate_answer
attributes: evaluator_version, pass, score_band
Las convenciones semánticas de IA generativa de OpenTelemetry todavía están evolucionando. Trátelas como un vocabulario compartido, pero fija la versión de la convención, registra cualquier extensión local y prueba las actualizaciones en staging. Mantén resultados de negocio como accepted_outcome en tu propio espacio de nombres de aplicación estable para que un cambio en la convención semántica no rompa los informes del producto.
Phase 1: Define Outcomes Before Adding Dashboards
1. Name the workflow and accepted outcome
No comience con gráficos de tokens a nivel de proveedor. Comience con una tarea del cliente como:
- la respuesta de soporte se acepta sin escalamiento;
- el parche de código pasa las pruebas;
- la extracción coincide con el esquema requerido;
- el agente completa la acción solicitada sin recuperación manual;
- los medios generados pasan la puerta de revisión del producto.
Cree un nombre workflow legible por máquina y un accepted_outcome o resultado equivalente. Esto se convierte en el denominador para las métricas de calidad, costo y confiabilidad.
2. Define the failure taxonomy
Separe al menos estas clases:
- fallo de transporte: tiempo de espera agotado, error de conexión o 5xx ascendente;
- fallo de capacidad: límite de tasa, cuota, saturación de cola o límite de contexto;
- fallo de contrato: JSON no válido, campo faltante, esquema de herramienta no compatible o flujo interrumpido;
- fallo de calidad: la respuesta es irrelevante, incorrecta, incompleta o no está fundamentada;
- fallo de seguridad: violación de la política, éxito de inyección de prompt o ejecución insegura de herramientas;
- fallo de negocio: salida técnicamente válida que el usuario rechaza o abandona.
Una sola dimensión error=true no es suficiente. Oculta si necesita trabajo de infraestructura, un cambio de prompt, un cambio de modelo o un cambio de producto.
3. Choose initial service-level indicators
Comience con un conjunto pequeño que refleje la experiencia del usuario:
workflow availability = accepted workflow completions / eligible workflow starts
quality pass rate = evaluator-passing completions / evaluated completions
p95 end-to-end latency = p95(workflow completed - workflow started)
cost per accepted outcome = total workflow cost / accepted outcomes
Mantén la disponibilidad del proveedor como una métrica de diagnóstico, no como el SLI del producto. Un proveedor puede estar sano mientras tu flujo de trabajo falla porque la recuperación, las herramientas, la validación o el enrutamiento están rotos.
Fase 2: Instrumenta la ruta completa de la solicitud
4. Crea un único span raíz por cada flujo de trabajo visible para el usuario
Genera el trace raíz en el límite de la aplicación, antes de que comiencen la recuperación o el enrutamiento del modelo. Propaga ese contexto a través de colas, workers, gateways, servicios de herramientas y callbacks.
Usa spans secundarios para:
- recuperación y reranking;
- cada intento del modelo;
- cada llamada a herramienta;
- comprobaciones de guardrails o políticas;
- análisis y validación de salida;
- selección de fallback;
- persistencia y entrega posterior.
5. Registra la ruta solicitada y la resuelta
El modelo nombrado por el cliente no siempre es el modelo que atendió la solicitud. Registra ambos:
{
"ai.requested_model": "support-balanced",
"ai.resolved_provider": "provider-b",
"ai.resolved_model": "model-version-2026-07",
"ai.route_reason": "primary_rate_limited",
"ai.attempt": 2
}
Esto es esencial para sistemas multi-proveedor. También hace que una estrategia de fallback de modelo sea auditable en lugar de invisible.
6. Mide el streaming por separado
La latencia total por sí sola no describe una experiencia de streaming. Captura:
- duración de la cola;
- latencia de conexión y del proveedor;
- tiempo hasta el primer token o el primer evento útil;
- duración de generación;
- tiempo de finalización de extremo a extremo;
- tiempo de cancelación del cliente.
Una solicitud puede tener una latencia total aceptable pero un mal tiempo hasta el primer token. También puede producir el primer token rápidamente y luego quedarse bloqueada.
7. Haz que los reintentos y fallbacks sean intentos de primera clase
Nunca sobrescribas el primer intento fallido con el éxito final. Un span de flujo de trabajo debe contener o enlazar cada intento facturable, incluyendo:
- número de reintento;
- disparador;
- duración del backoff;
- proveedor y modelo;
- tokens y coste;
- estado de salida parcial;
- resultado final.
Esto evita que una avalancha de reintentos aparezca como “100% de éxito”.
Fase 3: Añade contexto de calidad específico de IA
8. Versiona prompts, herramientas, políticas y evaluadores
Almacena identificadores estables en lugar de solo contenido bruto:
prompt_version
tool_schema_version
retrieval_index_version
policy_version
evaluator_version
route_policy_version
Estas dimensiones te permiten comparar una versión antes y después de un cambio. Sin versionado, una caída de calidad resulta difícil de atribuir.
9. Haz seguimiento de la calidad de la recuperación
Para la generación aumentada por recuperación, registra:
- versión de la consulta y filtros;
- latencia de recuperación;
- IDs de documento o fragmento;
- frescura de la fuente;
- top-k y versión del reranker;
- tasa de resultados vacíos;
- decisión de control de acceso;
- resultado de validación de citación o grounding.
No coloques documentos privados completos en almacenamiento de traces de uso general. Almacena referencias controladas o hashes, a menos que la política de depuración permita explícitamente capturar contenido.
10. Haz seguimiento de las llamadas a herramientas y de los efectos secundarios
Cada span de herramienta debe incluir el nombre de la herramienta, la versión del esquema, la decisión de autorización, la latencia, el resultado normalizado y si produjo un efecto secundario externo.
Para las herramientas que producen efectos secundarios, también registre una clave de idempotencia y el estado de reconciliación. Esto es importante cuando una llamada al modelo se agota después de que la herramienta ya se haya completado.
11. Combine evaluaciones en línea y fuera de línea
Las señales en línea son rápidas pero ruidosas: pulgar arriba, abandono, regeneración, corrección, escalamiento o finalización de la tarea. Las evaluaciones fuera de línea son más lentas pero controladas: conjuntos de prueba curados, evaluadores con rúbricas, pruebas ejecutables y revisión humana.
Conecte ambas al mismo flujo de trabajo y a los mismos identificadores de versión. No mezcle puntuaciones de distintas versiones de evaluadores en una sola línea de tendencia sin etiquetar el cambio.
Fase 4: Controle la privacidad, la seguridad y la retención
12. Clasifique la telemetría antes de la recopilación
Defina tres niveles:
- Metadatos: ruta, tiempos, tokens, estado, versiones e IDs.
- Señales de contenido derivado: longitud, idioma, categoría de seguridad, puntuación del evaluador o hash.
- Contenido sin procesar: prompts, respuestas, texto recuperado, argumentos de herramientas y resultados de herramientas.
Recopile metadatos de forma amplia. Recopile contenido sin procesar solo cuando el caso de uso, el aviso al usuario, el control de acceso y la política de retención lo permitan.
13. Redacte en el límite de recopilación
La redacción debe ocurrir antes de la exportación siempre que sea posible. Cubra:
- claves de API, tokens bearer, cookies y encabezados de autorización;
- direcciones de correo electrónico, números de teléfono, números de cuenta e identificadores gubernamentales;
- secretos dentro de argumentos de herramientas o documentos recuperados;
- URLs firmadas y cadenas de conexión de bases de datos;
- contenido específico de inquilino prohibido en almacenes de observabilidad compartidos.
Use listas de अनुमति para los atributos exportados. Una lista de denegación acabará omitiendo un nuevo campo que contenga secretos. Aplique la misma disciplina descrita en esta guía de gestión de claves de API de IA.
14. Establezca la retención y el acceso por clase de datos
El contenido sin procesar no debe heredar la misma retención que las métricas de bajo riesgo. Defina almacenamiento, cifrado, roles de acceso, registros de auditoría y procesos de eliminación separados. Pruebe la eliminación en lugar de asumir que un documento de políticas es suficiente.
El Marco de Gestión de Riesgos de IA de NIST y su Perfil de IA Generativa enfatizan la medición continua, la documentación y la gestión de riesgos a lo largo del ciclo de vida del sistema. La observabilidad ayuda a proporcionar evidencia, pero el registro indiscriminado puede crear un nuevo riesgo de privacidad y seguridad.
15. Controle las dimensiones de alta cardinalidad
No convierta IDs de usuario, IDs de trazas, texto de prompts, IDs de documentos o mensajes de error sin procesar en etiquetas de métricas. Mantenga los datos de alta cardinalidad en trazas o registros, y luego derive métricas acotadas como flujo de trabajo, familia de modelo, clase de error, entorno y región.
Fase 5: Construya alertas que apunten a la acción
16. Alerta sobre síntomas que impactan al usuario
Genere una página ante síntomas como:
- tasa de finalización aceptada por debajo del objetivo;
- caída de la tasa de aprobación de calidad más allá del guardarraíl de la versión;
- latencia p95 o tiempo hasta el primer token consumiendo el presupuesto de error;
- costo por resultado aceptado superando su límite;
- efecto secundario inseguro o fallo de política;
- aumento de la tasa de fallback por encima de su banda normal.
Use los errores del proveedor, los picos de tokens y las omisiones de recuperación como alertas de diagnóstico o señales del panel, a menos que amenacen directamente el objetivo orientado al usuario.
17. Use ventanas de burn-rate para las alertas de SLO
Un umbral estático puede generar ruido. La alerta basada en burn-rate del presupuesto de errores pregunta con qué rapidez el servicio está consumiendo el presupuesto permitido de fallos. La guía de SRE de Google recomienda combinar una ventana más rápida con una ventana más lenta de confirmación para que los incidentes graves activen una alerta rápidamente sin hacer accionable cada pico breve.
18. Añada anotaciones de lanzamiento y ruta
Cada panel debería mostrar los lanzamientos de prompt, aplicación, enrutamiento, modelo y evaluador. Añada anotaciones de despliegue y compare cohortes canary frente a control. De lo contrario, el equipo verá moverse una línea sin ver qué cambió.
Fase 6: Validar antes del despliegue completo
19. Ejecute simulacros de fallos
Pruebe al menos:
- timeout upstream;
- límite de velocidad y agotamiento de cuota;
- salida estructurada mal formada;
- interrupción parcial de streaming;
- la recuperación no devuelve ningún contexto autorizado;
- la herramienta tiene éxito pero la respuesta se pierde;
- el fallback cambia el comportamiento del modelo;
- el exportador de telemetría no está disponible;
- la regla de redacción recibe un campo desconocido.
Confirme que el flujo de trabajo falla de forma segura, que la traza permanece coherente y que la alerta identifica al propietario correcto.
20. Despliegue en cuatro etapas
- Shadow: emita telemetría sin cambiar el enrutamiento ni el comportamiento del usuario.
- Canary: habilítelo para una pequeña parte del tráfico y compare la sobrecarga, la cardinalidad y la calidad de los datos.
- Producción con protección: asocie umbrales de lanzamiento y reglas de reversión.
- Producción completa: amplíelo después de que pasen las comprobaciones de privacidad, fiabilidad y coste.
OpenTelemetry admite patrones de muestreo head y tail. Conserve todos los errores y las clases raras de fallos cuando sea posible, y luego muestree el tráfico de éxito rutinario para controlar el coste. Las reglas de muestreo no deben eliminar las trazas exactas necesarias para explicar un incidente.
Matriz de prueba de aceptación en producción
Las pruebas de aceptación demuestran que la lista de verificación de implementación de observabilidad de IA funciona en escenarios de fallo, privacidad y pérdida de telemetría, y no solo en solicitudes exitosas.
No declare completa la observabilidad porque aparezcan spans en un visor de trazas. Ejecute pruebas controladas y guarde evidencia para cada puerta de lanzamiento.
| Prueba | Condición inyectada | Evidencia de telemetría requerida | Condición de aprobación |
|---|---|---|---|
| Tiempo de espera de upstream | Forzar que la ruta primaria del modelo supere su plazo límite | Span del primer intento, clase de timeout, decisión de reintento o fallback, resultado final | No hay spans huérfanos; la disposición final y el costo total son visibles |
| Límite de tasa | Devolver un 429 del proveedor o agotar una cuota de prueba | Código bruto del proveedor, clase de capacidad normalizada, duración del backoff, cambio de ruta | El presupuesto de reintentos está limitado y la alerta apunta al propietario de la ruta |
| Salida estructurada inválida | Devolver JSON mal formado o un campo requerido ausente | Span de validación de contrato, versión del validador, intento de reparación, resultado final aprobado/fallido | El éxito HTTP no se cuenta como éxito aceptado |
| Flujo interrumpido | Interrumpir la salida después del primer token | Tiempo hasta el primer token, indicador de salida parcial, uso facturable, decisión de reintento | Se evitan el contenido duplicado y la doble ejecución de herramientas |
| Recuperación vacía | No devolver ningún documento autorizado | Filtros de recuperación, resultado de autorización, motivo de resultado vacío, política de respuesta | El sistema sigue el comportamiento aprobado sin contexto |
| Ambigüedad de herramienta | Permitir que una herramienta finalice mientras la solicitud del modelo agota el tiempo de espera | Clave de idempotencia, estado de efecto secundario, resultado de reconciliación | La herramienta no se ejecuta dos veces y el estado es recuperable |
| Canario de redacción | Insertar un secreto sintético en un campo de prueba | Evento de detección local sin valor de secreto exportado | La exportación se bloquea o se redacta antes de salir del límite |
| Caída del exportador | Detener el destino de telemetría | Métricas de cola/pérdida del exportador y salud de la aplicación | El tráfico de usuarios permanece dentro de su presupuesto de confiabilidad |
| Verificación de muestreo | Generar errores poco frecuentes entre un alto volumen de tráfico exitoso | Se conservan los traces de error; los éxitos rutinarios se muestrean según la configuración | Los ejemplos del incidente siguen siendo buscables después del muestreo |
| Regresión de lanzamiento | Desplegar un canary con degradación conocida de latencia o calidad | Anotación de lanzamiento, cohorte canary, cohorte de control, comparación de SLI | El umbral de rollback se activa con un propietario del cambio identificable |
Para cada prueba, registre el propietario, la fecha de la prueba, el ID del trace, la alerta esperada, la alerta observada y el ticket de remediación. Esto convierte la observabilidad en un control de lanzamiento repetible en lugar de un proyecto de instrumentación de una sola vez.
Plan de implementación de siete días
Para un equipo enfocado, la lista de verificación de implementación de observabilidad de IA puede implementarse como una secuencia de siete días que deja evidencia revisable al final de cada día.
Esta secuencia es intencionalmente acotada. Entrega primero una sección vertical confiable antes de que el equipo amplíe la cobertura.
- Día 1 — Contrato de resultados: elija un flujo de trabajo de alto valor, defina inicios elegibles, resultados aceptados, clases de fallo y fórmulas de SLI.
- Día 2 — Esqueleto de trazas: cree el span raíz del flujo de trabajo y propague el contexto a través de la aplicación, la cola, la pasarela, la capa de recuperación y las herramientas.
- Día 3 — Intentos del modelo: capture las rutas solicitadas y resueltas, los intentos, la latencia, el motivo de finalización, el uso del proveedor, los reintentos y los mecanismos de respaldo.
- Día 4 — Calidad y coste: combine los resultados del validador, las versiones del evaluador, los resultados de los usuarios y el coste normalizado del flujo de trabajo.
- Día 5 — Controles de privacidad: clasifique los campos, implemente la exportación de la lista de अनुमति allowlist, pruebe la redacción, establezca la retención y verifique los límites de acceso.
- Día 6 — SLO y paneles: construya el panel mínimo, añada anotaciones de versiones, defina alertas de burn rate y asigne responsables.
- Día 7 — Simulacros de fallo: ejecute la matriz de aceptación, corrija las brechas, inicie un canario y documente las condiciones de reversión.
Al final del séptimo día, el objetivo no es la instrumentación universal. El objetivo es un flujo de trabajo en producción cuyo comportamiento, calidad, fiabilidad, seguridad y coste puedan explicarse de principio a fin.
Panel mínimo para el lanzamiento
El panel es la vista operativa de la lista de verificación de implementación de observabilidad de IA. Debe mostrar primero los resultados del cliente y después los detalles de infraestructura.
Mantenga la primera vista operativa lo bastante pequeña como para usarla durante un incidente:
- Fila de resultados: inicios elegibles, completions aceptadas, tasa de aprobación de calidad y abandono o escalado.
- Fila de fiabilidad: errores normalizados, tasa de fallback, amplificación por reintentos y consumo del presupuesto de error.
- Fila de latencia: p50/p95/p99 de extremo a extremo, tiempo en cola, tiempo hasta el primer token, latencia de recuperación y latencia de herramientas.
- Fila de economía: tokens de entrada/salida/en caché, coste total del flujo de trabajo y coste por resultado aceptado.
- Fila de cambios: versiones de la aplicación, del prompt, de la política de rutas, del modelo, del índice de recuperación, del esquema de herramientas y del evaluador.
- Enlaces de investigación: trazas representativas para cada clase de fallo, versión, ruta y flujo de trabajo afectado.
El panel debe admitir una ruta desde el síntoma hasta la traza. Si una alerta muestra una caída de calidad pero el equipo no puede llegar a las trazas del flujo de trabajo afectado en unos pocos clics, el ciclo de investigación está incompleto.
Tarjeta de evaluación de la plataforma de observabilidad de IA
La evaluación comercial debe comprobar si una plataforma admite su modelo operativo, no si tiene la lista de funciones más larga. Califique a los candidatos frente a la misma carga de trabajo piloto instrumentada.
| Criterio | Peso | Qué verificar en un piloto |
|---|---|---|
| Correlación del flujo de trabajo | 20% | Un único trace une los intentos del modelo, la recuperación, las herramientas, la validación y el resultado del usuario |
| Interoperabilidad de OpenTelemetry | 15% | La exportación/importación estándar funciona; las extensiones locales siguen siendo consultables; los datos son portables |
| Uniones de calidad y evaluación | 15% | La retroalimentación en línea y las evaluaciones offline versionadas se conectan con los traces de producción |
| Privacidad y gobernanza | 15% | Listas de अनुमतिidas de campos, redacción, controles regionales, roles de acceso, registros de auditoría y pruebas de eliminación |
| Operaciones de fiabilidad | 15% | SLOs, alertas de burn rate, controles de muestreo, anotaciones de lanzamiento y soporte para simulacros de incidentes |
| Atribución de costes | 10% | El uso del proveedor, los reintentos, los fallbacks, los tokens en caché y el coste por resultado aceptado se concilian |
| Cobertura de agente/RAG/herramientas | 5% | Las operaciones de recuperación y de herramientas con efectos secundarios tienen spans y filtros de primera clase |
| Coste operativo | 5% | La ingesta, el almacenamiento, las consultas, la retención y la sobrecarga de ingeniería se ajustan al volumen esperado |
Utilice una puntuación de 1 a 5 para cada criterio, multiplíquela por el peso y exija evidencia escrita del piloto. Una plataforma que no puede preservar su contrato de telemetría o exportar sus datos crea dependencia operativa incluso si sus paneles lucen pulidos.
Contrato de telemetría copiables
La forma más rápida de hacer operativo un AI observability implementation checklist es convertirlo en un contrato de telemetría versionado. El contrato define qué debe emitir cada flujo de trabajo e intento del modelo, qué campos son opcionales, qué valores están permitidos y qué campos están prohibidos en índices de alto volumen.
El ejemplo siguiente usa un espacio de nombres interno. Asígnelo a las convenciones fijadas de OpenTelemetry GenAI dentro de un solo adaptador, en lugar de exponer el código de la aplicación a cambios en las convenciones.
telemetry_contract:
version: "2026-08-04"
workflow_span:
required:
- ai.workflow.name
- ai.workflow.version
- ai.request.id
- deployment.environment
- service.version
- ai.outcome.status
- ai.outcome.accepted
- ai.latency.total_ms
optional:
- ai.tenant.tier
- ai.experiment.id
- ai.user.feedback
prohibited:
- end_user.email
- end_user.name
- raw.authorization_header
model_attempt_span:
required:
- ai.attempt.number
- ai.route.requested_model
- ai.route.resolved_provider
- ai.route.resolved_model
- ai.result.status
- ai.usage.input_tokens
- ai.usage.output_tokens
- ai.latency.first_token_ms
- ai.latency.total_ms
conditional:
- ai.fallback.reason
- ai.error.class
- ai.error.provider_code
- ai.usage.cached_input_tokens
content_capture:
default: "off"
allowed_when:
- approved_evaluation_dataset
- explicit_debug_session
controls:
- redact_before_export
- access_logged
- retention_approved
Revisa este contrato en la revisión de código igual que un esquema de API. Un nuevo proveedor de modelo, herramienta de agente, política de fallback o evaluador no debería pasar a producción hasta que sus campos de telemetría se asignen al contrato y aprueben las mismas pruebas de aceptación.
Patrón de instrumentación para un flujo de trabajo de IA
No permitas que cada equipo invente de forma independiente los nombres de spans y los atributos. Proporciona un pequeño wrapper que cree el span raíz del flujo de trabajo, registre los intentos secundarios, capture resultados normalizados y aplique la redacción antes de la exportación.
Este ejemplo en Python es deliberadamente neutral respecto al proveedor. Los nombres internos de los atributos deben traducirse a tu versión fijada de la convención semántica de OpenTelemetry en la capa del wrapper o del colector.
from opentelemetry import trace
tracer = trace.get_tracer("checkout-assistant")
def run_ai_workflow(request, router, evaluator):
with tracer.start_as_current_span("ai.workflow.checkout_help") as workflow_span:
workflow_span.set_attribute("ai.workflow.name", "checkout_help")
workflow_span.set_attribute("ai.workflow.version", "2026-08-04")
workflow_span.set_attribute("ai.request.id", request.request_id)
result = None
for attempt_number in range(1, 3):
with tracer.start_as_current_span("ai.model.attempt") as attempt_span:
route = router.resolve(request, attempt_number)
attempt_span.set_attribute("ai.attempt.number", attempt_number)
attempt_span.set_attribute("ai.route.requested_model", request.model)
attempt_span.set_attribute("ai.route.resolved_provider", route.provider)
attempt_span.set_attribute("ai.route.resolved_model", route.model)
result = route.generate(request)
attempt_span.set_attribute("ai.result.status", result.status)
attempt_span.set_attribute("ai.usage.input_tokens", result.input_tokens)
attempt_span.set_attribute("ai.usage.output_tokens", result.output_tokens)
if result.status == "ok":
break
attempt_span.set_attribute("ai.error.class", result.error_class)
evaluation = evaluator.score(request, result)
workflow_span.set_attribute("ai.outcome.status", result.status)
workflow_span.set_attribute("ai.outcome.accepted", evaluation.accepted)
workflow_span.set_attribute("ai.evaluator.version", evaluation.version)
workflow_span.set_attribute("ai.quality.score", evaluation.score)
return result
El código de producción también debería registrar la duración, el tiempo hasta el primer token, los motivos de fallback, la cancelación, los errores de streaming y las excepciones. La decisión de diseño importante es la jerarquía: un flujo de trabajo del cliente contiene uno o más intentos facturables, y el flujo de trabajo registra el resultado final aceptado.
Política de alertas y runbook de primera respuesta
Una lista de verificación de implementación de observabilidad de IA está incompleta si los paneles no tienen reglas de respuesta. Cada métrica de lanzamiento necesita un desencadenante, un responsable y una primera consulta de diagnóstico.
| Alerta | Ejemplo de desencadenante | Primera pregunta | Acción inmediata |
|---|---|---|---|
| Consumo del resultado aceptado | Consumo rápido y lento del presupuesto de error | ¿Qué flujo de trabajo, versión, ruta o inquilino cambió? | Pausar el despliegue o revertir la versión implicada |
| Regresión de latencia | La latencia p95 del flujo de trabajo incumple el SLO | ¿Se movió la latencia de cola, recuperación, modelo o herramienta? | Desviar alrededor de la etapa lenta o reducir la carga |
| Aumento de fallback | La tasa de fallback supera su banda normal | ¿El proveedor principal está fallando, limitando o agotando el tiempo de espera? | Inspeccionar los errores normalizados y sin procesar del proveedor |
| Repunte del costo por resultado | El costo aumenta mientras la aceptación se mantiene plana o cae | ¿Están aumentando los reintentos, la longitud de salida o las rutas costosas? | Limitar los reintentos y restaurar la política de rutas anterior |
| Caída de la puntuación de calidad | La tasa de aprobación del evaluador en línea o muestreado cae | ¿Cambió la versión del prompt, la recuperación, el modelo o el evaluador? | Comparar la cohorte de la versión con la última cohorte saludable |
| Incertidumbre de herramienta | No se puede reconciliar el resultado del efecto secundario | ¿La herramienta terminó antes del tiempo de espera o la cancelación? | Detener el reintento automático y entrar en reconciliación |
| Pérdida de telemetría | Disminuye la completitud esperada de spans o uso | ¿La instrumentación está rota o aumenta la presión de exportación? | Tratar la telemetría faltante como un incidente operativo |
La vista de guardia debería enlazar directamente desde una alerta a los traces filtrados por flujo de trabajo, versión, modelo solicitado, ruta resuelta y clase de error. Si los responsables deben reconstruir manualmente esos filtros durante un incidente, el sistema no está listo para lanzarse.
Propiedad y entrega a producción
Asigne la lista de verificación a roles nombrados antes del despliegue. La propiedad compartida sin un responsable explícito suele producir paneles que todos pueden ver y que nadie mantiene.
| Responsabilidad | Rol responsable | Evidencia de entrega requerida |
|---|---|---|
| Definición del resultado del flujo de trabajo | Propietario del producto o de la funcionalidad de IA | Regla de resultado aceptado y ejemplos de rechazo |
| Esquema de spans y métricas | Propietario de plataforma u observabilidad | Contrato de telemetría versionado y pruebas de esquema |
| Campos de ruta y fallback | Propietario de gateway o confiabilidad | Validación de ruta solicitada/resuelta e intentos |
| Evaluadores de calidad | Propietario de ingeniería de IA | Versión del evaluador, conjunto de datos, umbrales, límites conocidos |
| Privacidad y retención | Propietario de seguridad o privacidad | Clasificación de datos, prueba de redacción, aprobación de retención |
| SLOs y alertas | Propietario del servicio | Documento SLO, reglas de paging, panel, runbook |
| Asignación de costos | Propietario de finanzas de ingeniería | Completitud de uso y conciliación del costo por resultado |
| Preparación para lanzamiento | Líder de ingeniería | Matriz de aceptación completada y desencadenante de rollback |
Programa una revisión a los 30 días después del lanzamiento. Elimina los campos no utilizados, promueve las consultas de depuración usadas repetidamente a vistas de panel, revisa la cardinalidad y el costo de almacenamiento, y actualiza el contrato cuando cambie el comportamiento del flujo de trabajo.
Lista de verificación de implementación de observabilidad de IA copiable
Usa esta lista como criterio de lanzamiento:
- [ ] Define cada flujo de trabajo y el resultado de cliente aceptado.
- [ ] Define fallos de transporte, capacidad, contrato, calidad, seguridad y negocio.
- [ ] Selecciona SLIs de disponibilidad, calidad, latencia y costo por resultado.
- [ ] Aprueba un contrato de telemetría versionado con campos obligatorios, opcionales y prohibidos.
- [ ] Crea un trace raíz por cada flujo de trabajo visible para el usuario.
- [ ] Propaga el contexto a través de colas, herramientas, recuperación y gateways.
- [ ] Registra las rutas solicitadas y resueltas del proveedor/modelo.
- [ ] Crea un span separado para cada reintento e intento de fallback.
- [ ] Captura el tiempo en cola, el tiempo hasta el primer token y la latencia total.
- [ ] Captura el uso de tokens informado por el proveedor y el costo normalizado.
- [ ] Versiona prompts, herramientas, índices de recuperación, políticas, rutas y evaluadores.
- [ ] Registra referencias de recuperación, frescura, autorización y resultados de grounding.
- [ ] Registra la autorización de la herramienta, la idempotencia, el resultado y el estado de efecto secundario.
- [ ] Relaciona la opinión del usuario y los resultados de la evaluación offline con los traces.
- [ ] Clasifica la telemetría como metadatos, señales derivadas o contenido bruto.
- [ ] Redacta secretos y campos sensibles antes de exportar.
- [ ] Aplica políticas separadas de retención y acceso por clase de datos.
- [ ] Mantén los valores de alta cardinalidad fuera de las etiquetas de métricas.
- [ ] Configura alertas sobre SLOs que afectan al usuario y el consumo del presupuesto de error.
- [ ] Anota los lanzamientos y compara canary frente a control.
- [ ] Ejecuta simulacros de fallo, privacidad, muestreo y caída del exportador.
- [ ] Guarda evidencia de pruebas de aceptación e IDs de trace para el criterio de lanzamiento.
- [ ] Compara las plataformas de observabilidad con una única tarjeta de puntuación ponderada de piloto.
- [ ] Asigna responsables claros para resultados, esquema, privacidad, SLOs, calidad y costo.
- [ ] Vincula cada alerta que merezca una página con un runbook de primera respuesta y una consulta de trace.
Errores comunes de observabilidad de IA
Registrar prompts sin una política de datos
Los prompts sin procesar parecen útiles durante la depuración, pero pueden contener datos de clientes, secretos, material protegido por derechos de autor o información regulada. Comienza con metadatos y habilita la captura controlada de contenido solo cuando esté justificada.
Medir el costo por solicitud en lugar del costo por resultado
Una solicitud barata que falla la validación no es barata. Los reintentos, los fallbacks y la corrección humana forman parte del costo del flujo de trabajo. El mismo principio se aplica al ROI del caché de prompts: optimiza la tarea aceptada, no una tasa de tokens aislada.
Tratar cada llamada al modelo como independiente
Los agentes y los sistemas RAG son flujos de trabajo. Si los spans del modelo, la recuperación y las herramientas no están correlacionados, el equipo no puede reconstruir la causalidad.
Depender de un solo panel del proveedor
Los paneles del proveedor son útiles para el uso y los errores aguas arriba, pero no ven el resultado completo de tu aplicación, el sistema de recuperación, la ejecución de herramientas, la opinión del usuario ni la ruta de fallback entre proveedores.
Instrumentar todo antes de definir decisiones
La telemetría tiene un costo operativo. Cada campo debe respaldar una decisión de depuración, alertas, evaluación, gobernanza u optimización. Elimine los campos que nadie usa.
Dónde encaja una puerta de enlace de IA
Una puerta de enlace de LLM puede ser un límite útil de correlación y de políticas porque varias aplicaciones y proveedores pasan por un único punto de control. Puede normalizar los metadatos de ruta, intento, uso, latencia y errores antes de exportar la telemetría a su stack de observabilidad.
La puerta de enlace no es la solución completa. El código de la aplicación sigue siendo responsable de los resultados del flujo de trabajo, el contexto de recuperación, la semántica de las herramientas, la retroalimentación del usuario y la conversión de negocio. El diseño más sólido une la telemetría de la puerta de enlace con esas señales a nivel de aplicación.
Flatkey ofrece una capa de acceso compatible con OpenAI para varios modelos de IA. Si su equipo está consolidando integraciones con proveedores, explore Flatkey y use esta lista de verificación para definir el contrato de telemetría alrededor de su aplicación y su capa de enrutamiento.
Preguntas frecuentes
¿Qué debería implementar primero para la observabilidad de IA?
Comience la lista de verificación de implementación de observabilidad de IA con un trazo raíz por cada flujo de trabajo de cliente, spans secundarios de intentos de modelo, campos de modelo solicitado y resuelto, latencia, uso, errores normalizados y una señal de resultado aceptado. Añada más adelante la captura del prompt sin procesar, si su política de privacidad lo permite.
¿Es suficiente OpenTelemetry para la observabilidad de LLM?
OpenTelemetry proporciona la base agnóstica al transporte para trazas, métricas y registros, además de convenciones semánticas de IA generativa en evolución. Aun así, necesita definiciones de flujo de trabajo, evaluaciones, controles de privacidad, SLO, paneles e प्रक्रesses de incidentes.
¿Deberían almacenarse los prompts y las respuestas en las trazas?
No por defecto. Primero use metadatos, versiones, hashes y señales de calidad derivadas. Almacene el contenido sin procesar solo en sistemas controlados con un propósito explícito, política de acceso, periodo de retención y proceso de eliminación.
¿Qué métricas de observabilidad de IA importan más?
Empiece con la tasa de finalización aceptada, la tasa de aprobación de calidad, la latencia de extremo a extremo p95, el tiempo hasta el primer token para streaming, la tasa de fallback y el costo por resultado aceptado. Añada después métricas específicas del flujo de trabajo cuando estas sean confiables.
¿Cómo monitorizo varios proveedores de IA?
Use un único esquema de telemetría estable en todos los proveedores. Registre tanto la ruta solicitada como el proveedor/modelo resuelto en cada intento, normalice los errores sin descartar el código original del proveedor y vincule todos los intentos bajo la misma traza del flujo de trabajo.
