Uw Databricks Apps-agent laden

Met belastingstests worden de maximale query's per seconde (QPS) gevonden die uw Databricks Apps-agent kan ondersteunen voordat de prestaties afnemen. Op deze pagina ziet u hoe u het volgende kunt doen:

1. Implementeer een mockversie van uw agent om de doorvoer van de infrastructuur te isoleren van LLM-latentie.
2. Voer een ramp-to-saturation load test uit met Locust.
3. Analyseer resultaten met een interactief dashboard.

U kunt het door AI ondersteunde pad volgen met behulp van een Claude Code-vaardigheid of elke stap handmatig instellen.

Vereisten

• Een Azure Databricks werkruimte met Databricks-apps ingeschakeld.
• Een agent-app die is geïmplementeerd (of gereed voor implementatie) in Databricks-apps met behulp van de OpenAI Agents SDK, LangGraph of een aangepast framework. Zie Een AI-agent ontwerpen en implementeren in Databricks-apps.
• De Databricks CLI is geïnstalleerd en geverifieerd. Zie De Databricks CLI installeren of bijwerken.
• Python 3.10+ met uv package manager.
• (Voor het door AI ondersteunde pad) Claude Code geïnstalleerd.
• (Voor belastingstests langer dan ~1 uur) Een service-principal met M2M OAuth-referenties (client_id en client_secret). Zie Autorisatie van toegang voor de service-principal tot Azure Databricks met OAuth.
  • Voor korte belastingstests (minder dan ~1 uur) werken uw bestaande OAuth-referenties databricks auth login (U2M) prima. Voor langere tests gebruikt u M2M OAuth met een service-principal, omdat U2M-tokens tijdens lange uitvoeringen verlopen, wat fouten tijdens de test veroorzaakt. Voor het maken van een service-principal is beheerderstoegang tot de werkruimte vereist.

Door AI ondersteunde installatie (aanbevolen)

Als u Claude Code gebruikt, automatiseert de /load-testing vaardigheid de werkstroom. De code leest uw agentcode, genereert een mock, maakt scripts voor belastingtests en begeleidt u bij de implementatie.

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

Stap 1: Een agentsjabloon klonen

De /load-testing vaardigheid is opgenomen in de opslagplaats databricks/app-templates , zowel als de vaardigheid op het hoogste niveau agent-load-testing en vooraf gesynchroniseerd in elke afzonderlijke agentsjabloon. Als u al een project van app-templates hebt, dan bezit u de vaardigheid al.

Kloon de repository en navigeer naar de sjabloonmap voor de agent die u wilt loadtesten:

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

Stap 2: De belastingtestvaardigheid uitvoeren

Voer in Claude Code het volgende uit:

/load-testing

De vaardigheid begeleidt u interactief door de volgende stappen. U kunt mocking overslaan om uw echte agent te testen of implementatie overslaan als uw apps al worden uitgevoerd.

1. Parameters verzamelen: vraagt om uw implementatiestatus, rekengrootten, werkrolconfiguraties en OAuth-referenties.
2. Scripts voor belastingstests maken: genereert locustfile.py, run_load_test.pyen dashboard_template.py is afgestemd op uw project.
3. Mocking van uw LLM: maakt een mock-client die specifiek is voor uw SDK (OpenAI Agents SDK, LangGraph of aangepast). Deze vervangt echte LLM-aanroepen door configureerbare streamingvertragingen.
4. Test-apps implementeren: begeleidt u bij het implementeren van meerdere app-configuraties met verschillende rekengrootten en werkrollen.
5. Tests uitvoeren: voert de loadtest uit met M2M OAuth-verificatie en opbouw naar verzadiging.
6. Resultaten genereren: produceert een interactief HTML-dashboard met metrische gegevens over QPS, latentie en fouten.

Handmatige installatie

Volg deze stappen om belastingstests in te stellen en uit te voeren zonder AI-hulp.

Stap 1: De LLM-aanroepen van uw agent mocken (optioneel)

Sla deze stap over als je end-to-end resultaten wilt die de werkelijke latentie van LLM bevatten. Als u de doorvoer van de databricks-apps-infrastructuur geïsoleerd wilt meten, moet u de LLM simuleerden zodat de latentie per aanvraag (meestal 1-30 seconden) niet het knelpunt wordt.

