Testowanie obciążeniowe agenta usługi Databricks Apps

Testowanie obciążenia umożliwia znalezienie maksymalnej liczby zapytań na sekundę (QPS), które agent usługi Databricks Apps może utrzymać przed obniżeniem wydajności. Na tej stronie pokazano, jak wykonać następujące czynności:

1. Wdróż symulowaną wersję agenta, aby odizolować przepustowość infrastruktury od opóźnienia LLM.
2. Uruchom test obciążeniowy od rampy do nasycenia z Locust.
3. Analizowanie wyników za pomocą interaktywnego pulpitu nawigacyjnego.

Możesz postępować zgodnie ze ścieżką wspomaganą przez sztuczną inteligencję przy użyciu umiejętności Claude Code lub ręcznie skonfigurować każdy krok.

Requirements

• Obszar roboczy Azure Databricks z włączoną funkcjonalnością Databricks Apps.
• Aplikacja agenta wdrożona (lub gotowa do wdrożenia) w usłudze Databricks Apps przy użyciu zestawu SDK agentów OpenAI, LangGraph lub niestandardowej platformy. Zobacz Tworzenie agenta i wdrażanie go w usłudze Databricks Apps.
• CLI Databricks został zainstalowany i uwierzytelniony. Zobacz Instalowanie lub aktualizowanie interfejsu wiersza poleceń Databricks.
• Python 3.10+ z menedżerem pakietów uv.
• (W przypadku ścieżki wspomaganej przez sztuczną inteligencję) Zainstalowany program Claude Code .
• (W przypadku testów obciążeniowych dłuższych niż ~1 godzina) Jednostka usługi z poświadczeniami protokołu OAuth M2M (client_id i client_secret). Zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth.
  • W przypadku krótkich testów obciążeniowych (mniej niż ok. 1 godzina) istniejące poświadczenia OAuth użytkownika (U2M) z databricks auth login działają prawidłowo. W przypadku dłuższych testów użyj protokołu OAuth M2M z podmiotem usługi — tokeny U2M wygasają podczas długich przebiegów i powodują przerwanie testu. Utworzenie jednostki usługi wymaga dostępu administratora obszaru roboczego.

Konfiguracja wspomagana przez sztuczną inteligencję (zalecane)

Jeśli używasz programu Claude Code, /load-testing umiejętność automatyzuje przepływ pracy. Odczytuje on kod agenta, generuje pozorny kod, tworzy skrypty testowania obciążenia i przeprowadzi Cię przez wdrożenie.

Clone https://github.com/databricks/app-templates and run the /load-testing skill against the {your-template} template.

Krok 1. Klonowanie szablonu agenta

Umiejętność /load-testing jest zawarta w repozytorium databricks/app-templates, zarówno jako umiejętność najwyższego poziomu agent-load-testing, jak i wstępnie zsynchronizowana z każdym pojedynczym szablonem agenta. Jeśli masz już projekt z app-templates, masz już tę umiejętność.

Sklonuj repozytorium i przejdź do katalogu szablonu dla agenta, który chcesz załadować:

git clone https://github.com/databricks/app-templates.git
cd app-templates/{your-template}

Krok 2: Uruchomienie funkcjonalności testowania obciążenia

W programie Claude Code uruchom:

/load-testing

Umiejętność interaktywnie przeprowadzi Cię przez następujące kroki. Możesz pominąć symulowanie, aby przetestować rzeczywistego agenta, lub pominąć wdrażanie, jeśli twoje aplikacje są już uruchomione.

1. Zbieranie parametrów: pyta o stan wdrożenia, rozmiary obliczeniowe, konfiguracje procesów roboczych i poświadczenia protokołu OAuth.
2. Tworzenie skryptów testu obciążeniowego: generuje locustfile.py, run_load_test.py oraz dashboard_template.py dostosowane do projektu.
3. Symulowanie LLM: tworzy klienta symulującego dla konkretnego zestawu SDK (zestaw SDK agentów OpenAI, LangGraph lub niestandardowy), który zastępuje rzeczywiste wywołania LLM konfigurowalnymi opóźnieniami przesyłania strumieniowego.
4. Wdrażanie aplikacji testowych: przeprowadzi Cię przez proces wdrażania wielu konfiguracji aplikacji o różnych rozmiarach obliczeniowych i liczbach procesów roboczych.
5. Uruchamianie testów: przeprowadza test obciążeniowy z uwierzytelnianiem M2M OAuth i stopniowym zwiększaniem obciążenia do pełnej saturacji.
6. Generowanie wyników: tworzy interaktywny pulpit nawigacyjny HTML z metrykami QPS, opóźnieniami i awariami.

