Observabilidad de LLM en una puerta de enlace API multimodelo: seguimientos, libros de contabilidad de tokens, análisis de inquilinos y registro de avisos seguro

El recuento total de solicitudes y el gasto mensual no son suficientes cuando un cliente pregunta por qué un flujo de trabajo se volvió más lento, más caro o menos confiable ayer. Una puerta de enlace API multimodelo puede responder a esa pregunta si trata la observabilidad como parte del plano de control: cada solicitud obtiene un seguimiento, cada llamada de modelo actualiza un libro de registro de uso, cada inquilino y flujo de trabajo es atribuible y el contenido confidencial está protegido de forma predeterminada.

Este artículo describe un diseño práctico para análisis de uso de IA y observabilidad de LLM en una puerta de enlace que enfrenta múltiples proveedores a través de una API compatible con OpenAI. El patrón es útil incluso si no utiliza ningún proveedor específico: instrumente una vez en la puerta de enlace, normalice la telemetría del modelo, preserve la atribución de facturación y capture contenido rápido solo bajo una política explícita.

El problema del lector: "¿Qué inquilino, modelo, solicitud o ruta de recuperación provocó el cambio?"

La mayoría de los equipos eventualmente enfrentan la misma brecha de depuración. Los registros de la aplicación muestran que una función falló. Los paneles de los proveedores muestran que el uso de tokens aumentó. Finanzas ve una factura. Ninguna de esas vistas, por sí sola, explica la ruta completa desde la solicitud del inquilino hasta la llamada del modelo, el contexto de recuperación y el reintento hasta el costo facturado.

El objetivo no es otro panel con tokens totales. El objetivo es responder preguntas operativas como:

• ¿Qué inquilino o clave de API provocó un aumento en el gasto?
• ¿Aumentó la latencia después de que se cambió el alias de un modelo?
• ¿Los reintentos o las alternativas tienen un costo de contabilización doble?
• ¿Qué versión del mensaje consume más presupuesto de errores?
• ¿Un flujo de trabajo RAG se volvió costoso porque la recuperación agregó demasiados tokens de contexto?
• ¿Se puede admitir la depuración de un incidente sin leer las indicaciones privadas de los usuarios?

Hechos, recomendaciones y predicciones

Datos: OpenTelemetry documenta atributos y convenciones semánticas de IA generativa para operaciones de modelos, incluidos nombres de operaciones como chat, generate_content y text_completion. La misma documentación advierte que los atributos de los mensajes de entrada y salida de GenAI pueden contener información confidencial o PII y pueden requerir filtrado o truncamiento. Los principales proveedores de modelos también exponen paneles de uso, API o exportaciones que pueden admitir la conciliación del lado del proveedor, aunque los detalles difieren según el proveedor.

Recomendaciones: utilice OpenTelemetry para seguimientos neutrales del proveedor, pero mantenga las dimensiones comerciales propiedad de la puerta de enlace en sus propios atributos y libros de contabilidad. No almacene mensajes ni resultados sin procesar de forma predeterminada. Almacene primero metadatos, hashes, recuentos de tokens, ID de plantillas de solicitud, nombres de esquemas, clases de error y etiquetas de seguridad. Agregue la captura de contenido solo como una función de depuración de retención breve, de acceso controlado y voluntaria.

Predicción: La observabilidad de LLM se centrará menos en paneles de control de proveedores aislados y más en planos de control entre proveedores. Los equipos esperarán un lugar para investigar la latencia, el costo, la calidad, los eventos de políticas, el comportamiento de los inquilinos y las diferencias de facturación en todos los modelos.

Arquitectura de referencia: observe toda la ruta de la solicitud

Una puerta de enlace puede ver el ciclo de vida completo de la solicitud sin necesidad de que cada equipo de aplicaciones cree una telemetría personalizada. Un modelo de seguimiento útil comienza con un intervalo principal para la solicitud entrante del cliente y intervalos secundarios para los pasos que afectan el costo, la latencia y la calidad.

Estructura de luz recomendada

• Intervalo de solicitudes de puerta de enlace: solicitud aceptada, autenticada, autorizada, con velocidad limitada y enrutada.
• Duración de llamadas del modelo: proveedor, modelo, operación, uso de token, estado de respuesta y latencia.
• Intervalo de recuperación: índice consultado, ID de documento o ID hash, recuento de fragmentos, latencia de recuperación y uso compartido de token de contexto.
• Intervalo de llamadas de herramientas: nombre de la herramienta, estado, latencia, clase de error y clasificación de efectos secundarios.
• Intervalo de reintentos: motivo del reintento, número de intentos, estado del proveedor y costo incremental.
• Intervalo de respaldo: modelo original, modelo de respaldo, activador, política de compatibilidad y resultado final.
• Barrera de seguridad o período de moderación: política invocada, decisión, etiquetas y si la salida se bloqueó o transformó.
• Lapso de posprocesamiento: validación JSON, reparación de esquemas, verificación de citas o formato final.

