Lo que LiteLLM no puede ver: monitoreo del servicio de GPU bajo el gateway

Pasando de una pasarela FastAPI desarrollada manualmente a los registros centralizados de solicitudes de LiteLLM, el control de tokens y claves virtuales, y reduciendo el código personalizado de la pasarela. Una pasarela sigue solo viendo el tráfico que cruza sus límites. El servicio en producción planteó toda una categoría de preguntas que LiteLLM por sí solo no puede responder: cuestiones sobre colas, el uso de datos prellenados frente a su decodificación, los reinicios de contenedores y la saturación del servidor, que determinan si una llamada de once segundos fue exitosa o se quedó atascada.

Antecedentes

LiteLLM se encuentra en el punto de entrada de las solicitudes. Registra que llegó una llamada, qué modelo la atendió, el conteo de tokens, qué clave virtual fue utilizada, y si hubo éxito o fracaso. Para el seguimiento diario de costos, eso es prácticamente todo lo que necesitan los departamentos financiero y de producto.

Más allá de ese límite, la situación varía. Una solicitud de once segundos puede significar espera en cola en una GPU saturada o la generación normal de una respuesta larga. Desde el gateway, ambas situaciones parecen idénticas; sin embargo, las soluciones no lo son. Tratarlas como una sola métrica dirige a los técnicos de soporte en la dirección incorrecta.

Tres capas por debajo del gateway requieren cada una su propia métrica precisa:

• El tiempo de ejecución del modelo, donde se determina la latencia. El tiempo hasta el primer token incluye tanto la espera en cola como el prellenado previo, más que la fase de decodificación. El rendimiento del prellenado previo y de la decodificación se ve afectado por cuellos de botella diferentes. Estas señales provienen del propio /metrics del motor de servicio (por ejemplo, vLLM), no del gateway.
• Los contenedores, a través de cAdvisor: qué proceso está consumiendo memoria y qué contenedor se reinició durante la noche.
• Los hosts, a través de node-exporter: consumo total de CPU, memoria y disco en la máquina que alberga las GPUs.

Cuatro fuentes son importantes porque ningún coleccionista ve todas las capas. Los registros de Gateway sin métricas en tiempo real ofrecen solo una visión parcial; las métricas en tiempo real sin contexto del host y el contenedor pasan por alto al “vecino ruidoso” que se reinició a las tres de la mañana.

La pila completa

En un servidor GPU local, dos proyectos Docker Compose separan deliberadamente las distintas funciones.

Composición de Gateway: LiteLLM, PostgreSQL para las claves y gastos virtuales, Redis para el caché de límites de velocidad.

Composición de monitoreo: Prometheus, Grafana, node-exporter, cAdvisor. Los procesos de vLLM suelen ejecutarse en el host, fuera de ambas pilas, con un proceso por modelo servido. Prometheus recopila los cuatro objetivos que abarcan las métricas relacionadas con Gateway y las locales del modelo. Esta separación no es estética: es la forma en que la infraestructura opcional permanece tal.

Decisiones clave

1. Dos archivos de compose, no uno solo. LiteLLM ya estaba sirviendo a otros equipos cuando se añadió la funcionalidad de monitoreo. Integrar Prometheus en el mismo archivo de compose vincularía cada cambio en la configuración de extracción con el archivo del gateway de producción. La separación permite el aislamiento de fallos: se puede reconstruir el monitoreo libremente sin que LiteLLM lo note. La dependencia fluye en una sola dirección. La interconexión entre las capas implica un costo único frente al riesgo continuo de afectación generalizada. Si el monitoreo falla, los modelos siguen respondiendo; si el gateway falla, el monitoreo sigue registrando el estado del host para el análisis posterior.

2. No hay postgres-exporter ni redis-exporter por defecto. El host podría ejecutarlos sin problemas. Sin embargo, se dejaron para más adelante:

• Mientras LiteLLM funcione correctamente, rara vez se necesita un panel de control para los componentes internos de la base de datos y la caché; los fallos se manifiestan primero en el gateway.

node-exporter, cAdvisor y los puntos de extremo del modelo /metrics ya cubren las capas críticas.

Los exportadores adicionales representan versiones extra y consumo adicional de memoria operativa.

Los paneles de control no utilizados generan costos de mantenimiento sin beneficio alguno. Revíselos cuando los errores de conexión a PostgreSQL se vuelvan frecuentes, la autenticación con claves virtuales se ralenticue debido a la competencia por consultas, o la presión de memoria en Redis sea una posibilidad real; entonces agregue los exportadores esa misma semana. Anote los criterios para decidir cuándo no usarlos, de modo que esa decisión sea intencionada y no fruto del olvido.

3. Mantener Langfuse. LiteLLM consolida la observabilidad de las solicitudes, pero una acción del producto suele implicar múltiples llamadas al modelo: recuperación, resumen y seguimiento. Los IDs de sesión compartidos pueden agrupar las llamadas en LiteLLM, pero el seguimiento de la experiencia de usuario y la retención difieren. Los registros del gateway no están diseñados como archivos indefinidos. Las trazas antiguas se utilizan en conjuntos de evaluación para el cambio de modelos y ayudan a depurar informes de semanas anteriores. Las métricas se agregan; las trazas, en cambio, permiten reconstruir la información. Ninguna cantidad de métricas cubre por completo las trazas, y por eso ambas se mantienen.

Uso práctico

1. Declarar los modelos únicamente en config.yaml era problemático. Los modelos asociados a un archivo muestran una insignia de configuración en la interfaz y no se pueden editar o eliminar sin modificar el montaje e iniciar nuevamente un proxy ocupado. Los modelos registrados a través de la API de administración se almacenan en PostgreSQL y sobreviven a los reinicios:

curl -X POST <http://localhost:4000/model/new> \
  -H "Authorization: Bearer$LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "CHAT_MODEL",
    "litellm_params": {
      "model": "openai/CHAT_MODEL",
      "api_base": "<http://host.docker.internal:8001/v1>",
      "api_key": "dummy"
    }
  }'

Se recomienda utilizar una configuración separada para los ajustes y otra base de datos para el catálogo de modelos. Esa separación permite a los operadores agregar un modelo experimental sin afectar el proceso de gateway que utilizan otros equipos.

2. El panel del Node-Exporter tuvo poco uso. Una vez que las cargas de trabajo se estabilizaron y las implementaciones disminuyeron, los totales de hosts dejaron de responder a preguntas relevantes. Mantenga la extracción de datos; no invierta en exceso en paneles que no se utilizan. Los paneles de cAdvisor y vLLM recibieron más atención diaria porque reflejan la latencia visible para los usuarios.

3. Plantillas útiles de Grafana

• Panels comunitarios de vLLM (por ejemplo, el panel público en grafana.com con número 23991)
• cAdvisor (14282)
• Node Exporter Full (1860)

Importe ellos como puntos de referencia y luego elimine los paneles que nunca se abren.

Resumen

La alerta representa la deficiencia evidente: existen métricas, pero no se activa ninguna página cuando se superan los umbrales. Conectar las API de correo de la aplicación a los hosts GPU mezcla problemas diferentes; elige un método de notificación más seguro en adelante. Conceptualmente, Prometheus y Grafana responden a preguntas que ya se sabía que se harían; Langfuse reconstruye qué efecto tuvo una acción del usuario a través de las llamadas distribuidas. La agregación y la reconstrucción son complementarias. Una migración a un gateway sin un plan de monitoreo solo desplaza el punto ciego un nivel más abajo.