Een mock retourneert reacties met een configureerbare streamingvertraging, waarbij de volledige aanvraag-/antwoordpijplijn (SSE-streaming, verzenden van hulpprogramma's, SDK-runner) behouden blijft en waarbij alleen de LLM wordt verwisseld. Hiermee wordt de maximale QPS die het Databricks Apps-platform kan leveren zichtbaar gemaakt en worden de kosten van Foundation Model API-tokens tijdens belastingstests vermeden.

De timing van de mock wordt beheerd door twee omgevingsvariabelen:

Met de standaardwaarden duurt elk mock-antwoord ongeveer 800 ms (10 ms x 80 chunks), aanzienlijk sneller dan een echt LLM-antwoord (3-15 seconden). Doorvoernummers weerspiegelen vervolgens het platform, niet het model.

Maak een mockclient die de echte LLM-client vervangt. De rest van uw agentcode blijft ongewijzigd en de benadering is afhankelijk van uw SDK. Zie voor OpenAI de mock_openai_client.py referentie-implementatie in databricks/app-templates. Hetzelfde patroon past zich aan andere SDK's aan.

OpenAI Agents SDK

agent_server/mock_openai_client.py Maak een MockAsyncOpenAI-klasse die chat.completions.create() implementeert met streaming. Het retourneert direct segmenten voor het aanroepen van hulpprogramma's (simuleren van de LLM die besluit een hulpprogramma aan te roepen) en segmenten voor tekstreacties met configureerbare vertraging van MOCK_CHUNK_DELAY_MS en MOCK_CHUNK_COUNT omgevingsvariabelen.

Wissel deze in uw agent:

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

De rest van uw agentcode (handlers, hulpprogramma's, streaminglogica) blijft ongewijzigd.

LangGraph

Vervang het ChatDatabricks model door een mock die vooraf gemaakte AIMessage objecten retourneert:

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

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

De mock moet AIMessage objecten retourneren met hulpprogramma-aanroepen bij de eerste aanroep en tekstinhoud bij volgende aanroepen, met vertragingen die configureerbaar zijn voor streaming.

Op maat gemaakte agenten

Omhul welke externe API-aanroepen uw agent ook doet (LLM, vectorzoekopdracht, tool-API's) met mock-implementaties die realistische reactiestructuren retourneren met aanpasbare vertragingen.

Stap 2: Scripts voor loadtests opzetten

Maak een load-test-scripts/ map in uw project. Het framework voor belastingtests bestaat uit drie scripts die frameworkneutraal zijn en werken met een Databricks Apps-agent.

<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

Het framework bevat de volgende bestanden:

• locustfile.py: Een locust-belastingstest die POST /invocations aanvragen verzendt, SSE-streams stream: true parseert, de tijd bijhoudt tot het eerste token (TTFT) als aangepaste metriek, M2M OAuth-tokenuitwisseling met automatische vernieuwing gebruikt, en een StepRampShape implementeert dat gebruikers van step_size naar max_users opschaalt, waarbij elk niveau step_duration seconden wordt aangehouden.
• run_load_test.py: Een CLI-orchestrator die elke app-URL opeenvolgend test met geïsoleerde metrische gegevens per configuratie. Het verwerkt het vernieuwen van OAuth-token, voert een statuscontrole en warmup uit voor elke test en slaat resultaten op load-test-runs/<run-name>/<label>/.
• dashboard_template.py: Genereert een zelfstandig HTML-dashboard met behulp van Chart.js met KPI-kaarten, staafdiagrammen (QPS, latentie, TTFT per config), QPS-voortgangslijndiagrammen en een volledige resultatentabel. Kan zelfstandig worden uitgevoerd: uv run dashboard_template.py ../load-test-runs/<run-name>/.

Afhankelijkheden installeren

De scripts voor belastingtests gebruiken hun eigen pyproject.toml binnen load-test-scripts/ om de productieafhankelijkheden van uw agent niet te vervuilen. Maken 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",
]

Installeren vanuit de load-test-scripts/ map:

cd load-test-scripts/
uv sync

Stap 3: Test-apps met verschillende configuraties implementeren

Implementeer meerdere Databricks-apps met verschillende rekengrootten en werkrollen om de optimale configuratie voor uw workload te vinden.

Aanbevolen testmatrix

De onderstaande configuraties richten zich op de sweet spot die is geïdentificeerd uit eerdere tests. Als u een bredere dekking wilt, voegt u aan beide zijden één configuratie toe (bijvoorbeeld medium-w1 of large-w12), maar de zes hieronder zijn meestal voldoende.

Rekenkracht configureren

Gebruik de Databricks CLI om de rekengrootte in te stellen bij het maken of bijwerken van een app:

# 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

Aantal werknemers configureren met declaratieve Automationbundels

start-server (via AgentServer.run()) accepteert rechtstreeks een --workers vlag. Geef het aantal werknemers in de command array door met behulp van een DAB-variabele.

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'

Implementeren en verifiëren

Implementeer elk doel met de Databricks CLI:

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

Controleer of apps actief zijn voordat u belastingstests uitvoert:

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

Stap 4: Uitvoeren van belastingproeven

Authenticatie instellen

Selecteer uw verificatie op basis van hoe lang u van plan bent om uit te voeren:

• Korte tests (minder dan ~1 uur): gebruik uw bestaande gebruikersreferenties van databricks auth login. Er is geen extra installatie vereist.
• Lange tests (langer dan ongeveer 1 uur, zoals 's nachts uitvoeren): gebruik M2M OAuth met een service principal. U2M-tokens verlopen en onderbreken uw test halverwege de uitvoering. Voor het maken van een serviceprincipal is beheerderstoegang tot de werkruimte vereist.

Voor M2M OAuth moet u de referenties van de service-principal exporteren voordat u de tests uitvoert.

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

Parametersreferentie

Voorbeeldopdrachten

Snelle test met één app (korte uitvoering: maakt gebruik van uw databricks auth login sessie):

cd load-test-scripts/

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

Volledige matrix in de aanbevolen 6 configuraties (lange uitvoering: M2M-referenties doorgeven). Geef vlaggen door --compute-size in dezelfde volgorde als --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

Meerdere uitvoeringen voor statistische consistentie:

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

Wat gebeurt er tijdens een uitvoeringsproces?

1. Gezondheidscontrole: controleert of de app correct streamt (ontvangt gegevens).[DONE]
2. Opwarmen: verzendt sequentiële aanvragen om de app op te warmen.
3. Ramp-to-verzadiging: verhoogt het aantal gelijktijdige gebruikers elke step_duration seconden.
4. nl-NL: Verzadigingsdetectie: wanneer het QPS een plateau bereikt ondanks de toevoeging van meer gebruikers, is het doorvoermaximum bereikt.

Geschatte duur

Elke app die wordt getest, wordt uitgevoerd via een eigen ramp, dus de totale uitvoeringstijd wordt geschaald met het aantal configuraties in uw matrix. Gebruik de onderstaande formule om het uitvoeringsvenster te plannen.

Duur per app: (max_users / step_size) * step_duration seconden.

Met standaardinstellingen (--max-users 300 --step-size 20 --step-duration 30):

• 15 stappen x 30 seconden = ongeveer 7,5 minuten per app
• Voor de aanbevolen 6-configuratiematrix: ongeveer 45 minuten per uitvoering

Stap 5: Resultaten weergeven en interpreteren

1. Open het dashboard:

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

2. (Optioneel) Genereer het dashboard opnieuw op basis van bestaande gegevens, bijvoorbeeld na het bijwerken van de sjabloon:

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

Dashboard secties

Het interactieve dashboard bevat:

• KPI-kaarten: beste configuratie (op basis van de hoogste geslaagde QPS), totale piek QPS, laagste latentie en totale aanvragen die worden afgeleverd.
• QPS per Config: gegroepeerd staafdiagram met mediaan QPS, piek QPS met uitzondering van fouten en piek QPS naast elkaar voor elke configuratie.
• Latentie per configuratie: gegroepeerde balken met p50- en p95-latentie.
• TTFT by Config: time to first token (p50 en p95).
• Totaal aantal verzonden aanvragen: aantal aanvragen per configuratie.
• Voortgang van QPS-ramp: lijndiagrammen met tabbladen voor QPS, QPS (met uitzondering van fouten), latentie en fouten. Bevat een schuifregelaar voor maximale gebruikers om in te zoomen op lagere gelijktigheidsniveaus. Grafieken worden gegroepeerd op rekengrootte (gemiddeld en groot naast elkaar).
• Volledige resultatentabel: alle configuraties met piek-QPS, gebruikers met piek, latentie percentielen en foutpercentage.
• Testparameters: configuratieoverzicht voor reproduceerbaarheid.

Resultaten interpreteren

• Piek QPS: het maximale QPS dat is bereikt bij een hellingsstap. Dit is het doorvoermaximum voor die configuratie.
• Gebruikers bij Piek: het aantal gelijktijdige gebruikers wanneer piek in QPS is bereikt. Als u meer gebruikers toevoegt dan dit punt, wordt de doorvoer niet verhoogd.
• Foutpercentage: moet 0% of zeer laag zijn. Een hoge foutsnelheid betekent dat de app overbelast is op dat gelijktijdigheidsniveau.
• QPS-rampdiagram: zoek waar de lijn afvlakt. Dat is het verzadigingspunt: het toevoegen van meer gebruikers verhoogt de doorvoer niet.

Troubleshooting

Volgende stappen 

• Test met echte LLM-aanroepen: sla de mockingstap over en implementeer uw werkelijke agent om de end-to-end latentie te meten, inclusief de LLM-reactietijd.
• Aantal werkrollen afstemmen: gebruik de resultaten van de testmatrix om het optimale aantal werkrollen voor uw rekenkracht te vinden.
• Zelfstudie: Een GenAI-toepassing evalueren en verbeteren om de nauwkeurigheid, relevantie en veiligheid naast doorvoer te meten.