Métricas de latência de AI API: TTFT, primeira resposta e velocidade

A latência de uma AI API não é um único número. Em streaming, registre a chegada dos Headers upstream, o primeiro SSE Event não vazio, o primeiro conteúdo ou Action efetiva, o primeiro texto visível e a conclusão. Esses marcos respondem a perguntas diferentes e não devem ser chamados todos de “TTFT”.

Em chat de texto, Time to First Visible Text costuma representar a experiência do usuário. Em workflow de reasoning ou Tools, Function Arguments podem ser o primeiro resultado efetivo. Generation Speed é uma medida separada após a saída começar.

Construa uma timeline antes de nomear métricas

Use Clock monotônico e uma única origem:

t0  gateway recebe request
t1  inicia request upstream
t2  chegam Headers upstream
t3  primeiro SSE Event não vazio
t4  primeiro conteúdo ou Action efetiva
t5  primeiro Text Delta visível
t6  upstream Body termina ou fecha
t7  handler do gateway termina

Nem todo request possui todos os marcos. Valor ausente deve permanecer ausente, não virar zero.

Campo	Medição	Limite importante
auth_ms	Autenticação	Fase local
distribution_ms	Seleção de canal e routing	Fase local
body_read_ms	Leitura do request body	Detecta upload lento
upstream_headers_ms	Upstream Start até Headers	Origem diferente do gateway receipt
first_sse_event_ms	Receipt até primeiro Event	Pode conter só metadata
first_response_ms	Receipt até conteúdo ou Action	Texto, reasoning, Function Arguments
first_text_delta_ms	Receipt até texto visível	Pode não existir
upstream_done_ms	Receipt até fechamento upstream	Fechamento não é sempre sucesso
total_handler_ms	Receipt até fim do relay	E2E do gateway
visible_output_tps	Tokens / janela visível	Diagnóstico por usuário, não TPS global

Não subtraia durações com origens diferentes.

TTFT tem mais de um significado

O guia de benchmark NVIDIA NIM inclui geralmente rede, queue e prompt prefill no TTFT e exclui respostas iniciais vazias. Streams modernos podem emitir antes do texto: metadata, reasoning, Function Arguments, Tool Input ou heartbeat.

Nome	Definição recomendada	Uso
Time to Headers	Início até Headers upstream	Rede e admission
Time to First Event	Início até SSE não vazio	Liveness do transporte
Time to First Effective Response	Início até conteúdo ou Action útil	Agents e reasoning
Time to First Visible Text	Início até texto renderizável	Experiência de chat

Um dashboard com “TTFT” deve dizer qual definição usa.

Separe responsividade e velocidade de geração

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 exclui TTFT e normalmente divide o restante por output_tokens - 1. Não conte SSE Events como Tokens; um Event pode conter zero ou vários.

Texto inicial rápido com TPS baixo começa bem e fica lento; texto tardio com TPS alto parece travado e termina rápido. TPS por usuário e Throughput agregado também diferem.

Reasoning e Tools podem vir antes do texto

Em texto puro, first_response_ms e first_text_delta_ms ficam próximos. Function Arguments em 1,8 s e texto em 6,4 s significam que existe uma Action útil antes da prosa visível.

• terminal agent pode medir First Effective Action;
• UI só de texto deve medir First Visible Text;
• Tool API pode não produzir texto;
• SSE Envelope precoce prova conexão, não progresso útil.

O guia AI API Streaming cobre parsing, Cancellation e Idle Timeout. As métricas devem seguir o limite do parser.

Diagnostique fases em ordem fixa

Sintoma	Métrica	Verificar
Lento antes dos Headers	upstream_headers_ms	Rede, admission, queue, rota, região
Headers rápidos, saída tardia	first_response_ms	Model Queue, prefill, reasoning, inflight
Event rápido, saída tardia	Gap SSE→Response	Metadata, heartbeat, início de reasoning
Action rápida, texto tardio	Gap Response→Text	Tool/reasoning, composição
Texto rápido, geração lenta	visible_output_tps	Decode, contenção, contexto longo
Upstream normal	Campos locais	Auth, policy, upload

Uma métrica não prova a causa. Combine rota, região, provedor e carga concorrente.

Leia três traces sintéticos

Trace A: espera por 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

A espera ocorre antes dos Headers. Verifique rota, admission, rede, região e carga antes da interface.

Trace B: Action antes do 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

Action efetiva surge em 2,9 s e o texto 5,8 s depois. Investigue reasoning ou Tools; aumentar Header Timeout não ajuda.

Trace C: início rápido, geração 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

Texto começa rápido, mas a geração leva quase 20 s. Compare comprimento, contexto, channel, inflight e provedor. First-output Timeout não detecta esse padrão.

Compare apenas em condições controladas

Registre model e route, distribuições de Tokens, streaming, reasoning effort, Tools, região, Network Path, concurrency, sampling, Max Output, warmup, retry policy, amostra e método de percentil.

Compare p50, p95 e p99, não uma média isolada. Mantenha timeouts e erros. Prompts, comprimentos ou concurrency diferentes não formam ranking de velocidade de modelos.

Retenha metadata, não conteúdo

Request ID, timestamp, model, group, channel reference, status, Token Counts, timing fields, event counts, inflight, região aproximada e classificadores como upstream_headers_slow costumam bastar.

Não é necessário guardar prompts, respostas, API Keys ou identidades em texto. Aplique retention e Access Control à metadata.

Comece pela timeline, use Reliable AI API Routing para comparar Attempts e AI API Error Troubleshooting para ligar timing ao status final. Assim é possível separar admission, model startup, reasoning/Tools, geração visível e overhead local.