Testar carga em um endpoint de inferência significa verificar quantas solicitações ele atende dentro dos limites de latência, erro e custo definidos para a aplicação. Com Locust, você descreve usuários e requisições em Python, executa uma carga controlada e observa o comportamento do serviço. O teste de estresse vai além da faixa esperada para identificar saturação e recuperação.
Em IA, contar requisições não basta: o tamanho da entrada, o comprimento da resposta e a política de cache alteram o trabalho por chamada. Um ensaio útil combina cenários representativos, validação do conteúdo retornado e métricas do servidor. O roteiro abaixo usa uma API HTTP própria e não depende de um fornecedor específico de modelos.
Resumo rápido
- Defina critérios de aprovação antes de gerar tráfego.
- Separe chamadas curtas, longas e respostas em streaming.
- Use dados sintéticos e um ambiente autorizado para o ensaio.
- Valide o corpo da resposta, além do status HTTP.
- Observe também fila, recursos do servidor e saturação do gerador.
Transforme a expectativa do produto em um plano de carga
Comece pelo fluxo do usuário. Um assistente interno que resume documentos tem um perfil diferente de uma API que classifica pequenas mensagens. Registre quais operações existem, os tamanhos típicos das entradas, a distribuição de horários e o limite de espera aceitável. Quando não houver histórico, trate as hipóteses como hipóteses e revise o plano após observar uso real.
Escolha critérios de aprovação por cenário: percentil de latência, proporção de falhas, quantidade de respostas válidas por segundo e limite de gasto. O percentil 95, ou p95, é um valor abaixo do qual ficam aproximadamente 95% das medições. Ele ajuda a enxergar a experiência de chamadas lentas que a média pode esconder. Não escolha um número universal sem relação com o produto.
Documente modelo, configuração do servidor, limite de saída, quantidade de réplicas e localização do gerador. Guarde a versão do código do teste. Alterar várias dessas condições de uma vez dificulta saber por que o resultado mudou. Para relacionar o ensaio à operação contínua, consulte o guia de observabilidade de agentes de IA.
O ambiente de homologação deve reproduzir os componentes relevantes: autenticação, gateway, fila e inferência. Se ele for menor que a produção, descreva essa diferença e evite extrapolações lineares. Uma GPU adicional pode mudar o agendamento e a memória disponível; o ganho não precisa acompanhar exatamente o aumento do hardware.
Separe carga normal, estresse e recuperação
Um teste de carga verifica o comportamento no volume esperado. Um teste de estresse aumenta a pressão até encontrar limites operacionais definidos previamente. Um teste prolongado observa degradação ao longo do tempo. Uma etapa de recuperação verifica se o sistema volta à condição normal depois que a pressão diminui. Cada pergunta merece seu próprio registro.
| Ensaio | Pergunta | Evidência principal |
|---|---|---|
| Carga esperada | O produto atende o uso previsto? | Latência e respostas válidas |
| Estresse gradual | Onde começa a saturação? | Fila, erros e vazão |
| Pico | Como reage a uma subida rápida? | Admissão e expansão de capacidade |
| Duração prolongada | Há degradação acumulada? | Memória e evolução da latência |
| Recuperação | O serviço se estabiliza novamente? | Drenagem de fila e retorno ao padrão |
Defina antes de começar as condições de interrupção: custo acumulado, taxa de erro, fila máxima ou impacto em componentes compartilhados. Teste somente sistemas próprios ou com autorização explícita. Um endpoint de terceiro pode impor limites contratuais e técnicos; descobrir a capacidade dele por tráfego agressivo não é substituto para consultar essas condições.
Em cada patamar, aguarde tempo suficiente para observar o comportamento estável que interessa à operação. Não misture aquecimento com medições do serviço já preparado. Se o produto costuma partir de réplicas desligadas, execute também um cenário separado para esse início, com critérios próprios.
Crie um locustfile com validação de resposta
O arquivo abaixo é um ponto de partida para uma API fictícia em /inferir, que recebe texto e responde com um objeto JSON contendo uma string resultado. Adapte o contrato à sua aplicação antes de usar. O exemplo envia a credencial por variável de ambiente e não registra conteúdo do pedido em mensagens de erro.
import os
from locust import HttpUser, between, task
class UsuarioInferencia(HttpUser):
wait_time = between(1, 3)
def on_start(self) -> None:
self.client.headers.update({
"Authorization": "Bearer " + os.environ["TOKEN_TESTE"]
})
@task
def classificar(self) -> None:
with self.client.post(
"/inferir",
json={"texto": "Pedido fictício de segunda via"},
name="inferir/curta",
timeout=(5, 60),
catch_response=True,
) as resposta:
if resposta.status_code != 200:
resposta.failure("status inesperado")
return
try:
dados = resposta.json()
except ValueError:
resposta.failure("JSON invalido")
return
if not isinstance(dados, dict):
resposta.failure("objeto esperado")
return
resultado = dados.get("resultado")
if not isinstance(resultado, str) or not resultado.strip():
resposta.failure("resultado ausente")Na documentação do Locust, HttpUser fornece o cliente HTTP, task marca uma tarefa e between insere uma espera entre execuções. O parâmetro name agrupa estatísticas; catch_response permite considerar inválida uma resposta que chegou com sucesso HTTP. Esses recursos sustentam a estrutura acima.
A verificação do exemplo detecta problemas de transporte e contrato, mas não comprova qualidade da classificação. Para isso, mantenha um conjunto separado de entradas com respostas esperadas e execute uma avaliação funcional. O guia de testes de agentes de IA complementa essa dimensão.
Execute com limites e preserve os resultados
Instale Locust em um ambiente Python isolado, confira a versão instalada e registre-a junto do ensaio. Configure TOKEN_TESTE no mecanismo de segredos do seu terminal ou pipeline. O comando seguinte pressupõe um endpoint local autorizado na porta 8000. Os valores são ilustrativos e devem ser reduzidos se excederem a capacidade ou o orçamento do seu ambiente.
locust -f locustfile.py --host http://127.0.0.1:8000 \
--headless -u 10 -r 2 -t 2m \
--stop-timeout 65 --csv resultado --html resultado.htmlNa configuração documentada, -u indica usuários simultâneos, -r controla a entrada de usuários por segundo e -t limita a duração. Os arquivos CSV e HTML preservam o resultado. O período adicional de parada permite que tarefas em andamento terminem dentro do limite escolhido. Confirme o tempo total esperado ao planejar a janela do teste.
Execute primeiro com um usuário para validar autenticação, conteúdo e limpeza dos artefatos. Depois aumente a concorrência em ensaios controlados. Compare o histórico por intervalo, não apenas o resumo final: uma média que mistura início ocioso e pico saturado pode esconder exatamente o problema investigado.
Usuários simultâneos não equivalem a requisições por segundo. No fluxo sequencial deste exemplo, cada usuário aguarda a resposta e uma pausa antes de fazer outro pedido. Se o servidor fica mais lento, a taxa de novas chamadas tende a cair. Por isso, registre a taxa efetivamente alcançada e não apresente o número configurado de usuários como vazão do sistema.
Se o requisito for simular chegadas independentes da duração de respostas, este script simples não representa sozinho esse comportamento. Desenhe um cenário próprio e valide a geração efetiva. Caso contrário, o serviço pode parecer estável justamente porque clientes virtuais ficaram presos esperando, deixando de produzir a pressão que existiria no mundo real.
Interprete inferência, streaming e gargalos do gerador
Monte um conjunto de entradas sintéticas que represente tamanhos e tipos de pedido. Separe respostas curtas de gerações longas e mantenha parâmetros constantes entre comparações. Repetir exatamente o mesmo texto pode ativar cache e medir um caminho diferente do tráfego pretendido. Meça cenários com cache aquecido e sem reaproveitamento quando ambos forem relevantes.
Para respostas em streaming, distinga tempo até o primeiro conteúdo útil e duração total. Receber cabeçalhos não significa receber o primeiro token. Um cliente configurado para streaming pode encerrar sua medição padrão antes de consumir o corpo. Instrumente a leitura até o evento final, registre os tempos desejados separadamente e conte desconexões como falhas do fluxo.
O tutorial de latência e TTFT com vLLM aprofunda essas métricas. Neste ensaio, a pergunta central é como elas mudam quando a carga aumenta. Analise também respostas úteis por segundo, tokens gerados quando o servidor os informa e tempo gasto em fila. Um aumento de vazão acompanhado de atrasos inaceitáveis não satisfaz automaticamente o produto.
Observe CPU, memória e rede da máquina que executa Locust. Se ela saturar, o resultado deixa de representar apenas o endpoint. A documentação apresenta FastHttpUser como alternativa de cliente com menor consumo de CPU em determinados cenários, sem prometer que requisições individuais fiquem mais rápidas. Valide compatibilidade e verificação TLS antes de trocar o cliente.
Quando necessário, distribua a geração entre processos e máquinas. O modo distribuído do Locust usa um coordenador e trabalhadores. Mantenha código, variáveis e dados de teste consistentes entre trabalhadores e verifique que todos participaram. Preserve também métricas do próprio gerador para distinguir falta de capacidade de teste de saturação real da inferência.
Exemplo: software de atendimento em Belo Horizonte
Imagine uma empresa fictícia de software em Belo Horizonte que classifica mensagens antes de encaminhá-las ao suporte. Este é um exemplo ilustrativo, sem benchmark ou resultado obtido. A equipe quer verificar o comportamento durante o início do expediente, quando várias empresas clientes enviam solicitações ao mesmo tempo.
Ela monta mensagens sintéticas em português, com categorias e comprimentos variados. O teste conserva a proporção planejada de chamadas curtas e longas, mas não utiliza conversas de clientes. Primeiro confirma a resposta funcional com baixa concorrência. Depois executa carga esperada, um pico controlado e uma etapa de recuperação.
Se a fila crescer enquanto a utilização de GPU permanece baixa, a equipe investiga gateway, preparação de entrada e limites de conexão antes de comprar hardware. Se a inferência for o gargalo, compara configurações preservando o restante do cenário. Cada alteração precisa de uma hipótese explícita e uma nova medição comparável.
O relatório entregue ao produto contém cenário, critérios, taxa alcançada, latência por faixa e falhas. Também informa limites do ensaio e orçamento consumido. A decisão de liberar uma funcionalidade depende desses dados e da qualidade funcional, não de uma captura de tela com um número alto de requisições.
Erros comuns
- Considerar todo HTTP 200 um sucesso. Confira esquema, campos obrigatórios e resposta útil.
- Trocar modelo e infraestrutura simultaneamente. Controle variáveis para interpretar a comparação.
- Ignorar filas e recuperação. Parar de enviar tráfego não garante que o trabalho acumulado terminou.
- Esconder retentativas. Registre tentativas e falhas para não mascarar pressão adicional.
- Comparar entradas diferentes. Documente distribuição de tamanhos e parâmetros da geração.
- Publicar capacidade sem contexto. Informe cenário, limites e configuração medidos.
Perguntas frequentes
Locust mede qualidade da resposta de IA?
Ele pode executar validações programadas, mas a carga não substitui uma avaliação de qualidade. Use um conjunto de referência separado para verificar precisão, segurança e aderência ao comportamento esperado.
Quantos usuários preciso configurar?
Depende do fluxo e da duração das tarefas. Comece pequeno, observe a taxa alcançada e aumente conforme o plano. Usuários virtuais são uma configuração do gerador, não uma medida direta de clientes atendidos por segundo.
Posso testar diretamente uma API externa?
Somente dentro das condições autorizadas e dos limites acordados com o fornecedor. Prefira medir sua aplicação com orçamento controlado e separar falhas de integração, limites de conta e capacidade da infraestrutura própria.
Como tratar uma resposta que chega depois do timeout?
Para o cliente, o pedido falhou dentro do limite definido. Verifique se o servidor cancela o trabalho ou continua consumindo recursos. Retentativas sem essa informação podem duplicar carga e distorcer custos.
Um ensaio curto basta para liberar produção?
Ele ajuda a encontrar erros básicos, mas não representa necessariamente períodos prolongados, picos ou recuperação. Escolha duração e cenários conforme o risco do fluxo e documente o que ainda não foi medido.
