Métricas de latencia de AI API: TTFT, primera respuesta y velocidad
Guía basada en la timeline para separar headers upstream, primer evento SSE, primera respuesta efectiva, texto visible, latencia total y velocidad.
La latencia de una AI API no es una sola cifra. En streaming hay que registrar headers upstream, primer evento SSE no vacío, primer contenido o acción efectiva, primer texto visible y finalización. Cada hito responde a una pregunta distinta y no debería llamarse simplemente «TTFT».
En un chat de texto, el primer texto visible suele representar la experiencia del usuario. En un workflow con razonamiento o Tools puede aparecer antes un resultado efectivo, como argumentos de función. La velocidad de generación se mide después de comenzar la salida.
Construir una timeline antes de nombrar métricas
Usa un reloj monotónico y un único origen:
t0 gateway recibe la solicitud
t1 inicia la solicitud upstream
t2 llegan los headers upstream
t3 llega el primer SSE event no vacío
t4 llega el primer contenido o acción efectiva
t5 llega el primer text delta visible
t6 termina o se cierra el body upstream
t7 termina el handler del gateway
No todas las solicitudes tienen todos los hitos. Guarda la ausencia como ausencia, no como cero.
| Campo | Medición | Límite importante |
|---|---|---|
auth_ms |
Autenticación | Fase local |
distribution_ms |
Selección de canal y política | Fase local |
body_read_ms |
Lectura del request body | Puede detectar uploads lentos |
upstream_headers_ms |
Inicio upstream a headers | Origen distinto del receipt del gateway |
first_sse_event_ms |
Receipt a primer evento | Puede ser solo metadata |
first_response_ms |
Receipt a contenido o acción efectiva | Texto, reasoning o function arguments |
first_text_delta_ms |
Receipt a texto visible | No existe si no hay texto |
upstream_done_ms |
Receipt a cierre upstream | Cierre no implica éxito |
total_handler_ms |
Receipt al final del relay | Medida E2E del gateway |
visible_output_tps |
Tokens / ventana visible | Diagnóstico por usuario, no TPS global |
No restes duraciones con orígenes diferentes.
TTFT tiene más de un significado práctico
La guía de benchmarking NVIDIA NIM define TTFT hasta el primer token efectivo e incluye normalmente red, queue y prompt prefill. Un stream moderno puede emitir antes metadata, reasoning, argumentos, Tool Input o heartbeat.
| Nombre | Definición recomendada | Uso |
|---|---|---|
| Time to headers | Inicio a headers upstream | Red y admission |
| Time to first event | Inicio a primer SSE no vacío | Liveness de transporte |
| Time to first effective response | Inicio a contenido o acción útil | Agents y reasoning |
| Time to first visible text | Inicio a texto renderizable | Experiencia de chat |
Si una gráfica dice TTFT, documenta cuál de estas definiciones usa.
Separar capacidad de respuesta y velocidad
end_to_end_latency = final_response_time - request_start_time
visible_generation_window = final_response_time - first_visible_text_time
visible_output_tps = output_tokens / visible_generation_window_seconds
Inter-token latency excluye TTFT y suele dividir el tiempo restante por output_tokens - 1. No cuentes SSE events como tokens: un evento puede contener cero o varios y los límites dependen del tokenizer.
Un primer texto rápido con TPS bajo comienza bien y luego se arrastra; un primer texto lento con TPS alto parece bloqueado y después termina rápido. TPS por usuario y throughput agregado tampoco son equivalentes.
Reasoning y Tools pueden preceder al texto
En texto puro, first_response_ms y first_text_delta_ms pueden coincidir. Con Function Calling puede haber argumentos a 1,8 s y texto a 6,4 s. El sistema ya tenía una acción útil, pero el usuario aún no veía prosa.
- un terminal agent puede usar First Effective Action;
- una UI que solo muestra texto debe usar First Visible Text;
- una API de Tool Call puede no producir texto;
- un SSE envelope temprano solo prueba progreso de conexión.
La guía de streaming de AI API cubre parsing, cancelación e idle timeout. La métrica depende de distinguir envelopes y output efectivo.
Diagnosticar fases en un orden fijo
| Síntoma | Métrica | Revisar |
|---|---|---|
| Lento antes de headers | upstream_headers_ms |
Red, admission, queue, ruta, región |
| Headers rápidos, output útil lento | first_response_ms menos fases iniciales |
Queue de modelo, prefill, reasoning, inflight |
| Primer evento rápido, output lento | Gap SSE a response | Metadata, heartbeat, inicio de reasoning |
| Acción rápida, texto lento | Gap response a text | Tool/reasoning o composición |
| Texto rápido, generación lenta | visible_output_tps |
Decode, contención, contexto, red |
| Upstream normal | Campos locales | Auth, política o upload |
Una métrica no prueba la causa; combina route, region, provider y carga concurrente.
Leer tres traces sintéticas
Trace A: espera de headers
| Métrica | Valor |
|---|---|
upstream_headers_ms |
6.100 ms |
first_response_ms |
6.350 ms |
first_text_delta_ms |
6.400 ms |
total_handler_ms |
9.200 ms |
visible_output_tps |
42 |
La mayor espera ocurre antes de headers. Revisa ruta, admission, red, región y carga antes de optimizar la UI.
Trace B: acción antes del texto
| Métrica | Valor |
|---|---|
upstream_headers_ms |
240 ms |
first_response_ms |
2.900 ms |
first_text_delta_ms |
8.700 ms |
total_handler_ms |
10.200 ms |
visible_output_tps |
55 |
Hay acción efectiva a 2,9 s y texto 5,8 s después. Investiga reasoning o Tools; aumentar un header timeout no resuelve el patrón.
Trace C: inicio rápido, generación lenta
| Métrica | Valor |
|---|---|
upstream_headers_ms |
260 ms |
first_response_ms |
420 ms |
first_text_delta_ms |
430 ms |
total_handler_ms |
20.430 ms |
visible_output_tps |
9,8 |
Comienza rápido pero genera durante unos 20 s. Compara longitud, contexto, canal, inflight y proveedor. Un timeout de primera salida no lo detectará.
Comparar solo bajo condiciones controladas
Registra modelo y route exactos, distribuciones de tokens, streaming, reasoning effort, Tools, region, network path, concurrency, sampling, max output, warmup, retry policy, tamaño de muestra y cálculo de percentiles.
Compara p50, p95 y p99, no una media aislada. Mantén timeouts y errores visibles. Con prompts, longitudes o concurrencia distintos no presentes el resultado como ranking de velocidad de modelos.
Conservar metadata, no contenido
Para diagnosticar bastan Request ID, timestamp, model, group, channel reference, status, token counts, timings, event counts, inflight, región aproximada y clasificadores como upstream_headers_slow o generation_slow_tps.
No es necesario guardar prompts, respuestas, API Keys ni identidades en claro. También aplica retención y control de acceso a metadata.
Empieza por la timeline completa, usa Reliable AI API Routing para comparar intentos y AI API Error Troubleshooting para vincular tiempos con el estado final. Así se separan admission, model startup, reasoning, Tools, generación visible y overhead local.