Ręczna konfiguracja

Wykonaj następujące kroki, aby skonfigurować i uruchomić testy obciążeniowe bez pomocy dotyczącej sztucznej inteligencji.

Krok 1. Opcjonalnie, symulacja wywołań LLM agenta

Pomiń ten krok, jeśli chcesz uzyskać kompleksowe wyniki, które obejmują rzeczywiste opóźnienie LLM. Aby zmierzyć przepustowość infrastruktury aplikacji Databricks w izolacji, zasymuluj działanie LLM, aby opóźnienie na żądanie (zwykle 1–30 sekund) nie stało się wąskim gardłem.

Mockowane odpowiedzi są zwracane z konfigurowalnym opóźnieniem przesyłania strumieniowego, zachowując pełny potok żądania/odpowiedzi (przesyłanie strumieniowe SSE, dystrybucja narzędzi, uruchamianie SDK) i zamianę tylko LLM. Odsłania maksymalną liczbę zapytań na sekundę (QPS), które platforma Databricks Apps może obsługiwać, i unika kosztów związanych z tokenami API modelu podstawy podczas testów obciążeniowych.

Czas symulacji jest kontrolowany przez dwie zmienne środowiskowe:

W przypadku wartości domyślnych każda pozorna odpowiedź trwa około 800 ms (10 ms x 80 fragmentów), znacznie szybciej niż rzeczywista odpowiedź LLM (3–15 sekund). Liczby przepływności odzwierciedlają następnie platformę, a nie model.

Utwórz pozornego klienta, który zastępuje rzeczywistego klienta LLM. Pozostała część kodu agenta pozostaje niezmieniona, a podejście zależy od zestawu SDK. Aby uzyskać informacje na temat interfejsu OpenAI, zobacz implementację referencyjnąmock_openai_client.py w pliku databricks/app-templates. Ten sam wzorzec dostosowuje się do innych zestawów SDK.

Zestaw SDK agentów OpenAI

Create agent_server/mock_openai_client.py — MockAsyncOpenAI klasa, która implementuje chat.completions.create() z przesyłaniem strumieniowym. Zwraca fragmenty wywołań narzędzi natychmiast (symulując LLM podejmującą decyzję o wywołaniu narzędzia) i fragmenty odpowiedzi tekstowej z konfigurowalnym opóźnieniem ze zmiennych środowiskowych MOCK_CHUNK_DELAY_MS i MOCK_CHUNK_COUNT.

Zamień go w swojego agenta:

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")

Pozostała część kodu agenta (programy obsługi, narzędzia, logika przesyłania strumieniowego) pozostaje niezmieniona.

LangGraph

ChatDatabricks Zastąp model pozorem, który zwraca wstępnie skompilowane AIMessage obiekty:

# Before:
# model = ChatDatabricks(endpoint="databricks-claude-sonnet-4")

# After:
from agent_server.mock_llm import MockChatModel
model = MockChatModel()

Makiety powinny zwracać AIMessage obiekty z wywołaniami narzędziowymi przy pierwszym wywołaniu oraz treścią tekstową przy kolejnych wywołaniach, z konfigurowalnymi opóźnieniami w przesyłaniu strumieniowym.

Agenci dostosowani

Opakuj wszystkie zewnętrzne wywołania API wykonywane przez agenta (LLM, AI Search, API narzędzi) w implementacje mockowe, które zwracają realistyczne struktury odpowiedzi z konfigurowalnymi opóźnieniami.

Krok 2. Konfigurowanie skryptów testowania obciążenia

load-test-scripts/ Utwórz katalog w projekcie. Struktura testowania obciążenia składa się z trzech skryptów, które są niezależne od struktury i współpracują z dowolnym agentem usługi 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

Struktura zawiera następujące pliki:

