Faça o teste de carga do seu agente do Databricks Apps
Testes de carga encontram o número máximo de queries por segundo (QPS) que seu agente do Databricks Apps pode suportar antes que o desempenho se degrade. Esta página mostra como fazer o seguinte:
- Implante uma versão simulada de seu agente para isolar o throughput da infraestrutura da latência da LLM.
- Execute um teste de carga de rampa para saturação com Locust.
- Analise os resultados com um painel interativo.
Você pode seguir o caminho assistido por AI usando uma habilidade do Claude Code ou configurar cada passo manualmente.
Requisitos
- Um workspace do Databricks com Databricks Apps habilitado.
- Um aplicativo de agente implantado (ou pronto para ser implantado) no Databricks Apps usando o OpenAI Agents SDK, LangGraph ou uma estrutura personalizada. Consulte Crie um agente de AI e implante-o no Databricks Apps.
- A CLI do Databricks instalada e autenticada. Consulte Instalar ou atualizar a CLI do Databricks.
- Python 3.10+ com gerenciador de pacote
uv. - (Para o caminho assistido por AI) Claude Code instalado.
- (Para testes de carga com duração superior a ~1 hora) Uma Service Principal com credenciais M2M OAuth (
client_ideclient_secret). Consulte Autorizar o acesso da Service Principal ao Databricks com OAuth.- Para testes de carga curtos (com menos de ~1 hora), suas credenciais OAuth de usuário (U2M) existentes de
databricks auth loginfuncionam bem. Para testes mais longos, use OAuth M2M com um Service Principal do Databricks — tokens U2M expiram durante execuções longas e causam falhas no meio do teste. A criação de um Databricks Service Principal requer acesso de administrador do Workspace.
- Para testes de carga curtos (com menos de ~1 hora), suas credenciais OAuth de usuário (U2M) existentes de
Configuração assistida por AI (recomendado)
Se você usar o Claude Code, a habilidade /load-testing automatiza o fluxo de trabalho. Ele lê seu código de agente, gera um mock, cria scripts de teste de carga e guia você pela implantação.
Instrua o Claude Code a fazer isso por você:
Clone https://github.com/databricks/app-templates and run the /load-testing skill against the {your-template} template.
Ou siga as etapas abaixo.
Passo 1: Clone um padrão de agente
A habilidade /load-testing está incluída no repository databricks/app-templates, tanto como a habilidade principal agent-load-testing quanto pré-sincronizada em cada padrão de agente individual. Se você já tem um projeto de app-templates, você já possui a habilidade.
Clone o repo e mude para o diretório de padrão para o agente que você deseja testar a carga:
git clone https://github.com/databricks/app-templates.git
cd app-templates/{your-template}
Passo 2: Executar a habilidade de teste de carga
No Claude Code, execute:
/load-testing
A habilidade o guia pelos os passos seguintes. É possível ignorar a simulação para testar seu agente real, ou ignorar a implantação se seus aplicativos já estiverem em execução.
- Coleta de Parâmetros : solicita informações sobre o status da implantação, tamanhos de compute, configurações de worker e credenciais OAuth.
- Criação de scripts de teste de carga : gera
locustfile.py,run_load_test.pyedashboard_template.pyadaptados ao seu projeto. - **Simulando seu LLM**: cria um cliente simulado específico para seu SDK (SDK de Agentes OpenAI, LangGraph ou personalizado) que substitui chamadas reais do LLM por atrasos de transmissão configuráveis.
- Implantação de aplicativos de teste : orienta na implantação de várias configurações de aplicativo com diferentes tamanhos de compute e contagens de workers.
- **Executando testes**: executa o teste de carga com autenticação M2M OAuth e ramp-to-saturation.
- **Geração de resultados**: produz um dashboard HTML interativo com QPS, latência e métricas de falha.
Configuração manual
Siga estes passos para configurar e executar testes de carga sem assistência de AI.
O passo 1: Simule as chamadas LLM do seu agente (opcional)
Pule este passo se quiser resultados de ponta a ponta que incluam latência real do LLM. Para medir o throughput da infraestrutura do Databricks Apps isoladamente, simule o LLM para que sua latência por solicitação (normal-mente 1-30 segundos) não se torne o gargalo.
Um mock retorna respostas pré-definidas com um atraso de transmissão configurável, preservando o pipeline completo de solicitação/resposta (transmissão SSE, despacho de ferramenta, executor SDK) e trocando apenas o LLM. Isso mostra o QPS máximo que a plataforma Databricks Apps pode entregar e evita custos de tokens da API do Foundation Model durante testes de carga.
O tempo simulado é controlado por duas variáveis de ambiente:
Variável | Padrão | Descrição |
|---|---|---|
|
| Atraso em milissegundos entre os fragmentos de texto de transmissão |
|
| Número de blocos de texto por resposta |
Com os default, cada resposta simulada leva aproximadamente 800 ms (10 ms x 80 blocos), significativamente mais rápido do que uma resposta de LLM real (3-15 segundos). Os números de throughput então refletem a plataforma, não o modelo.
Criar um cliente simulado que substitua o cliente LLM real. O resto do seu código de agente permanece inalterado, e a abordagem depende do seu SDK. Para OpenAI, consulte a implementação de referênciamock_openai_client.py em databricks/app-templates. O mesmo padrão se adapta a outros SDKs.
- OpenAI Agents SDK
- LangGraph
- Custom agents
Crie agent_server/mock_openai_client.py — uma classe MockAsyncOpenAI que implementa chat.completions.create() com transmissão. Ele retorna blocos de chamadas de ferramentas instantaneamente (simulando o LLM decidindo chamar uma ferramenta) e blocos de resposta de texto com atraso configurável das variáveis de ambiente MOCK_CHUNK_DELAY_MS e MOCK_CHUNK_COUNT.
Faça o swap dele para seu agente:
from agent_server.mock_openai_client import MockAsyncOpenAI
from agents import set_default_openai_client, set_default_openai_api
set_default_openai_client(MockAsyncOpenAI())
set_default_openai_api("chat_completions")
O restante do código do seu agente (manipuladores, ferramentas, lógica de transmissão) permanece inalterado.
Substitua o modelo ChatDatabricks por uma simulação que retorna objetos AIMessage pré-criados:
# Before:
# model = ChatDatabricks(endpoint="databricks-claude-sonnet-4")
# After:
from agent_server.mock_llm import MockChatModel
model = MockChatModel()
O mock deve retornar AIMessage objetos com chamadas de ferramenta na primeira invocação e conteúdo de texto em invocações subsequentes, com atrasos de transmissão configuráveis.
Encapsule quaisquer chamadas externas de API que seu agente fizer (LLM, AI Search, APIs de ferramentas) com implementações simuladas que retornem formatos de resposta realistas com atrasos configuráveis.
Passo 2: Configurar scripts de teste de carga
Crie um diretório load-test-scripts/ em seu projeto. A estrutura de teste de carga consiste em três scripts que são agnósticas à estrutura e funcionam com qualquer agente do Databricks Apps.
<project-root>/
agent_server/ # Your existing agent code
load-test-scripts/ # Load testing scripts (create this)
run_load_test.py # CLI orchestrator
locustfile.py # Locust test with SSE streaming + TTFT tracking
dashboard_template.py # Interactive HTML dashboard generator
load-test-runs/ # Results (auto-created per run)
<run-name>/
dashboard.html # Interactive dashboard
test_config.json # Test parameters for reproducibility
<label>/ # Per-config Locust CSV output
A estrutura inclui os seguintes arquivos:
locustfile.py** **: Um teste de carga Locust que enviaPOST /invocationssolicitaçõesstream: truecom, analisa transmissões SSE, rastreiaStepRampShapestep_sizemax_usersostep_durationtempo até o primeiro token (TTFT) como uma métrica personalizada, usa troca de tokens OAuth M2M com auto-refresh e implementa um que aumenta os usuários de para enquanto mantém cada nível por segundos.run_load_test.py: Um orquestrador de CLI que testa cada URL de aplicativo sequencialmente com métricas isoladas por configuração. Ele gerencia o refresh de tokens OAuth, executa uma verificação de integridade e um aquecimento antes de cada teste, e salva os resultados emload-test-runs/<run-name>/<label>/.dashboard_template.py: Gera um painel HTML autocontido usando Chart.js com cartões de KPI, gráficos de barras (QPS, latência, TTFT por configuração), gráficos de linha de progressão da rampa de QPS e uma tabela de resultados completa. Pode ser executado de forma autônoma:uv run dashboard_template.py ../load-test-runs/<run-name>/.
Instalar dependências
Os scripts de teste de carga usam seus próprios pyproject.toml dentro de load-test-scripts/ para evitar poluir as dependências de produção do seu agente. Crie load-test-scripts/pyproject.toml:
[project]
name = "load-test-scripts"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
"locust>=2.32,<2.40",
"urllib3<2.3",
"requests",
]
pin locust em <2.40. As versões mais recentes (>=2.43) têm um RecursionError conhecido que interrompe testes de carga longos.
Instale no diretório load-test-scripts/:
cd load-test-scripts/
uv sync
Passo 3: Implantar aplicativos de teste com configurações variadas
Implante vários Databricks Apps com diferentes tamanhos de compute e número de workers para encontrar a configuração ideal para sua carga de trabalho.
Matriz de teste recomendada
As configurações abaixo se concentram no ponto ideal identificado em testes anteriores. Se você quiser uma cobertura mais ampla, adicione uma configuração em cada lado (por exemplo, medium-w1 ou large-w12), mas as seis abaixo geralmente são suficientes.
Tamanho de compute | Workers | Nome de aplicativo sugerido |
|---|---|---|
Médio | 2 |
|
Médio | 3 |
|
Médio | 4 |
|
Grande | 6 |
|
Grande | 8 |
|
Grande | 10 |
|
Configurar tamanho do compute
Use a CLI do Databricks para definir o tamanho do compute ao criar ou atualizar um aplicativo:
# Create a new app with Medium compute
databricks apps create <app-name> --compute-size MEDIUM
# Update an existing app to Large compute
databricks apps update <app-name> --compute-size LARGE
Configure a quantidade de worker com pacotes de automação declarativa.
start-server (via AgentServer.run()) aceita um sinalizador --workers diretamente. Passe a contagem de workers no array command usando uma variável DAB:
variables:
app_name:
default: 'my-agent-medium-w2'
workers:
default: '2'
resources:
apps:
load_test_app:
name: ${var.app_name}
source_code_path: .
config:
command: ['uv', 'run', 'start-server', '--workers', '${var.workers}']
env:
- name: MOCK_CHUNK_DELAY_MS
value: '10'
- name: MOCK_CHUNK_COUNT
value: '80'
targets:
medium-w2:
default: true
variables:
app_name: 'my-agent-medium-w2'
workers: '2'
large-w8:
variables:
app_name: 'my-agent-large-w8'
workers: '8'
Implantar e verificar
Implante cada destino com a CLI do Databricks:
databricks bundle deploy --target medium-w2
databricks bundle run load_test_app --target medium-w2
Verifique se os aplicativos estão ativos antes de executar os testes de carga:
databricks apps get <app-name> --output json | jq '{app_status, compute_status, url}'
Aguarde até que todos os aplicativos atinjam o status ACTIVE antes de prosseguir. Aplicativos que ainda estão começando produzem resultados enganosos.
Passo 4: Executar testes de carga
Configurar autenticação
Selecione sua autenticação com base em quanto tempo você planeja executar:
- Testes curtos (menos de ~1 hora) : use suas credenciais de usuário existentes de
databricks auth login. Nenhuma configuração extra é necessária. - Testes longos (mais de ~1 hora, como execuções noturnas) : use OAuth M2M com um service principal do Databricks. Os tokens U2M expiram e interrompem seu teste no meio da execução. A criação de um service principal do Databricks requer acesso de administrador do workspace.
Para OAuth M2M, exporte as credenciais do Service Principal do Databricks antes de executar testes:
export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_CLIENT_ID=<your-client-id>
export DATABRICKS_CLIENT_SECRET=<your-client-secret>
Referência de parâmetros
Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
| Sim | — | URL(s) do aplicativo para testar (repetível) |
| Para testes longos |
| ID do cliente do Service Principal (M2M OAuth) |
| Para testes longos |
| Segredo do cliente do Service Principal (OAuth M2M) |
| Não | Derivado automaticamente do URL | Rótulo legível por humanos por aplicativo (repetível) |
| Não | Detectado automaticamente ou | Tag de tamanho de Compute por aplicativo: |
| Não |
| Número máximo de usuários simulados concorrentes |
| Não |
| Usuários adicionados por passo de rampa |
| Não |
| Segundos por passo de rampa |
| Não |
| Taxa de geração de usuários (usuários/seg) |
| Não |
| Nome para esta execução — resultados salvos em |
| Não | Desativada | Gerar dashboard HTML interativo após a conclusão dos testes |
Comandos de exemplo
Teste rápido de aplicativo único (execução curta — usa sua sessão databricks auth login):
cd load-test-scripts/
uv run run_load_test.py \
--app-url https://my-app.aws.databricksapps.com \
--dashboard --run-name quick-test
Matriz completa em todas as 6 configurações recomendadas (execução longa — passar credenciais M2M). Passar --compute-size sinalizadores na mesma ordem que --app-url:
uv run run_load_test.py \
--app-url https://my-app-medium-w2.aws.databricksapps.com \
--app-url https://my-app-medium-w3.aws.databricksapps.com \
--app-url https://my-app-medium-w4.aws.databricksapps.com \
--app-url https://my-app-large-w6.aws.databricksapps.com \
--app-url https://my-app-large-w8.aws.databricksapps.com \
--app-url https://my-app-large-w10.aws.databricksapps.com \
--compute-size medium --compute-size medium --compute-size medium \
--compute-size large --compute-size large --compute-size large \
--client-id $DATABRICKS_CLIENT_ID \
--client-secret $DATABRICKS_CLIENT_SECRET \
--dashboard --run-name overnight-sweep
Várias execuções para consistência estatística:
for RUN in r1 r2 r3 r4 r5; do
uv run run_load_test.py \
--app-url https://my-app.aws.databricksapps.com \
--client-id $DATABRICKS_CLIENT_ID \
--client-secret $DATABRICKS_CLIENT_SECRET \
--max-users 1000 --step-size 20 --step-duration 10 \
--run-name my_test_${RUN} --dashboard || break
done
O que acontece durante uma execução
- Verificação de integridade: verifica se o aplicativo transmite corretamente
[DONE](recebe). - Aquecimento: envia solicitações sequenciais para aquecer o aplicativo.
- Rampa para saturação: aumenta os usuários concorrentes a cada
step_durationsegundos. - Detecção de saturação : quando o QPS estabiliza apesar de adicionar mais usuários, você atingiu o limite de throughput.
Duração estimada
Cada aplicativo em teste é executado em sua própria rampa, portanto, o tempo total de execução escala com o número de configurações em sua matriz. Use a fórmula abaixo para planejar sua janela de execução.
Duração por aplicativo: (max_users / step_size) * step_duration segundos.
Com default (--max-users 300 --step-size 20 --step-duration 30):
- 15 etapas x 30 segundos = aproximadamente 7,5 minutos por aplicativo
- Para a matriz de 6 configurações recomendada: aproximadamente 45 minutos por execução.
Etapa 5: view e interpretar resultados
-
Abra o painel:
Bashopen load-test-runs/<run-name>/dashboard.html -
(Opcional) Regenere o painel a partir de dados existentes, por exemplo, após atualizar o padrão:
Bashcd load-test-scripts/
uv run dashboard_template.py ../load-test-runs/<run-name>/
Seções do painel
O dashboard interativo inclui:
- Cartões KPI : melhor configuração (por pico de QPS bem-sucedidas), pico geral de QPS, menor latência e total de solicitações atendidas.
- QPS por Configuração : gráfico de barras agrupadas mostrando QPS mediano, QPS de pico excluindo falhas e QPS de pico lado a lado para cada configuração.
- Latência por Configuração : barras agrupadas mostrando latência p50 e p95.
- TTFT by Config : tempo até o primeiro token (p50 e p95).
- Total de solicitações atendidas : contagem de solicitações por configuração.
- Progressão da Rampa QPS : gráficos de linha com tabs para QPS, QPS (excluindo falhas), Latência e Falhas. Inclui um controle deslizante de usuários máximos para detalhar intervalos de concorrência menores. Os gráficos são agrupados por tamanho do compute (médio e grande lado a lado).
- Tabela Completa de Resultados : todas as configurações com QPS de pico, usuários no pico, percentis de latência e taxa de falha.
- **Parâmetros de Teste**: resumo de configuração para reprodutibilidade.
Como interpretar resultados
- QPS de pico : o QPS máximo alcançado em qualquer o passo de rampa. Este é o limite máximo de throughput para essa configuração.
- Usuários de pico : o número de usuários concorrentes quando o pico de QPS foi atingido. Adicionar mais usuários além deste ponto não aumenta o throughput.
- Taxa de Falha : deve ser 0% ou muito baixa. Uma taxa de falha alta significa que o aplicativo está sobrecarregado naquele nível de simultaneidade.
- **Gráfico de rampa de QPS**: procure onde a linha se estabiliza. Esse é o ponto de saturação: adicionar mais usuários não aumentará o throughput.
Execução de referência de benchmark em dados sintéticos
Esta seção relata o que uma execução de benchmark interna do Databricks mediu em relação a um aplicativo de agente sintético, onde cada chamada de LLM foi simulada. É um exercício separado de testar a carga do seu próprio agente: use-o para ver o formato dos resultados que você pode esperar e para obter um ponto de partida aproximado para o dimensionamento.
O que esta execução mostrou
- Ponto de partida recomendado : 2 workers em compute Médio, ou 8 workers em Grande.
- Nem sempre mais workers é melhor. Em médio, 2 workers (155,1 QPS) superaram 4 workers (116,5 QPS) em cerca de 33%. A carga de trabalho simulada é restrita à CPU, então, após 2 workers, você atinge uma contenção de CPU/memória que anula o paralelismo extra. Um agente real restrito a E/S que aguarda principalmente um endpoint de modelo pode escalar mais do que esta simulação, então, certifique-se de testar seu próprio agente.
- Tamanho do Compute : Grande entregou aproximadamente 2,2x o throughput do Médio (278,0 vs 123,5 QPS de pico médio).
- Latência : Grande teve um desempenho ~20% menor que o Médio (~906 ms x 1.180 ms p50), com TTFT de ~1.100 ms no Grande x 1.720-1.820 ms no Médio.
- Confiabilidade : a taxa de falha permaneceu em ou perto de 0% para cada configuração, mesmo com 1.000 usuários concorrentes.
Como o LLM foi simulado (transmissão simulada com atrasos fixos por segmento), estes são números de throughput da infraestrutura, e não números de agente de ponta a ponta. Eles medem quantas solicitações o Databricks Apps FastAPI AgentServer pode processar em paralelo, não a latência de um modelo real. Um agente de produção que chama um Endpoint de LLM ativo apresenta QPS mais baixo e latência mais alta, dominado pelo tempo de resposta do modelo. Seus próprios números variam com a complexidade do agente, tamanho da carga útil, chamadas de ferramentas, região e o Endpoint do modelo que você chama. Para um dimensionamento preciso, execute um teste de carga em seu próprio agente.
Os resultados tabelados abaixo mostram o detalhamento completo por configuração.
Condições de teste
- Execução de referência : 5 rodadas idênticas contra 8 configurações de aplicativo (4 compute Médio, 4 compute Grande), cada uma com uma contagem de workers uvicorn diferente.
- Rampa : 20 a 1.000 usuários concorrentes, em etapas de 20 usuários, mantidas por 10 segundos cada (50 etapas por configuração).
- Agente simulado : respostas de transmissão de cerca de 95 blocos por solicitação, simulando a transmissão de tokens do LLM.
- Volume : cerca de 1,46 milhão de solicitações totais em todas as execuções.
QPS de pico por configuração
A média de QPS é calculada nas 5 execuções.
Tamanho de compute | Workers | Pico médio de QPS | Intervalo de pico | Taxa de falha |
|---|---|---|---|---|
Médio | 2 | 155,1 | 137,0–166,6 | 0,0% |
Médio | 4 | 116,5 | 112,6–121,8 | 0,1% |
Médio | 6 | 111,9 | 102,6–117,5 | 0,0% |
Médio | 8 | 110,3 | 108,3–112,1 | 0,0% |
Grande | 6 | 281,6 | 268,2–292,4 | 0,0% |
Grande | 8 | 268,2 | 265,8–271,0 | 0,0% |
Grande | 10 | 288,1 | 280,3–299,4 | 0,0% |
Grande | 12 | 274,2 | 269,4–278,8 | 0,0% |
Média por tamanho do compute:
Tamanho de compute | Pico médio de QPS | Média de QPS |
|---|---|---|
Médio | 123,5 | 45,5 |
Grande | 278,0 | 100,1 |
Nesta execução, o compute Grande entregou aproximadamente 2,2 vezes o throughput do compute Médio.
Solução de problemas
Problema | soluções |
|---|---|
O token de autenticação expirou no meio do teste | Para testes com duração superior a aproximadamente 1 hora, alterne de U2M para M2M OAuth passando |
Falha na verificação de integridade | Verifique se o aplicativo está ATIVO: |
0 QPS ou nenhum resultado | Verifique se há erros em |
Baixo QPS, apesar da alta contagem de usuários | O aplicativo está saturado. Tente mais workers ou compute maior. |
Alta taxa de falha | O aplicativo está sobrecarregado. Reduza |
O painel não mostra dados de rampa | Verifique se |
Outros recursos
- Teste com chamadas reais de LLM: ignore o passo de simulação e implante seu agente real para medir a latência de ponta a ponta, incluindo o tempo de resposta do LLM.
- Ajustar a contagem de workers : use os resultados da matriz de teste para encontrar a contagem ideal de workers para o seu tamanho de compute.
- Tutorial: Avalie e melhore um aplicativo GenAI para medir precisão, relevância e segurança, juntamente com o throughput.
- Coloque seu agente de Databricks Apps em produção para a sequência completa de prontidão para produção, incluindo o AI Gateway.