Proveďte zátěžový test agenta aplikací Databricks

Zátěžové testování najde maximální počet dotazů za sekundu (QPS), které může agent Databricks Apps udržovat, než dojde ke snížení výkonu. Na této stránce se dozvíte, jak provést následující akce:

  1. Nasaďte napodobenou verzi agenta, která izoluje propustnost infrastruktury od latence LLM.
  2. Proveďte zátěžový test ramp-to-saturation pomocí Locust.
  3. Analýza výsledků pomocí interaktivního řídicího panelu

Pomocí dovednosti Clauda Code můžete postupovat podle cesty s asistencí umělé inteligence nebo můžete jednotlivé kroky nastavit ručně.

Animovaný náhled řídicího panelu zátěžového testování zobrazující grafy průběhu QPS, latence a nájezdu napříč konfiguracemi výpočetních prostředků

Požadavky

  • Pracovní prostor Azure Databricks s povolenými aplikacemi Databricks.
  • Aplikace agenta nasazená (nebo připravená k nasazení) v Databricks Apps pomocí sady OpenAI Agents SDK, LangGraph nebo vlastní architektury. Viz Vytvoření agenta AI a jeho nasazení v Databricks Apps.
  • Rozhraní příkazového řádku Databricks je nainstalované a ověřené. Viz Instalaci nebo aktualizaci rozhraní příkazového řádku Databricks.
  • Python 3.10+ se správcem balíčků uv.
  • (Pro cestu s asistencí umělé inteligence) Clauda Code byla nainstalována.
  • (Pro zátěžové testy delší než ~1 hodinu) Služební identita s přihlašovacími údaji M2M OAuth (client_id a client_secret). Viz Autorizace přístupu servisního principála k Azure Databricks pomocí OAuth.
    • Při krátkých zátěžových testech (méně než přibližně 1 hodinu) vaše stávající U2M OAuth přihlašovací údaje fungují správně databricks auth login. V případě delších testů použijte M2M OAuth se služebním účtem – platnost tokenů U2M vyprší během dlouhých spuštění a způsobí selhání během testu. Vytvoření instančního objektu služby vyžaduje přístup správce pracovního prostoru.

Pokud používáte Claude Code, /load-testing dovednost automatizuje pracovní postup. Načte kód vašeho agenta, vygeneruje napodobení, vytvoří skripty zátěžového testování a provede vás nasazením.

Tip

Řekněte Claudovi Code, aby to udělal za vás:

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

Nebo postupujte podle následujících kroků.

Krok 1: Klonování šablony agenta

Dovednost /load-testing je součástí úložiště databricks/app-templates, jak jako dovednost nejvyšší úrovně agent-load-testing, tak i předem synchronizovaná do každé jednotlivé šablony agenta. Pokud už máte projekt od app-templates, už máte dovednost.

Naklonujte úložiště a přejděte do adresáře šablony pro agenta, kterého chcete zatížit testem.

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

Krok 2: Spuštění schopnosti zátěžového testování

V Claudu Code spusťte:

/load-testing

Dovednost vás interaktivně provede následujícími kroky. Můžete přeskočit napodobování a otestovat skutečného agenta nebo přeskočit nasazení, pokud už vaše aplikace běží.

  1. Shromažďování parametrů: dotaz na stav nasazení, velikosti výpočetních prostředků, konfigurace pracovních procesů a přihlašovací údaje OAuth.
  2. Vytváření skriptů zátěžového testu: vygeneruje locustfile.pyrun_load_test.pya dashboard_template.py na míru vašemu projektu.
  3. Napodobení LLM: vytvoří předstíraného klienta specifického pro vaši sadu SDK (OpenAI Agents SDK, LangGraph nebo vlastní), který nahrazuje skutečná volání LLM konfigurovatelnými zpožděními streamování.
  4. Nasazení testovacích aplikací: provede vás nasazením více konfigurací aplikací s různými velikostmi výpočetních prostředků a počty pracovních procesů.
  5. Spouštění testů: Provádí zátěžový test s ověřováním M2M OAuth a postupným zvyšováním zátěže až do nasycení.
  6. Generování výsledků: vytvoří interaktivní řídicí panel HTML s metrikami QPS, latence a selhání.

Ruční nastavení

Pokud chcete nastavit a spustit zátěžové testy bez pomoci S AI, postupujte podle těchto kroků.

Krok 1: Napodobte volání LLM agenta (volitelné)