• locustfile.py: Test obciążenia Locust, który przesyła POST /invocations żądania z stream: true, analizuje strumienie SSE, śledzi czas do pierwszego tokenu (TTFT) jako metrykę niestandardową, używa wymiany tokenów OAuth M2M z automatycznym odświeżaniem i implementuje StepRampShape, który zwiększa liczbę użytkowników z step_size do max_users utrzymując każdy poziom przez step_duration sekundy.
• run_load_test.py: Orkiestrator CLI, który sekwencyjnie testuje każdy adres URL aplikacji z izolowanymi metrykami dla każdej konfiguracji. Obsługuje odświeżanie tokenu OAuth, uruchamia sprawdzanie kondycji i rozgrzewkę przed każdym testem i zapisuje wyniki w pliku load-test-runs/<run-name>/<label>/.
• dashboard_template.py: Generuje samodzielny pulpit nawigacyjny HTML przy użyciu Chart.js z kartami KPI, wykresami słupkowymi (QPS, opóźnieniami, TTFT by config), wykresami liniowymi postępu kroków QPS oraz pełną tabelą wyników. Można uruchomić autonomicznie: uv run dashboard_template.py ../load-test-runs/<run-name>/.

Instalowanie zależności

Skrypty testowania obciążenia używają własnych pyproject.toml wewnątrz load-test-scripts/, aby uniknąć zakłócania zależności produkcyjnych agenta. Utwórz 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",
]

Zainstaluj z poziomu load-test-scripts/ katalogu:

cd load-test-scripts/
uv sync

Krok 3. Wdrażanie aplikacji testowych z różną konfiguracją

Wdróż wiele aplikacji usługi Databricks z różnymi rozmiarami obliczeniowymi i liczbami procesów roboczych, aby znaleźć optymalną konfigurację obciążenia.

Zalecana macierz testowa

Poniższe konfiguracje koncentrują się na optymalnym ustawieniu zidentyfikowanym w poprzednich testach. Jeśli chcesz uzyskać szerszy zakres, dodaj jedną konfigurację po obu stronach (na przykład medium-w1 lub large-w12), ale sześć poniższych jest zwykle wystarczające.

Konfigurowanie rozmiaru obliczeniowego

Użyj interfejsu wiersza polecenia usługi Databricks, aby ustawić rozmiar obliczeniowy podczas tworzenia lub aktualizowania aplikacji:

# 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

Konfigurowanie liczby procesów roboczych przy użyciu pakietów deklaratywnej automatyzacji

start-server (za pośrednictwem AgentServer.run()) akceptuje flagę --workers bezpośrednio. Przekaż liczbę pracowników w tablicy command przy użyciu zmiennej 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'

Wdrażanie i weryfikowanie

Wdróż każdy element docelowy przy użyciu interfejsu wiersza polecenia usługi Databricks:

databricks bundle deploy --target medium-w2
databricks bundle run load_test_app --target medium-w2

Przed uruchomieniem testów obciążeniowych sprawdź, czy aplikacje są aktywne:

databricks apps get <app-name> --output json | jq '{app_status, compute_status, url}'

Krok 4. Uruchamianie testów obciążeniowych

Konfigurowanie uwierzytelniania

Wybierz metodę uwierzytelniania w zależności od tego, jak długo planujesz, by działało.

• Krótkie testy (mniej niż ok. 1 godzina): użyj istniejących poświadczeń użytkownika z witryny databricks auth login. Nie jest wymagana dodatkowa konfiguracja.
• Długie testy (więcej niż ok. 1 godzina, takie jak przebiegi z dnia na dzień): użyj protokołu OAuth M2M z jednostką usługi. Tokeny U2M wygasają i przerywają test w połowie przebiegu. Utworzenie jednostki usługi wymaga dostępu administratora obszaru roboczego.

W przypadku protokołu OAuth M2M wyeksportuj poświadczenia podmiotu usługi przed uruchomieniem testów.

export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_CLIENT_ID=<your-client-id>
export DATABRICKS_CLIENT_SECRET=<your-client-secret>

Odniesienie do parametrów

Przykładowe polecenia