El intervalo principal debe contener identificadores de correlación estables. Los tramos secundarios deben tener atributos técnicos normalizados. El libro de contabilidad de uso debe contener registros duraderos de facturación y análisis. Evite forzar toda la información en etiquetas de métricas; Los valores de alta cardinalidad, como los ID de inquilinos, los hashes de solicitud y los ID de documentos, se almacenan mejor en seguimientos, registros o tablas de contabilidad y luego se agregan en paneles.

Normalizar los metadatos capturados en cada llamada de LLM

Cada solicitud de modelo debe producir un registro coherente, independientemente del proveedor. El esquema exacto variará, pero un mínimo práctico se ve así:

{
  "request_id": "req_01J...",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tenant_id": "tenant_123",
  "team_id": "team_456",
  "app_id": "support_bot",
  "gateway_key_id": "key_789",
  "operación": "chat",
  "proveedor": "nombre_proveedor",
  "modelo": "id-modelo-proveedor",
  "model_alias": "chat-de-soporte-rápido",
  "prompt_template_id": "refund_policy_v5",
  "prompt_hash": "sha256:...",
  "response_schema": "support_answer_v2",
  "estado": "completado",
  "error_class": nulo,
  "latencia_ms": 1842,
  "tokens de entrada": 2110,
  "tokens_salida": 384,
  "tokens_input_cached": 1200,
  "estimated_cost_usd": "0.00492",
  "final_billed_cost_usd": nulo,
  "finish_reason": "detener",
  "retry_count": 0,
  "fallback_used": falso,
  "content_capture_policy": "metadata_only"
}

Mantenga dos ideas separadas: la telemetría explica lo que sucedió, mientras que el libro mayor de uso registra lo que se debe cobrar, conciliar y reportar. Se hacen referencia entre sí con ID de solicitud e ID de seguimiento, pero no es necesario que vivan en el mismo sistema de almacenamiento.

Cree un libro de contabilidad de costos y tokens, no solo contadores

Los contadores de tokens son útiles para los gráficos, pero no son suficientes para la facturación o la investigación de incidentes. Un libro de contabilidad debería representar las transiciones de estado. Cree una fila cuando la puerta de enlace acepte una solicitud y luego actualícela a medida que avanza la solicitud.

Estados útiles del libro mayor

• aceptado: se aprobaron las comprobaciones de autenticación y políticas.
• reenviada: la solicitud fue enviada a un proveedor.
• transmisión: el proveedor comenzó a devolver tokens.
• completado: la respuesta finalizó exitosamente.
• user_aborted: el cliente se desconectó antes de completarse.
• reintentado: se realizó un intento adicional del proveedor.
• fallback_used: se seleccionó un modelo o proveedor diferente después de un error o una coincidencia de políticas.
• falló: la solicitud finalizó sin una respuesta utilizable.
• conciliado: se compararon y aplicaron los datos de costos o uso del proveedor.

Este modelo de estado ayuda a detectar errores comunes de facturación y análisis: respuestas transmitidas en las que el cliente se desconectó, intentos de reintento cobrados por el proveedor pero ocultos al usuario, rutas alternativas que contaban el modelo incorrecto y diferencias de contabilidad de caché entre proveedores.

Utilice las convenciones de OpenTelemetry GenAI y luego amplíelas con cuidado

Las convenciones semánticas de OpenTelemetry GenAI proporcionan un vocabulario portátil para operaciones de modelos. Utilice esas convenciones para atributos comunes como el nombre de la operación, el proveedor, el modelo, los parámetros de la solicitud, los motivos de finalización de la respuesta, el uso del token y el estado de error cuando corresponda.

Sin embargo, las convenciones neutrales sobre el proveedor no cubrirán todas las dimensiones comerciales de una puerta de enlace. Agregue atributos propiedad de la puerta de enlace o columnas del libro mayor para:

• ID de inquilino, ID de equipo, ID de cliente revendedor e ID de aplicación;
• ID de clave API de puerta de enlace y alcance de clave;
• plan de facturación, límite de gasto y política presupuestaria;
• alias del modelo y versión de la política de enrutamiento;
• ID de plantilla de solicitud y versión de solicitud;
• nombre del flujo de trabajo y paso del flujo de trabajo;
• coste estimado, costo final facturado y estado de conciliación.