Tento krok přeskočte, pokud chcete mít kompletní výsledky, které zahrnují skutečnou latenci LLM. Pokud chcete měřit propustnost infrastruktury Databricks Apps izolovaně, napodobit LLM, aby se latence jednotlivých požadavků (obvykle 1–30 sekund) nestala kritickým bodem.

Mock vrací předem připravené odpovědi s konfigurovatelným zpožděním streamování, přičemž je zachován celý proces požadavků a odpovědí (SSE streamování, distribuce nástrojů, spouštěč SDK) a zamění se pouze LLM. Tím se zobrazí maximální počet QPS, který platforma Databricks Apps dokáže během zátěžových testů poskytovat a vyhnout se nákladům na token rozhraní API modelu Foundation.

Časování emulace je řízeno dvěma proměnnými prostředí:

Variable Default Description
MOCK_CHUNK_DELAY_MS 10 Zpoždění v milisekundách mezi streamovanými textovými bloky
MOCK_CHUNK_COUNT 80 Počet bloků textu na odpověď

Ve výchozím nastavení každá napodobená odpověď trvá přibližně 800 ms (10 ms x 80 bloků dat), výrazně rychleji než skutečná odpověď LLM (3–15 sekund). Čísla propustnosti pak odrážejí platformu, nikoli model.

Vytvořte napodobení klienta, který nahradí skutečného klienta LLM. Zbytek kódu agenta zůstane beze změny a přístup závisí na vaší sadě SDK. Informace o OpenAI naleznete v referenční implementacimock_openai_client.py v databricks/app-templates. Stejný vzor se přizpůsobí jiným sadám SDK.

OpenAI Agents SDK

Vytvořte agent_server/mock_openai_client.py — třídu MockAsyncOpenAI, která implementuje chat.completions.create() se streamováním. Vrátí bloky volání nástroje okamžitě (simuluje rozhodování LLM o volání nástroje) a bloky textových odpovědí s konfigurovatelným zpožděním od proměnných prostředí MOCK_CHUNK_DELAY_MS a MOCK_CHUNK_COUNT.

Prohoďte ho do svého 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")

Zbytek kódu agenta (obslužné rutiny, nástroje, logika streamování) zůstane beze změny.

LangGraph

ChatDatabricks Nahraďte model napodobeným objektem, který vrací předdefinované AIMessage objekty:

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

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

Napodobení by se mělo vracet AIMessage objekty při použití nástrojových volání při prvním vyvolání a s textovým obsahem při následujících voláních, s konfigurovatelným zpožděním při streamování.

Vlastní agenti

Obalte veškerá externí API volání, která váš agent provádí (LLM, AI Search, API nástrojů), mock implementacemi, které vracejí realistickou strukturu odpovědí s konfigurovatelnými prodlevami.

Krok 2: Nastavení skriptů zátěžového testování

Vytvořte load-test-scripts/ adresář v projektu. Architektura zátěžového testování se skládá ze tří skriptů, které jsou nezávislé na architektuře a pracují s libovolným agentem 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

Architektura obsahuje následující soubory:

  • locustfile.py: Zátěžový test Locust, který odesílá POST /invocations požadavky pomocí stream: true, rozebírá streamy SSE, sleduje čas prvního tokenu (TTFT) jako vlastní metriku, používá M2M OAuth výměnu tokenů s automatickým obnovením a implementuje metodu StepRampShape, která zvyšuje počet uživatelů z step_size na max_users a drží každou úroveň po dobu step_duration sekund.
  • run_load_test.py: CLI orchestrátor, který postupně testuje každou URL aplikace s izolovanými metrikami pro každou konfiguraci. cs-CZ: Zpracovává aktualizaci tokenu OAuth, před každým testem spustí kontrolu stavu, vykoná přípravné činnosti a uloží výsledky do load-test-runs/<run-name>/<label>/.
  • dashboard_template.py: Vygeneruje samostatný řídicí panel HTML pomocí Chart.js s kartami klíčových ukazatelů výkonu, pruhovými grafy (QPS, latence, TTFT podle konfigurace), spojnicovými grafy průběhu rampy QPS a kompletní tabulkou výsledků. Lze spustit samostatně: uv run dashboard_template.py ../load-test-runs/<run-name>/.

Nainstalujte závislosti

Skripty zátěžového testování používají své vlastní pyproject.toml uvnitř load-test-scripts/ , aby se zabránilo znečišťování produkčních závislostí vašeho agenta. Vytvořit 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",
]

Note

Připnout locust na <2.40. Novější verze (>=2.43) mají známé RecursionError, které způsobují přerušení dlouhých zátěžových testů.