Szybki test pojedynczej aplikacji (krótki czas — wykorzystuje Twoją sesję 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

Pełna macierz w zalecanych 6 konfiguracjach (długotrwała — przekazywanie poświadczeń M2M). Przekaż --compute-size flagi w tej samej kolejności co --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

Wiele przebiegów w celu zapewnienia spójności statystycznej:

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

Co się dzieje podczas wykonywania programu

1. Sprawdzanie kondycji: sprawdza prawidłowo strumienie aplikacji (odbiera [DONE]).
2. Rozgrzewka: wysyła sekwencyjne żądania, aby rozgrzać aplikację.
3. Rampowe nasycenie: kroki w górę współbieżnych użytkowników co step_duration sekund.
4. Wykrywanie nasycenia: kiedy QPS osiąga stabilizację mimo dodawania większej liczby użytkowników, osiągnięto limit przepustowości.

Szacowany czas trwania

Każda testowana aplikacja przechodzi przez własny proces, więc całkowity czas wykonywania zwiększa się proporcjonalnie do liczby konfiguracji w twojej macierzy. Użyj poniższej formuły, aby zaplanować okno uruchamiania.

Czas trwania aplikacji: (max_users / step_size) * step_duration sekundy.

Z wartościami domyślnymi (--max-users 300 --step-size 20 --step-duration 30):

• 15 kroków x 30 sekund = około 7,5 minut na aplikację
• Zalecana macierz sześciu konfiguracji: około 45 minut na czas przebiegu

Krok 5. Wyświetlanie i interpretowanie wyników

1. Otwórz pulpit nawigacyjny:

   open load-test-runs/<run-name>/dashboard.html
   

2. (Opcjonalnie) Wygeneruj ponownie pulpit nawigacyjny z istniejących danych, na przykład po zaktualizowaniu szablonu:

   cd load-test-scripts/
   uv run dashboard_template.py ../load-test-runs/<run-name>/
   

Sekcje pulpitu nawigacyjnego

Interaktywny pulpit nawigacyjny obejmuje:

• Karty KPI: najlepsza konfiguracja (według szczytowego udanego QPS), ogólna szczytowa QPS, najmniejsze opóźnienie i łączna liczba obsłużonych żądań.
• QPS by Config: pogrupowany wykres słupkowy przedstawiający medianę QPS, szczytowe QPS z wyłączeniem awarii oraz szczytowe QPS równocześnie dla każdej konfiguracji.
• Opóźnienie według konfiguracji: pogrupowane paski pokazujące opóźnienie p50 i p95.
• TTFT by Config: czas pierwszego tokenu (p50 i p95).
• Łączna liczba obsługiwanych żądań: liczba żądań na konfigurację.
• Progresja rampy QPS: wykresy liniowe z sekcjami QPS, QPS (z wyłączeniem awarii), Opóźnienie i Awarii. Obejmuje suwak max-users, aby skupić się na niższych wartościach współbieżności. Wykresy są pogrupowane według rozmiaru obliczeniowego (średni i duży obok siebie).
• Pełna tabela wyników: wszystkie konfiguracje ze szczytowym QPS, użytkownikami przy szczycie, percentylami opóźnień i wskaźnikiem awarii.
• Parametry testu: podsumowanie konfiguracji w celu odtworzenia.

Jak interpretować wyniki

• Szczytowa QPS: maksymalna liczba QPS osiągnięta w każdym kroku rampy. Jest to limit przepływności dla tej konfiguracji.
• Użytkownicy w momencie szczytu: liczba równoczesnych użytkowników, gdy osiągnięto szczytowe QPS. Dodanie większej liczby użytkowników poza ten punkt nie zwiększa przepływności.
• Współczynnik awarii: powinien wynosić 0% lub bardzo niski. Wysoka szybkość awarii oznacza, że aplikacja jest przeciążona na tym poziomie współbieżności.
• Wykres rampowy QPS: znajdź miejsce, w którym linia się spłaszcza. Jest to punkt nasycenia: dodanie większej liczby użytkowników nie zwiększy przepływności.

Referencyjne uruchomienie testu porównawczego na danych syntetycznych

W tej sekcji przedstawiono wyniki pomiarów z wewnętrznego testu porównawczego Azure Databricks przeprowadzonego na syntetycznej aplikacji agenta, w której każde wywołanie LLM było symulowane. To ćwiczenie odrębne od testów obciążeniowych własnego agenta: potraktuj je jako sposób, by zobaczyć, jakich wyników można się spodziewać, i uzyskać przybliżony punkt wyjścia do wstępnego wymiarowania.

Co pokazano w tym przebiegu

• Zalecana konfiguracja początkowa: 2 węzły robocze przy zasobach obliczeniowych Medium lub 8 węzłów roboczych przy zasobach Large.
• Więcej pracowników nie zawsze jest lepsze. W średnim, 2 pracowników (155.1 QPS) pokonało 4 pracowników (116,5 QPS) o ~33%. Symulowane obciążenie jest ograniczone wydajnością CPU, więc przy więcej niż 2 workerach pojawia się konkurencja o zasoby CPU i pamięci, która niweluje korzyści z dodatkowej równoległości. Prawdziwy agent ograniczony przez operacje wejścia/wyjścia, który głównie czeka na endpoint modelu, może skalować się lepiej niż ten mock, dlatego koniecznie przetestuj własnego agenta.
• Rozmiar obliczeniowy: wariant Large zapewniał około 2,2 razy większą przepustowość niż Medium (średni szczytowy QPS: 278,0 vs 123,5).
• Opóźnienie: wariant Large miał opóźnienie o ok. 20% niższe niż Medium (~906 ms vs 1 180 ms p50), a TTFT wynosił ~1 100 ms dla wariantu Large wobec 1 720–1 820 ms dla wariantu Medium.
• Niezawodność: szybkość awarii pozostała na poziomie lub blisko 0% dla każdej konfiguracji, nawet przy 1000 równoczesnych użytkownikach.

Ponieważ działanie LLM zasymulowano (strumieniowanie zasymulowano przy użyciu stałych opóźnień dla każdego fragmentu), są to wyniki dotyczące przepustowości infrastruktury, a nie wyniki end-to-end dla agenta. Mierzą, ile żądań FastAPI AgentServer aplikacji Databricks Apps może przetwarzać równolegle, a nie latencję rzeczywistego modelu. Agent produkcyjny, który wywołuje endpoint działającego modelu LLM, notuje niższy QPS i wyższą latencję, przy czym dominuje czas odpowiedzi modelu. Twoje wyniki różnią się w zależności od złożoności agenta, rozmiaru danych wejściowych, liczby wywołań narzędzi, regionu i używanego punktu końcowego modelu. Aby prawidłowo dobrać rozmiar, uruchom test obciążeniowy na własnym agencie.

Poniższa tabela przedstawia pełne zestawienie wyników dla każdej konfiguracji.

Warunki testu

• Uruchomienie referencyjne: 5 identycznych rund dla 8 konfiguracji aplikacji (4 ze średnimi zasobami obliczeniowymi, 4 z dużymi), z których każda ma inną liczbę workerów uvicorn.
• Rampa: od 20 do 1000 współbieżnych użytkowników w krokach 20 użytkowników przechowywanych przez 10 sekund (50 kroków na konfigurację).
• Agent symulowany: strumieniowe odpowiedzi po około 95 fragmentów na każde żądanie, symulujące strumieniowanie tokenów LLM.
• Liczba: około 1,46 miliona żądań łącznie we wszystkich uruchomieniach.

Maksymalna liczba QPS dla poszczególnych konfiguracji

Szczytowa wartość QPS jest średnią z 5 przebiegów.

Uśrednione według rozmiaru mocy obliczeniowej:

W tym uruchomieniu konfiguracja Large zapewniła około 2,2 razy większą przepustowość niż konfiguracja Medium.

Troubleshooting

Dodatkowe zasoby

• Przetestuj przy użyciu rzeczywistych wywołań LLM: pomiń krok pozorowania i wdróż faktycznego agenta, aby zmierzyć opóźnienie od końca do końca, w tym czas reakcji LLM.
• Optymalizacja liczby procesów roboczych: użyj wyników macierzy testów, aby znaleźć optymalną liczbę procesów roboczych dla wielkości obliczeniowej.
• Samouczek: Oceń i ulepsz agenta, aby mierzyć dokładność, trafność i bezpieczeństwo, a także przepustowość.
• Przygotuj agenta Databricks Apps do wdrożenia produkcyjnego, aby przejść pełną ścieżkę przygotowania do środowiska produkcyjnego, w tym AI Gateway.