Una API de LLM es fácil de medir mal. El conteo de solicitudes aumenta, el uso de tokens aumenta, los paneles se vuelven más coloridos y, aun así, el equipo sigue sin poder responder las preguntas que importan: ¿los usuarios obtuvieron respuestas utilizables?, ¿la latencia se mantuvo dentro de la promesa del producto?, ¿los reintentos ocultaron un problema del proveedor?, ¿y el resultado aceptado costó lo que esperábamos?
Las métricas correctas de la API de LLM conectan las llamadas al modelo con los resultados del producto. Ayudan a que ingeniería, producto y finanzas estén de acuerdo en si una función de IA es lo bastante fiable para escalar, lo bastante barata para mantener y lo bastante observable para depurar.
Esta guía te ofrece una tarjeta de puntuación práctica para el trabajo en producción con API de LLM. Úsala después de entender qué es una API de LLM, mientras comparas el acceso directo al proveedor con una pasarela, o cuando tu equipo pasa de llamadas de prototipo a tráfico real.
La respuesta rápida: mide resultados aceptados, no solo la actividad de la API
El error común es medir el envoltorio en lugar del flujo de trabajo. Una respuesta 200, el recuento de tokens, el nombre del modelo y el gasto total son útiles, pero no demuestran que el producto haya obtenido valor de la llamada a la API de LLM.
Las métricas que realmente importan son:
| Grupo de métricas | Qué responde | Por qué importa |
|---|---|---|
| Tasa de respuesta aceptada | ¿La aplicación recibió una respuesta utilizable? | El éxito HTTP en bruto pasa por alto fallos de esquema, malas llamadas a herramientas, rechazos y regeneraciones del usuario. |
| Latencia por recorrido del usuario | ¿La respuesta llegó lo bastante rápido para este flujo de trabajo? | Chat, agentes de programación, trabajos por lotes y flujos con herramientas necesitan objetivos de latencia distintos. |
| Costo por resultado aceptado | ¿Cuánto costó realmente el resultado útil? | El precio por token por sí solo ignora reintentos, alternativas, respuestas rechazadas y desperdicio de contexto largo. |
| Estado de reintentos y límites de tasa | ¿El sistema es estable bajo demanda real? | Los reintentos ocultos pueden aumentar la latencia, el costo y el riesgo de incidentes antes de que cambie la tasa de éxito global. |
| Calidad de los mecanismos de respaldo | ¿Las rutas de respaldo recuperaron el problema sin romper el contrato? | El respaldo solo es útil cuando la respuesta final sigue cumpliendo las necesidades de calidad, esquema y política de la carga de trabajo. |
| Completitud de auditoría | ¿Puede el equipo explicar rápidamente una solicitud problemática? | La depuración requiere contexto de solicitud, clave, carga de trabajo, modelo, ruta, tokens, costo, latencia y error. |
Ese es el marco operativo. El objetivo no es demostrar que la API de LLM recibió tráfico. El objetivo es demostrar que la capa de la API ayudó a que un flujo del producto fuera más fiable, más rápido, más barato o más fácil de operar.
Métrica 1: tasa de respuesta aceptada
Empieza con la tasa de respuesta aceptada porque es la más cercana al valor para el usuario.
accepted_response_rate =
accepted_outputs / user_or_job_requests
Defina accepted_output a nivel de aplicación. Para un resumidor de soporte, puede significar que el resumen pasó las comprobaciones de longitud, tono y citas. Para un agente de codificación, puede significar que el parche se aplicó y las pruebas pasaron. Para un flujo de trabajo de extracción, puede significar que el JSON coincidió con el esquema y las reglas de confianza. Para una función de chat, puede significar que el usuario no reintentó, escaló o abandonó de inmediato.
Haga seguimiento de al menos estos campos por solicitud de LLM API:
| Campo | Por qué importa |
|---|---|
request_id |
Permite que soporte, ingeniería y finanzas hablen del mismo evento. |
workload |
Separa las rutas de chat, agente, extracción, enriquecimiento y lote. |
requested_model |
Registra lo que la aplicación solicitó. |
final_model |
Registra lo que realmente generó la respuesta. |
status |
Separa éxito, timeout, límite de velocidad, error del proveedor, fallo de validación y bloqueo de política. |
accepted_output |
Indica si el resultado produjo valor útil para el producto. |
retry_count |
Muestra el trabajo oculto detrás de una solicitud visible. |
fallback_count |
Muestra si la recuperación cambió el modelo o la ruta del proveedor. |
No trate HTTP 200 / total requests como la métrica principal de confiabilidad. Es una señal de infraestructura. La LLM API puede devolver una respuesta técnicamente exitosa que falla para el producto: JSON mal formado, llamada de función incorrecta, cita faltante, rechazo inseguro, campo alucinado, respuesta incompleta o una respuesta que llegó demasiado tarde.
Métrica 2: latencia por ruta, no latencia promedio
La latencia promedio suele ser el número incorrecto. Oculta la latencia de cola que sienten los usuarios y los problemas de enrutamiento que los operadores necesitan diagnosticar.
Para rutas interactivas de LLM API, haga seguimiento de:
| Métrica | Mejor uso |
|---|---|
| Tiempo hasta el primer token o primer fragmento | Chat en streaming, copilotos, agentes de codificación y cualquier interfaz donde el progreso importa. |
| Duración de extremo a extremo | Respuestas sin streaming, salidas estructuradas, cadenas de llamadas a herramientas y trabajos por lotes. |
| Latencia p90 | Revisión de la experiencia del producto para la mayoría de los usuarios. |
| Latencia p99 | Revisión de incidentes, inestabilidad del proveedor y detección de regresiones de cola larga. |
Para cargas de trabajo en segundo plano, haga seguimiento también del rendimiento:
| Métrica | Mejor uso |
|---|---|
| Tokens por segundo | Generación larga, resumido y cargas de trabajo de codificación. |
| Trabajos completados por minuto | Dimensionamiento de la cola y salud de los workers. |
| Rendimiento ajustado por reintentos | Capacidad real después de contar fallos y reintentos. |
Las convenciones semánticas de GenAI de OpenTelemetry nombran primitivas útiles como uso de tokens, duración de la operación, tiempo hasta el primer fragmento, tiempo por fragmento de salida, duración de la solicitud al servidor, tiempo hasta el primer token, duración del flujo de trabajo, duración del agente, llamadas de inferencia, llamadas a herramientas y duración de herramientas. No necesitas implementar todas las métricas de una vez, pero usa nombres estables desde el principio para que la telemetría de tu API de LLM no termine convirtiéndose más tarde en una hoja de cálculo improvisada.
Segmenta la latencia por:
- carga de trabajo;
- streaming frente a no streaming;
- modelo solicitado;
- modelo final;
- proveedor o ruta;
- conteo de reintentos;
- conteo de fallback;
- tamaño del prompt o bucket de ventana de contexto.
Esa segmentación te dice si la latencia cambió porque el modelo se volvió más lento, el prompt se hizo más grande, la ruta cambió, un proveedor alcanzó sus límites o una política de reintentos empezó a hacer demasiado trabajo.
Métrica 3: costo por salida aceptada
El precio por token no es lo mismo que el costo de producción. Un modelo de bajo costo puede volverse caro si requiere reintentos repetidos, produce respuestas rechazadas o obliga a personas a revisar resultados de baja confianza. Un modelo premium puede ser más barato para una carga de trabajo si produce respuestas aceptadas con menos llamadas.
Usa esta métrica de costo de la API de LLM:
cost_per_accepted_output =
total_workload_cost / accepted_outputs
Luego divide el costo:
| Componente de costo | Lo que revela |
|---|---|
| Costo del intento principal | Costo base cuando la primera llamada funciona. |
| Costo de reintento | Costo oculto detrás de una solicitud visible para el usuario. |
| Costo de fallback | Costo de las rutas de recuperación. |
| Costo de salida rechazada | Gasto que no produjo valor útil para el producto. |
| Desperdicio de contexto largo | Costo de enviar contexto repetido o innecesario. |
| Costo de herramientas o medios | Costo de herramientas de pago, llamadas de imágenes, llamadas de video, acciones del navegador o pasos de enriquecimiento conectados al flujo de trabajo. |
Para la revisión financiera, informa el costo por carga de trabajo, clave, entorno, política de ruta y modelo final. Para la revisión de ingeniería, añade la tasa de respuestas aceptadas junto al costo. Un gráfico de costos sin calidad puede empujar al equipo hacia un modelo que parece barato y genera más fallos del producto.
Aquí es donde la superficie de producto de Flatkey es relevante. La documentación pública de Flatkey describe una API REST compatible con OpenAI en https://router.flatkey.ai/v1, y su inicio rápido indica a los usuarios que revisen los Usage Logs para ver el modelo, los recuentos de tokens, la latencia y el costo después de una solicitud. Eso proporciona a los equipos un libro mayor base útil. Un equipo de producción aún debería añadir etiquetas de carga de trabajo, reglas de salida aceptada y notas de política de ruta alrededor de ese libro mayor.
Métrica 4: reintentos, 429 y presión por límites de velocidad
Los límites de velocidad no son solo papeleo del proveedor. Cambian la latencia, el costo y la experiencia del usuario.
La documentación de la API REST de Flatkey indica que las solicitudes de API usan autenticación Bearer, que los límites de tasa se aplican por clave de API y que, al superar el límite, se devuelve 429 Too Many Requests. Eso significa que un panel de control real de API de LLM debería distinguir entre fallos del proveedor, presión del lado del cliente y problemas de capacidad a nivel de clave.
Haz seguimiento de:
| Métrica | Fórmula o definición | Qué vigilar |
|---|---|---|
| Tasa de 429 | 429 responses / total requests |
Un pico significa que conviene revisar la capacidad a nivel de clave, el patrón de ráfagas o el diseño de la cola. |
| Tasa de reintentos | requests with retry_count > 0 / total requests |
Una tasa alta de reintentos puede ocultar inestabilidad detrás del éxito eventual. |
| Tasa de éxito de reintentos | accepted outputs after retry / retried requests |
Muestra si los reintentos recuperan valor o solo añaden costo. |
| Penalización de latencia por reintento | latency after retry - primary-success latency |
Muestra el costo de la experiencia de usuario de la recuperación. |
| Penalización de costo por reintento | cost after retry - primary-success cost |
Muestra el costo de facturación de la recuperación. |
Los reintentos deben tener presupuestos. Si una solicitud puede reintentarse silenciosamente tres veces, el producto puede parecer fiable mientras la latencia p99 y el costo se descontrolan. Para rutas interactivas, los presupuestos de reintento deberían ser más estrictos que para trabajos en segundo plano. Para rutas por lotes, la cola puede ser mejor que el reintento inmediato.
Métrica 5: recuperación por fallback y desajuste de fallback
El fallback es útil cuando salva una solicitud que de otro modo fallaría. Es peligroso cuando oculta un problema del proveedor al devolver una respuesta que rompe el contrato de la aplicación.
La documentación de fallback de OpenRouter describe probar otros modelos cuando los proveedores de un modelo principal están caídos, limitados por tasa o se niegan a responder por moderación; también señala que el precio sigue al modelo finalmente utilizado. La documentación de enrutamiento de proveedores de OpenRouter muestra controles de enrutamiento como el orden de proveedores, la अनुमति de fallback, la ordenación por precio, rendimiento o latencia, y los umbrales de rendimiento preferidos. La implementación exacta difiere según la plataforma, pero las preguntas operativas son ampliamente útiles para cualquier API de LLM con múltiples rutas posibles.
Haz seguimiento de:
| Métrica | Fórmula o definición | Qué responde |
|---|---|---|
| Tasa de activación de fallback | requests with fallback_count > 0 / total requests |
Con qué frecuencia falla el enrutamiento primario o elige una alternativa. |
| Tasa de recuperación de fallback | accepted outputs after fallback / fallback-triggered requests |
Si el fallback realmente recupera una salida útil. |
| Tasa de desajuste del fallback | fallback outputs rejected for schema, tool, context, modality, or policy mismatch / fallback-triggered requests |
Si la ruta de respaldo es compatible. |
| Penalización de costo del fallback | fallback-success cost - primary-success cost |
Si la recuperación es financieramente aceptable. |
| Penalización de latencia del fallback | fallback-success latency - primary-success latency |
Si la recuperación es aceptable para el recorrido del usuario. |
| Visibilidad de la ruta final | requests with logged final model and provider / total requests |
Si el equipo puede depurar y auditar la ruta. |
Para una API de LLM, el fallback debe probarse por contrato, no solo por disponibilidad. Si la ruta primaria requiere llamadas a herramientas, esquema JSON, una ventana de contexto larga o una política de datos específica, la ruta de respaldo debe cumplir el mismo requisito o quedar excluida de esa carga de trabajo.
Métrica 6: eficiencia del contexto
El costo de la API de LLM a menudo crece porque crece el contexto. Los equipos publican prompts del sistema más largos, adjuntan instrucciones repetidas, agregan resultados de recuperación, incluyen el historial de conversación y aumentan el número máximo de tokens de salida sin vincular esos cambios a una salida aceptada.
Seguimiento de:
| Métrica | Por qué importa |
|---|---|
| Tokens de entrada por salida aceptada | Muestra la inflación del prompt y de la recuperación. |
| Tokens de salida por salida aceptada | Muestra si las respuestas son más largas de lo que el producto necesita. |
| Utilización del contexto | Muestra si la carga de trabajo está cerca del límite práctico de contexto del modelo. |
| Proporción de tokens almacenables en caché | Muestra si las secciones repetidas del prompt pueden reutilizarse cuando el proveedor o la pasarela admite caché. |
| Tasa de truncamiento o error de contexto | Muestra si el tamaño de entrada está causando fallos antes de evaluar la calidad de la generación. |
La pregunta útil de revisión no es "¿qué modelo tiene la ventana de contexto más grande?" Es "¿cuánto contexto necesita esta carga de trabajo para producir una respuesta aceptada?" Eso mantiene la elección del modelo vinculada a los resultados en lugar de a las especificaciones máximas.
Métrica 7: completitud de la auditoría
Un incidente de producción en una API de LLM suele comenzar con una queja específica: un usuario obtuvo una mala respuesta, un trabajo se volvió caro, un proveedor se ralentizó, una clave alcanzó un límite o un modelo devolvió una salida mal formada. La completitud de la auditoría mide si el equipo puede reconstruir ese evento rápidamente.
Como mínimo, cada solicitud de producción debería conectar:
| Campo de auditoría | Respuesta requerida |
|---|---|
request_id |
¿De qué solicitud exacta estamos hablando? |
timestamp |
¿Cuándo ocurrió? |
api_key_id or environment |
¿Qué aplicación, equipo o entorno lo envió? |
workload |
¿Qué ruta de producto o trabajo lo envió? |
route_policy |
¿Qué regla se suponía que debía aplicarse? |
requested_model |
¿Qué pidió la aplicación? |
final_model |
¿Qué respondió? |
final_provider_or_route |
¿A dónde fue realmente la solicitud? |
status and error_type |
¿Qué pasó? |
input_tokens and output_tokens |
¿Cuánto trabajo se realizó? |
latency_ms and time_to_first_chunk_ms |
¿Qué tan lento fue? |
cost |
¿Cuánto costó? |
retry_count and fallback_count |
¿Cuánta recuperación hubo? |
accepted_output |
¿La aplicación aceptó el resultado? |
Si estos campos viven en herramientas separadas, la API de LLM aún puede funcionar, pero las operaciones serán más lentas. Los equipos deberían poder responder "¿qué cambió?" sin tener que unir facturas del proveedor, registros de la aplicación, registros de cola y capturas de pantalla de cinco paneles.
La tarjeta de evaluación de la API de LLM
Use esta tarjeta de evaluación durante la selección de proveedores, la migración de gateways y las revisiones operativas mensuales.
| Pregunta | Métrica | Condición de aprobación |
|---|---|---|
| ¿Los usuarios obtienen respuestas útiles? | Tasa de respuestas aceptadas | Estable o superior por carga de trabajo después de cambios de modelo o ruta. |
| ¿La API es lo suficientemente rápida? | Latencia p90/p99 y tiempo hasta el primer fragmento | Cumple el objetivo para cada ruta de usuario. |
| ¿El sistema es más barato en la práctica? | Costo por salida aceptada | Es menor después de incluir reintentos, fallbacks, salida rechazada y costo de herramientas. |
| ¿Los límites están bajo control? | Tasa de 429, tasa de reintento, tasa de éxito de reintento | La presión de límites es visible y no infla silenciosamente el costo o la latencia. |
| ¿Funcionan las rutas de respaldo? | Recuperación de fallback y tasas de desajuste | Los fallbacks recuperan fallos sin romper el esquema, las herramientas, la política o la calidad. |
| ¿El contexto está bajo control? | Tokens de entrada por salida aceptada y tasa de error de contexto | El crecimiento del prompt y de la recuperación produce valor medible. |
| ¿Pueden los ingenieros depurar incidentes? | Completitud de la auditoría | La solicitud, la carga de trabajo, la ruta, el modelo final, el estado, la latencia, los tokens, el costo y el tipo de error son visibles. |
| ¿Puede finanzas atribuir el gasto? | Costo por clave, carga de trabajo, entorno, ruta y modelo | El gasto se asigna a responsables y rutas de producto. |
Si una herramienta no puede exponer los campos necesarios para esta tarjeta de puntuación, úsela con cuidado. Aun así, puede elegirla para experimentar, pero no debería convertirse en el plano de control operativo para el tráfico de API de LLM en producción sin instrumentación compensatoria.
Un plan simple de medición de 30 días
No necesita una pila de observabilidad perfecta desde el primer día. Empiece con suficiente estructura para que la siguiente decisión de enrutamiento o de modelo sea medible.
Semana 1: defina cargas de trabajo y request IDs
Elija tres a cinco cargas de trabajo representativas:
- una vía interactiva de asistente o chat;
- una vía de agente de código o de llamada a herramientas;
- una vía por lotes de extracción o enriquecimiento;
- una vía de modelo de alto coste;
- una vía sensible a fallos de reserva.
Añada request_id, workload, environment, requested_model y status. Sin estos campos, el análisis posterior se convierte en conjeturas.
Semana 2: añada resultados y errores
Defina accepted_output para cada carga de trabajo. Después clasifique los errores con una lista breve: tiempo de espera agotado, límite de tasa, error del proveedor, fallo de validación, bloqueo por política, error de contexto y desconocido. Evite etiquetas de error demasiado detalladas que hagan imposible leer los gráficos.
Semana 3: añada latencia, tokens y coste
Capture la duración de la operación, el tiempo hasta el primer fragmento para llamadas en streaming, tokens de entrada, tokens de salida y coste. Construya una vista por carga de trabajo y otra por modelo final. Esto suele ser suficiente para encontrar la primera optimización significativa.
Semana 4: compare rutas y políticas
Compare:
- ruta directa del proveedor frente a ruta de gateway;
- modelo antiguo frente a modelo nuevo;
- éxito solo con primario frente a éxito con reserva;
- coste por solicitud frente a coste por salida aceptada;
- latencia media frente a latencia p90 y p99;
- ruta con reintentos deshabilitados frente a ruta con reintentos habilitados para la misma carga de trabajo.
La revisión debería producir una decisión de ruta o de modelo, no solo un panel más bonito.
Dónde encaja Flatkey
Flatkey es relevante cuando la API de LLM tiene que convertirse en una capa operativa compartida en lugar de una sola llamada a un proveedor. Las fuentes actuales de Flatkey respaldan estos datos del producto:
- Flatkey expone una API REST compatible con OpenAI en
https://router.flatkey.ai/v1. - Las solicitudes de API usan autenticación Bearer.
- La misma URL base funciona en todos los endpoints, proveedores y modelos.
- La documentación de API de Flatkey enumera endpoints para completions de chat, responses, embeddings, generación de imágenes, generación de video y listado de modelos.
- La guía de inicio rápido de Flatkey dice que la API REST, el SDK de OpenAI, la CLI de Flatkey y las rutas de agente de código comparten una sola clave, un solo saldo de cuenta y un solo catálogo de modelos.
- La guía de inicio rápido dice que los Usage Logs muestran modelo, conteos de tokens, latencia y coste después de una solicitud.
- El sitio público de Flatkey posiciona el producto en torno a una clave, un saldo, modelos oficiales, herramientas de pago por llamada y una sola factura.
Esos son primitivas útiles para medir las operaciones de API de LLM. No sustituyen las métricas específicas de la carga de trabajo. El equipo aún necesita definir la salida aceptada, los objetivos de latencia, los presupuestos de reintentos, la política de fallback y los requisitos de auditoría.
Si ya está comparando capas de API, combine este artículo con la tabla de puntuación de métricas de API de routing de IA. Si está al principio del proceso, empiece con cómo usar una API de IA unificada y luego vuelva a esta tabla de puntuación antes de mover tráfico de producción.
Errores comunes
Error 1: detenerse en los totales de tokens.
Los totales de tokens te indican consumo. No te dicen si la salida fue aceptada, si los reintentos inflaron la factura o si los usuarios obtuvieron una mejor experiencia.
Error 2: mezclar todas las cargas de trabajo.
Un agente de codificación, un asistente de soporte al cliente, un trabajo nocturno de enriquecimiento y un flujo de trabajo de imágenes no deberían compartir un único objetivo de éxito.
Error 3: tratar el fallback como fiabilidad automática.
El fallback solo mejora la fiabilidad cuando la ruta de respaldo cumple el mismo contrato de salida y produce un resultado aceptado.
Error 4: comparar precios de lista sin salida rechazada.
Un modelo más barato no es más barato si crea más respuestas descartadas, prompts más largos o más revisión humana.
Error 5: hacer que los registros sean útiles solo para ingenieros.
Finanzas necesita gasto por propietario y carga de trabajo. Producto necesita resultados aceptados. Soporte necesita búsqueda a nivel de solicitud. El libro mayor de LLM API debería dar soporte a los tres.
Preguntas frecuentes
¿Cuál es la métrica más importante de una API de LLM?
La métrica más importante de LLM API es la tasa de respuestas aceptadas por carga de trabajo. Conecta la llamada a la API con si el producto realmente recibió una respuesta útil.
¿El uso de tokens es una métrica de calidad de una API de LLM?
No. El uso de tokens es una señal de coste y capacidad. Se vuelve útil cuando se combina con la salida aceptada, la latencia y el contexto de la carga de trabajo.
¿Debería un panel de una API de LLM centrarse en la latencia promedio?
No. La latencia promedio no es suficiente para revisar producción. Haz seguimiento de la latencia p90 y p99, además del tiempo hasta el primer token o el primer fragmento en rutas de streaming.
¿Cómo deberían comparar los equipos el coste de una API de LLM entre proveedores?
Compara el coste por salida aceptada, no solo el precio por token. Incluye reintentos, fallbacks, respuestas rechazadas, desperdicio de contexto largo y cualquier llamada a herramientas o medios adjunta al flujo de trabajo.
¿Cuándo ayuda un gateway de API de LLM con las métricas?
Un gateway puede ayudar cuando los equipos necesitan una URL base, acceso compartido al modelo, registros de uso, visibilidad de facturación, política de enrutamiento, comportamiento de fallback y contexto de auditoría en múltiples proveedores. Aun así, necesita etiquetas de carga de trabajo y reglas de salida aceptada desde la aplicación.
Conclusión final
Una LLM API debería medirse como infraestructura de producción, no como un endpoint de demostración. El conteo de solicitudes, el nombre del modelo, los totales de tokens y el éxito HTTP son solo la capa inicial.
Las métricas que realmente importan son la tasa de respuestas aceptadas, la latencia por ruta, el coste por salida aceptada, la salud de reintentos y límites de tasa, la recuperación por fallback, la eficiencia del contexto y la integridad de la auditoría. Haz seguimiento de todo eso por carga de trabajo y política de enrutamiento, y la LLM API será más fácil de ajustar, más fácil de confiar y más fácil de defender cuando ingeniería, producto, finanzas y soporte pregunten qué cambió.
Empieza con una prueba práctica: elige una carga de trabajo real, envíala a través de la ruta de tu proveedor actual y a través de la URL base compatible con OpenAI de Flatkey, y luego compara la salida aceptada, el modelo final, la latencia, el uso de tokens, el costo, los reintentos y el comportamiento de fallback con la misma tarjeta de puntuación.