Instalace z adresáře load-test-scripts/ :

cd load-test-scripts/
uv sync

Krok 3: Nasazení testovacích aplikací s různými konfiguracemi

Nasaďte několik aplikací Databricks s různými velikostmi výpočetních prostředků a počty pracovních procesů, abyste našli optimální konfiguraci pro vaši úlohu.

Následující konfigurace se zaměřují na optimální bod zjištěný z předchozích testů. Pokud chcete širší pokrytí, přidejte jednu konfiguraci na obou stranách (například medium-w1 nebo large-w12), ale šest níže obvykle stačí.

Vypočítat velikost Pracovníci Navrhovaný název aplikace
Medium 2 <your-app>-medium-w2
Medium 3 <your-app>-medium-w3
Medium 4 <your-app>-medium-w4
Velké 6 <your-app>-large-w6
Velké 8 <your-app>-large-w8
Velké 10 <your-app>-large-w10

Konfigurace velikosti výpočetních prostředků

Pomocí rozhraní příkazového řádku Databricks můžete nastavit velikost výpočetních prostředků při vytváření nebo aktualizaci aplikace:

# 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

Konfigurace počtu pracovních procesů pomocí deklarativních automatizačních sad

start-server (prostřednictvím AgentServer.run()) --workers přijímá příznak přímo. V poli command pomocí proměnné DAB předat počet pracovníků.

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'

Nasazení a ověření

Nasaďte každý cíl pomocí rozhraní příkazového řádku Databricks:

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

Před spuštěním zátěžových testů ověřte, že jsou aplikace aktivní:

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

Note

Než budete pokračovat, počkejte, až se všechny aplikace dostanou ke ACTIVE stavu. Aplikace, které jsou stále ve fázi spouštění, vytvářejí zavádějící výsledky.

Krok 4: Spuštění zátěžových testů

Nastavení ověřování

Vyberte autentizaci podle toho, jak dlouho plánujete spustit:

  • Krátké testy (méně než ~1 hodina): Použijte své stávající přihlašovací údaje uživatele z databricks auth login. Nevyžaduje se žádné další nastavení.
  • Dlouhé testy (více než ~1 hodina, například celonoční běhy): Použijte M2M OAuth se služebním zástupcem. Platnost tokenů U2M vyprší a přeruší testování během jeho spuštění. Vytvoření instančního objektu služby vyžaduje přístup správce pracovního prostoru.

V případě použití M2M OAuth vyexportujte přihlašovací údaje aplikačního objektu před spuštěním testů.

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

Referenční informace k parametrům

Parameter Povinné Default Description
--app-url Yes — Adresy URL aplikací pro testování (opakovatelné)
--client-id Pro dlouhé testy DATABRICKS_CLIENT_ID Env ID klienta service principalu (M2M OAuth)
--client-secret Pro dlouhé testy DATABRICKS_CLIENT_SECRET Env Tajný klíč klienta služebního principálu (M2M OAuth)
--label No Automaticky odvozené z adresy URL Popisek čitelný pro člověka na aplikaci (opakovatelný)
--compute-size No Automaticky rozpoznané nebo medium Značka výpočetní velikosti pro aplikaci: medium, large (opakovatelný)
--max-users No 300 Maximální počet souběžných simulovaných uživatelů
--step-size No 20 Uživatelé přidaní za každý krok rampy
--step-duration No 30 Sekundy na krok rampy
--spawn-rate No 20 Rychlost uživatelských spawnů (uživatelé/s)
--run-name No <timestamp> Název tohoto spuštění – výsledky uložené do load-test-runs/<run-name>/
--dashboard No Off Generování interaktivního řídicího panelu HTML po dokončení testů

Příklady příkazů

Rychlý test jednoaplikace (krátký test – používá vaší databricks auth login relaci):

cd load-test-scripts/

uv run run_load_test.py \
    --app-url https://my-app.aws.databricksapps.com \
    --dashboard --run-name quick-test

Úplná matice pro doporučených 6 konfigurací (dlouhodobý provoz — předání M2M přihlašovacích údajů). Předejte --compute-size příznaky ve stejném pořadí jako --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íce spuštění pro statistickou konzistenci:

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 se stane během běhu

  1. Kontrola stavu: Ověřuje správné fungování datových proudů aplikace (přijímá [DONE]).
  2. Warmup: odesílá sekvenční požadavky, které aplikaci zahřejí.
  3. Ramp až do dosažení nasycení: zvyšuje počet souběžných uživatelů každých step_duration sekund.
  4. Detekce saturace: Když se QPS ustálí, i když přidáváte další uživatele, dosáhli jste limitu propustnosti.