La contrapartida es la cardinalidad. Estos campos son valiosos para la investigación, pero pueden hacer que las métricas sean costosas y ruidosas si se usan como etiquetas de métricas en todas partes. Una regla práctica es: los agregados de baja cardinalidad van a las métricas; Los identificadores de alta cardinalidad van a seguimientos, registros y libros de contabilidad.

Diseñar registros de mensajes y salidas seguros

El registro rápido completo facilita la depuración, pero aumenta la privacidad, el cumplimiento, el almacenamiento y la exposición a riesgos internos. El valor predeterminado más seguro es la observabilidad de los metadatos primero.

Predeterminado: solo metadatos

Para la mayor parte del tráfico de producción, almacene:

• ID y versión de la plantilla del mensaje;
• hashes de mensajes y resultados normalizados;
• recuento de tokens de entrada, salida, caché y contexto;
• nombre del esquema de respuesta y resultado de la validación;
• etiquetas de seguridad y decisiones políticas;
• resúmenes de errores y clases de errores del proveedor;
• Recuperación de metadatos, no documentos sin procesar.

Suscripción: captura de contenido controlada

Si necesita contenido sin editar o redactado para una depuración profunda, solicite una política explícita. Los buenos controles incluyen listas de entorno permitido, consentimiento de inquilinos, muestreo, longitud máxima de carga útil, redacción automática, ventanas de retención cortas, cifrado, acceso basado en roles, registros de auditoría y una ruta de aprobación inmediata para incidentes sensibles.

No trate la redacción como perfecta. Reduce el riesgo; no lo elimina. Para cargas de trabajo reguladas o de alta sensibilidad, considere almacenar solo hashes y reproducir problemas en un arnés sintético con datos de prueba aprobados.

Agregar observabilidad RAG como una capa separada

La generación con recuperación aumentada puede cambiar tanto la calidad como el costo. Registrar solo la llamada del modelo final oculta la causa raíz cuando el recuperador devuelve demasiados fragmentos, documentos obsoletos o contexto irrelevante.

Para cada paso de recuperación, capture:

• nombre del índice o colección;
• estrategia de recuperación y modelo de incorporación;
• ID de documento o ID hash;
• recuento de fragmentos y tokens de contexto totales;
• latencia de recuperación;
• distribución de puntuación máxima, si está disponible;
• cobertura de citación;
• si se utilizó el contexto recuperado en la respuesta final.

Esto le permite distinguir "el modelo empeoró" de "el recuperador comenzó a enviar contexto excesivo o de baja calidad". También ayuda a identificar flujos de trabajo donde los tokens de contexto dominan el costo total.

Conciliar el uso de la puerta de enlace con la facturación del proveedor

Las estimaciones de la puerta de enlace están disponibles de inmediato. Los datos de facturación del proveedor suelen ser más lentos pero más autorizados. Utilice ambos.

Un trabajo de conciliación diario debe comparar las filas del libro mayor de la puerta de enlace con las API de uso del proveedor, las API de costos, las exportaciones de paneles o las exportaciones de facturas. Agrupe deltas por proveedor, modelo, proyecto y ventana de tiempo. Realice un seguimiento de las diferencias por separado para tokens de entrada, tokens de salida, tokens almacenados en caché, recuentos de solicitudes y costos.

Diferencias de conciliación comunes

• La transmisión se desconecta: la puerta de enlace puede ver un cliente cancelado mientras el proveedor aún factura los tokens generados.
• Reintentos: se pueden facturar varios intentos incluso si solo se devuelve una respuesta final.
• Almacenamiento en caché rápido: los proveedores pueden exponer la contabilidad de tokens almacenados en caché de manera diferente.
• Redondeo: las pequeñas diferencias por solicitud pueden hacerse visibles a escala.
• Descuentos por lotes o niveles: las facturas de los proveedores pueden aplicar precios que la estimación en tiempo real aún no conocía.
• Cambios por parte del proveedor: el precio del modelo, el comportamiento de tokenización o las exportaciones de facturación pueden cambiar con el tiempo.

Cuando la conciliación encuentre un delta, evite sobrescribir silenciosamente su libro mayor. Almacene la estimación original, el valor conciliado por el proveedor, la fuente de conciliación y el código de motivo, si se conoce.

Paneles que responden a preguntas operativas

Inicie paneles a partir de problemas de lectores, no de métricas vanidosas. Las vistas útiles incluyen:

• coste por inquilino, equipo, aplicación y flujo de trabajo;
• coste por tarea exitosa, no solo costo por solicitud;
• Latencia p50, p95 y p99 por proveedor, modelo y alias de modelo;
• tasa de retorno y tasa de reintentos por ruta;
• tasa de tiempo de espera y tendencias de clase de error del proveedor;
• proporción de aciertos de caché y estimación de ahorro de tokens almacenados en caché;
• tasa de fallas en la validación de resultados estructurados;
• versiones de avisos principales por consumo de presupuesto de error;
• Compartición de tokens de contexto RAG por flujo de trabajo;
• Bloques de barandilla y golpes de clasificador de inyección rápida.

Para alertas, combine señales técnicas y comerciales. Un aumento repentino en el gasto de los inquilinos puede ser más urgente que un pequeño aumento de la latencia global. Un salto en la tasa de respaldo después de un cambio de alias de modelo puede indicar un problema de compatibilidad. Las respuestas 401, 429 o 5xx repetidas pueden indicar problemas clave, agotamiento de cuotas o inestabilidad del proveedor.

Flujo de implementación mínimo para un proxy compatible con OpenAI

Para un proxy /chat/completions, el flujo puede ser simple:

1. Reciba la solicitud y asigne request_id y el contexto de seguimiento.
2. Autenticar la clave de puerta de enlace y resolver el alcance del inquilino, el equipo, la aplicación y la política.
3. Cree el tramo de puerta de enlace principal.
4. Cree una fila del libro mayor con el estado aceptado.
5. Resolver el alias del modelo en el modelo del proveedor y la versión de la política de enrutamiento.
6. Registrar metadatos: operación, ID de plantilla de solicitud, nombre de esquema, hash de solicitud y política de captura de contenido.
7. Inicie el intervalo de llamadas del modelo utilizando atributos semánticos de GenAI cuando corresponda.
8. Reenviar la solicitud al proveedor seleccionado.
9. Para streaming, actualice el estado cuando llegue el primer fragmento y cuente el uso con la mayor precisión que permita la respuesta del proveedor.
10. Al finalizar, analice el uso del proveedor, el motivo de finalización, el estado y la clase de error.
11. Actualice el libro mayor con tokens, costo estimado, detalles de reintento/retroceso y estado final de la solicitud.
12. Emitir métricas del libro mayor y abarcar datos.
13. Ejecute la conciliación diaria y almacene los costos confirmados por el proveedor por separado de la estimación original.

Lista de verificación de implementación

• Defina ID de solicitud canónica e ID de seguimiento.
• Adopte los atributos de OpenTelemetry GenAI para la telemetría de modelos comunes.
• Cree un libro de registro de uso de la puerta de enlace con transiciones de estado de solicitud.
• Normalizar las dimensiones de proveedor, modelo, alias de modelo, inquilino, aplicación y flujo de trabajo.
• Mantenga los datos de investigación de alta cardinalidad fuera de las etiquetas de métricas.
• Hacer que el mensaje sin formato y la captura de salida estén deshabilitados de forma predeterminada.
• Agregue políticas explícitas para muestreo, redacción, retención y control de acceso.
• Capture metadatos de recuperación para flujos de trabajo de RAG.
• Cree paneles de control de costos, latencia, confiabilidad, validación y comportamiento de los inquilinos.
• Concilie las estimaciones de la puerta de enlace con el uso del proveedor y las exportaciones de costos.
• Alerta sobre picos de gasto, regresiones de latencia, saltos de respaldo, errores de validación y eventos relevantes para la seguridad.

Conclusión

Una puerta de enlace multimodelo es el lugar adecuado para implementar la observabilidad de LLM porque ve las solicitudes antes de que lleguen a cualquier proveedor y puede adjuntar un contexto empresarial que los proveedores desconocen. El diseño más sólido no es "registrar todo". Es un modelo en capas: seguimientos neutrales del proveedor para la ejecución, un token duradero y un libro de contabilidad de costos para la facturación, análisis de inquilinos para la gobernanza, metadatos RAG para la calidad de la recuperación y registro rápido de privacidad para una depuración segura.

Comience con metadatos, transiciones de estado y conciliación. Agregue captura de contenido solo cuando la política, la retención y los controles de acceso estén listos. Esa secuencia brinda a los desarrolladores la evidencia que necesitan para depurar la latencia, la calidad y el gasto sin convertir la observabilidad en un nuevo riesgo de exposición de datos.

Lectura relacionada

• comportamiento de reintento y respaldo en el enrutamiento API LLM
• patrones de control de costes por lotes y almacenamiento en caché rápido
• administración de claves API de equipo y límites de gasto