Odhadovaná doba trvání

Každá aplikace pod testem prochází vlastní rampou, takže celková doba běhu se škáluje s počtem konfigurací v matici. Pomocí následujícího vzorce naplánujte okno spuštění.

Doba trvání na aplikaci: (max_users / step_size) * step_duration sekundy.

S výchozími nastaveními (--max-users 300 --step-size 20 --step-duration 30):

  • 15 kroků x 30 sekund = přibližně 7,5 minuty na aplikaci
  • Pro doporučenou 6-konfigurační matici: přibližně 45 minut na běh

Krok 5: Zobrazení a interpretace výsledků

  1. Otevřete řídicí panel:

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

  2. (Volitelné) Znovu vygenerujte řídicí panel z existujících dat, například po aktualizaci šablony:

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

Oddíly řídicího panelu

Interaktivní řídicí panel obsahuje:

  • Karty klíčových ukazatelů výkonu: nejlepší konfigurace (podle vrcholu úspěšných QPS), celková špička QPS, nejnižší latence a celkový počet požadavků, které byly obslouženy.
  • QPS by Config: seskupený pruhový graf zobrazující medián QPS, špičku QPS s vyloučením selhání a špičku QPS vedle sebe pro každou konfiguraci.
  • Latence podle konfigurace: seskupené pruhy zobrazující latenci p50 a p95
  • TTFT podle konfigurace: doba k prvnímu tokenu (p50 a p95).
  • Celkový počet obsluhovaných požadavků: počet požadavků na jednu konfiguraci.
  • Průběh rampy QPS: spojnicové grafy s kartami pro QPS, QPS (s výjimkou selhání), Latence a Selhání. Zahrnuje posuvník pro maximální počet uživatelů, který umožňuje přiblížení na nižší rozsahy souběžnosti. Grafy jsou seskupené podle velikosti výpočetních prostředků (střední a velké vedle sebe).
  • Tabulka úplných výsledků: všechny konfigurace s QPS ve špičce, uživatelé ve špičce, percentily latence a míra selhání.
  • Parametry testu: souhrn konfigurace pro reprodukovatelnost.

Jak interpretovat výsledky

  • Špička QPS: maximální počet QPS dosažený v jakémkoli kroku rampy. Toto je strop propustnosti pro danou konfiguraci.
  • Uživatelé ve špičce: počet souběžných uživatelů při dosažení špičky QPS. Přidání dalších uživatelů mimo tento bod nezvyšuje propustnost.
  • Míra selhání: měla by být 0% nebo velmi nízká. Vysoká míra selhání znamená, že aplikace je na této úrovni souběžnosti přetížená.
  • Graf nájezdu QPS: Vyhledejte místo, kde čára zploštěla. To je bod sytosti: Přidání dalších uživatelů nezvýší propustnost.

Řešení potíží

Problém Řešení
Platnost ověřovacího tokenu vypršela uprostřed testu U testů delších než ~1 hodinu přepněte z U2M na M2M OAuth předáním --client-id a --client-secret
Kontrola zdraví selže Ověřte, že je aplikace aktivní: databricks apps get <name> --output json
0 QPS nebo žádné výsledky Kontrola load-test-runs/<run-name>/<label>/locust_output.log chyb
Nízký počet QPS bez ohledu na vysoký počet uživatelů Aplikace je nasycená. Zkuste použít více pracovních procesů nebo větší výpočetní prostředky.
Vysoká míra selhání Aplikace je přetížená. Snižte nebo zvyšte --max-users počet pracovníků nebo výpočetní kapacitu.
Řídicí panel neobsahuje žádná data rampy. Ověřte, že results_stats_history.csv existuje v každém podadresáři výsledků.

Další zdroje informací

  • Testování pomocí skutečných volání LLM: přeskočte krok napodobování a nasaďte skutečného agenta, abyste změřili kompletní latenci včetně doby odezvy LLM.
  • Ladění počtu pracovních procesů: Pomocí výsledků testovací matice vyhledejte optimální počet pracovních procesů pro vaši velikost výpočetních prostředků.
  • Kurz: Vyhodnocení a vylepšení aplikace GenAI pro měření přesnosti, relevance a bezpečnosti spolu s propustností
  • Připravte svého agenta Databricks Apps pro produkční nasazení v rámci kompletního postupu přípravy na produkční nasazení, včetně AI Gateway.
  • Last updated on