Chargez et testez votre agent Databricks Apps
Les tests de charge déterminent le nombre maximal de requêtes par seconde (QPS) que votre agent Databricks Apps peut prendre en charge avant que les performances ne se dégradent. Cette page vous montre comment effectuer les opérations suivantes :
- Déployez une version fictive de votre agent pour isoler le throughput de l'infrastructure de la latence du LLM.
- Exécutez un test de charge de rampe à saturation avec Locust.
- Analysez les résultats avec un tableau de bord interactif.
Vous pouvez suivre le chemin assisté par l’IA en utilisant une compétence Claude Code, ou configurer chaque étape manuellement.
Exigences
- Un workspace Databricks avec les Databricks Apps activées.
- Une application d’agent déployée (ou prête à être déployée) sur Databricks Apps à l'aide de l’OpenAI Agents SDK, de LangGraph ou d'un framework personnalisé. Consultez Créer un agent IA et le déployer sur Databricks Apps.
- La CLI Databricks est installée et authentifiée. Consultez Installer ou mettre à jour la Databricks CLI.
- Python 3.10+ avec le gestionnaire de
uvpackage. - (Pour le chemin assisté par l'IA) Claude Code installé.
- (Pour les tests de charge de plus d'environ 1 heure) Un Service Principal avec des identifiants OAuth M2M (
client_idetclient_secret). Voir Autoriser l'accès du Service Principal à Databricks avec OAuth.- Pour les tests de charge courts (moins d'~1 heure), vos informations d'identification OAuth utilisateur (U2M) existantes de
databricks auth loginfonctionnent parfaitement. Pour les tests plus longs, utilisez l'OAuth M2M avec un Service Principal Databricks — les jetons U2M expirent lors des exécutions longues et entraînent des échecs en cours de test. La création d'un Service Principal Databricks nécessite un accès administrateur au Workspace.
- Pour les tests de charge courts (moins d'~1 heure), vos informations d'identification OAuth utilisateur (U2M) existantes de
Configuration assistée par l'IA (recommandé)
Si vous utilisez Claude Code, la compétence /load-testing automatise le workflow. Il lit votre code d'agent, génère une maquette, crée des scripts de test de charge et vous accompagne tout au long du déploiement.
Demandez à Claude Code de le faire pour vous :
Clone https://github.com/databricks/app-templates and run the /load-testing skill against the {your-template} template.
Ou suivez les étapes ci-dessous.
Étape 1 : Cloner un template d'agent
La compétence /load-testing est incluse dans le repository databricks/app-templates, à la fois en tant que compétence agent-load-testing de niveau supérieur et pré-synchronisée dans chaque template d'agent individuel. Si vous avez déjà un projet de app-templates, vous avez déjà la compétence.
Clonez le dépôt et accédez au répertoire du Template pour l'agent que vous souhaitez tester en charge :
git clone https://github.com/databricks/app-templates.git
cd app-templates/{your-template}
Étape 2 : Exécutez la compétence de test de charge.
Dans Claude Code, exécuter :
/load-testing
La compétence vous guide de manière interactive à travers les étapes suivantes. Vous pouvez ignorer la simulation pour tester votre véritable agent, ou ignorer le déploiement si vos applications sont déjà en cours d'exécution.
- Collecte des parameter : des questions sur l'état de votre déploiement, les tailles de compute, les configurations de Worker et les identifiants OAuth vous sont posées.
- Création de scripts de test de charge : génère
locustfile.py,run_load_test.pyetdashboard_template.pyadaptés à votre projet. - Maquettage de votre LLM : crée un client simulé spécifique à votre SDK (SDK d'agents OpenAI, LangGraph ou personnalisé) qui remplace les appels réels de LLM par des délais de streaming configurables.
- Déploiement d'applications de test : vous guide dans le déploiement de plusieurs configurations d'applications avec différentes tailles de compute et différents nombres de Workers.
- Exécution des tests : exécute le test de charge avec l'authentification OAuth M2M et la rampe jusqu'à saturation.
- Génération des résultats : produit un tableau de bord HTML interactif avec des métriques de QPS, de latence et d'échec.
Configuration manuelle
Suivez ces étapes pour configurer et exécuter des tests de charge sans assistance IA.
Étape 1 : Simulez les appels LLM de votre agent (facultatif)
Ignorez cette étape si vous souhaitez des résultats de bout en bout incluant une latence LLM réelle. Pour mesurer le throughput de l'infrastructure Databricks Apps de manière isolée, simulez le LLM afin que sa latence par requête (généralement de 1 à 30 secondes) ne devienne pas le goulot d'étranglement.
Une simulation renvoie des réponses prédéfinies avec un délai de streaming configurable, en préservant le pipeline complet de requête/réponse (streaming SSE, distribution d'outils, exécuteur SDK) et en remplaçant uniquement le LLM. Ceci révèle le QPS maximal que la plateforme Databricks Apps peut fournir et évite les coûts de jetons de l'API du modèle de fondation pendant les tests de charge.
Le timing simulé est contrôlé par deux variables d'environnement :
Variable | Par défaut | Description |
|---|---|---|
|
| Délai en millisecondes entre les blocs de texte Stream |
|
| Nombre de segments de texte par réponse |
Avec les valeurs par défaut, chaque réponse simulée prend environ 800 ms (10 ms x 80 fragments), ce qui est considérablement plus rapide qu’une réponse LLM réelle (3 à 15 secondes). Les chiffres de throughput reflètent alors la plateforme, et non le modèle.
Créez un client factice qui remplace le véritable client LLM. Le reste de votre code d'agent reste inchangé, et l'approche dépend de votre SDK. Pour OpenAI, consultez l'implémentation de référencemock_openai_client.py dans databricks/app-templates. Le même modèle s'adapte à d'autres SDK.
- OpenAI Agents SDK
- LangGraph
- Custom agents
Créez agent_server/mock_openai_client.py — une classe MockAsyncOpenAI qui implémente chat.completions.create() avec streaming. Il renvoie instantanément des morceaux d'appel d'outil (simulant la décision du LLM d'appeler un outil) et des morceaux de réponse textuelle avec un délai configurable à partir des variables d'environnement MOCK_CHUNK_DELAY_MS et MOCK_CHUNK_COUNT.
Insérez-le dans votre 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")
Le reste de votre code d'agent (gestionnaires, outils, logique de streaming) reste inchangé.
Remplacez le modèle ChatDatabricks par une maquette qui renvoie des objets AIMessage prédéfinis :
# Before:
# model = ChatDatabricks(endpoint="databricks-claude-sonnet-4")
# After:
from agent_server.mock_llm import MockChatModel
model = MockChatModel()
Le mock doit retourner AIMessage objets avec des appels d’outil lors de la première invocation et du contenu textuel lors des invocations suivantes, avec des délais de streaming configurables.
Enveloppez tous les appels d’API externes effectués par votre agent (LLM, AI Search, APIs d'outils) avec des implémentations simulées qui renvoient des formes de réponse réalistes avec des délais configurables.
Étape 2 : Configurez les scripts de test de charge.
Créez un répertoire load-test-scripts/ dans votre projet. Le framework de test de charge se compose de trois scripts indépendants du framework et fonctionnant avec n'importe quel agent 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
Le framework comprend les fichiers suivants :
locustfile.py: un test de charge Locust qui envoiePOST /invocationsrequêtes avecstream: true, analyse les SSE Stream, suit le temps jusqu'au premier jeton (TTFT) en tant que métrique personnalisée, utilise l'échange de jetons OAuth M2M avec auto-refresh, et implémente unStepRampShapequi fait monter en charge les utilisateurs destep_sizeàmax_userstout en maintenant chaque niveau pendantstep_durationsecondes.run_load_test.py: un orchestrateur CLI qui teste chaque URL d'application séquentiellement avec des métriques isolées par configuration. Il gère le token OAuth refresh, exécute un bilan de santé et un préchauffage avant chaque test, et enregistre les résultats dansload-test-runs/<run-name>/<label>/.dashboard_template.py: Génère un tableau de bord HTML autonome à l'aide de Chart.js avec des cartes de KPI, des graphiques à barres (QPS, latence, TTFT par configuration), des graphiques linéaires de progression de la rampe QPS et un tableau de résultats complet. Peut être exécuté de manière autonome :uv run dashboard_template.py ../load-test-runs/<run-name>/.
Installer les dépendances
Les scripts de test de charge utilisent leurs propres pyproject.toml à l'intérieur de load-test-scripts/ pour éviter de polluer les dépendances de production de votre agent. Créer 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 à <2.40. Les versions plus récentes (>=2.43) ont un problème connu RecursionError qui interrompt les tests de charge longs.
Installez à partir du répertoire load-test-scripts/ :
cd load-test-scripts/
uv sync
Étape 3 : déployer des applications de test avec des configurations variées
Déployez plusieurs Databricks Apps avec différentes tailles de compute et un nombre de worker pour trouver la configuration optimale pour votre workload.
Matrice de test recommandée.
Les configurations ci-dessous se concentrent sur le juste milieu identifié lors de tests antérieurs. Si vous souhaitez une couverture plus large, ajoutez une configuration de chaque côté (par exemple, medium-w1 ou large-w12), mais les six ci-dessous sont généralement suffisantes.
Taille de compute | Workers | Nom d'application suggéré |
|---|---|---|
Medium | 2 |
|
Medium | 3 |
|
Medium | 4 |
|
Large | 6 |
|
Large | 8 |
|
Large | 10 |
|
Configurer la taille du compute
Utilisez le CLI Databricks pour définir la taille du compute lors de la création ou de la mise à jour d'une application :
# 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
Configurer le nombre de Worker avec Declarative Automation Bundles
start-server (via AgentServer.run()) accepte directement un indicateur --workers. Transmettez le nombre de Worker dans le tableau command à l'aide d'une variable 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'
Déployer et vérifier
Déployez chaque cible avec la CLI Databricks :
databricks bundle deploy --target medium-w2
databricks bundle run load_test_app --target medium-w2
Vérifiez que les applications sont actives avant d'exécuter des tests de charge :
databricks apps get <app-name> --output json | jq '{app_status, compute_status, url}'
Veuillez attendre que toutes les applications atteignent le statut ACTIVE avant de poursuivre. Les applications qui sont encore en cours de démarrage produisent des résultats trompeurs.
Étape 4 : Lancez les tests de charge.
Configurer l'authentification
Sélectionnez votre authentification en fonction de la durée d'exécution prévue :
- Tests courts (moins de ~1 heure) : utilisez vos identifiants utilisateur existants de
databricks auth login. Aucune configuration supplémentaire requise. - Tests longs (plus d'environ 1 heure, comme les exécutions de nuit) : utilisez l'OAuth M2M avec un Service Principal Databricks. Les jetons U2M expirent et interrompent votre test en cours d'exécution. La création d'un Service Principal Databricks nécessite un accès administrateur au Workspace.
Pour l’OAuth M2M, exportez les informations d’identification du Service Principal Databricks avant d’exécuter les tests :
export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_CLIENT_ID=<your-client-id>
export DATABRICKS_CLIENT_SECRET=<your-client-secret>
Référence des paramètres
parameter | Obligatoire | Par défaut | Description |
|---|---|---|---|
| Oui | — | URL(s) d'application à tester (répétable) |
| Pour les tests longs |
| ID client du Service Principal (OAuth M2M) |
| Pour les tests longs |
| Secret client du Service Principal (OAuth M2M) |
| Non | Dérivé automatiquement de l'URL | Étiquette lisible par l'homme par application (répétable) |
| Non | Détection automatique ou | Balise de taille de compute par application : |
| Non |
| Nombre maximal d'utilisateurs simultanés simulés |
| Non |
| Utilisateurs ajoutés par étape de montée en charge |
| Non |
| Secondes par étape de rampe |
| Non |
| Taux d'apparition d'utilisateurs (utilisateurs/sec) |
| Non |
| Nom de cette exécution — résultats enregistrés dans |
| Non | Désactivé | Générer un tableau de bord HTML interactif une fois les tests terminés. |
Exemples de commandes
Test rapide d'une seule application (exécution courte — utilise votre session 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
Matrice complète sur les 6 configurations recommandées (exécution longue — passage des identifiants M2M). Transmettez --compute-size indicateurs dans le même ordre 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
Plusieurs exécutions pour la cohérence statistique :
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
Que se passe-t-il pendant une exécution
- Healthcheck : vérifie que l'application Stream correctement (reçoit
[DONE]). - **Mise en route** : envoie des requêtes séquentielles pour préparer l’application.
- **Montée en charge jusqu'à saturation** : augmente le nombre d'utilisateurs simultanés toutes les
step_durationsecondes. - Détection de saturation : lorsque le QPS plafonne malgré l'ajout d'utilisateurs supplémentaires, vous avez atteint le plafond de throughput.
Durée estimée
Chaque application testée s'exécute selon sa propre rampe, de sorte que la durée d'exécution totale évolue en fonction du nombre de configurations de votre matrice. Utilisez la formule ci-dessous pour planifier votre fenêtre d'exécution.
Durée par application : (max_users / step_size) * step_duration secondes.
Avec les default (--max-users 300 --step-size 20 --step-duration 30) :
- 15 étapes x 30 secondes = environ 7,5 minutes par application
- Pour la matrice recommandée à 6 configurations : environ 45 minutes par exécution
Étape 5 : Afficher et interpréter les résultats
-
Ouvrez le tableau de bord :
Bashopen load-test-runs/<run-name>/dashboard.html -
(Facultatif) Régénérez le tableau de bord à partir de données existantes, par exemple après la mise à jour du Template :
Bashcd load-test-scripts/
uv run dashboard_template.py ../load-test-runs/<run-name>/
Sections du tableau de bord
Le tableau de bord interactif comprend :
- Cartes d’indicateurs clés de performance : meilleure configuration (par QPS de pointe réussis), QPS de pointe global, latence la plus faible et nombre total de requêtes servies.
- QPS par configuration : graphique à barres groupées montrant le QPS médian, le QPS de pointe excluant les échecs et le QPS de pointe côte à côte pour chaque configuration.
- Latence par configuration : barres groupées affichant la latence p50 et p95.
- TTFT par configuration : délai avant le premier jeton (p50 et p95).
- Total des requêtes traitées : nombre de requêtes par configuration.
- Progression de la rampe QPS : graphiques linéaires avec tab pour QPS, QPS (hors échecs), Latence et Échecs. Comprend un curseur d'utilisateurs max. pour zoomer sur des plages de concurrence inférieures. Les graphiques sont regroupés par taille de compute (moyen et grand, côte à côte).
- Tableau des résultats complets : toutes les configurations avec le QPS de pointe, les utilisateurs au pic, les percentiles de latence et le taux d'échec.
- Paramètres de test : récapitulatif de la configuration pour la reproductibilité.
Comment interpréter les résultats
- QPS de pointe : le QPS maximal atteint à chaque étape de montée en charge. C'est le plafond de throughput pour cette configuration.
- **Utilisateurs au pic** : le nombre d'utilisateurs simultanés lorsque le pic de QPS a été atteint. Ajouter plus d'utilisateurs au-delà de ce point n'augmente pas le throughput.
- Taux d'échec : devrait être de 0 % ou très faible. Un taux d'échec élevé signifie que l'application est surchargée à ce niveau de concurrence.
- QPS Ramp Chart : recherchez l'endroit où la ligne s'aplatit. C'est le point de saturation : l'ajout de nouveaux utilisateurs n'augmentera pas le throughput.
Exécution de référence de benchmark sur des données synthétiques
Cette section rapporte ce qu'un benchmark interne de Databricks a mesuré par rapport à une application d'agent synthétique, où chaque appel LLM était simulé. Il s'agit d'un exercice distinct des tests de charge de votre propre agent : utilisez-le pour voir la forme des résultats que vous pouvez attendre et pour obtenir un point de départ approximatif pour le dimensionnement.
Ce que cette exécution a montré
- Point de départ recommandé : 2 Worker sur compute Moyen, ou 8 Worker sur Grand.
- Un nombre plus élevé de Worker n'est pas toujours mieux. Sur Medium, 2 Workers (155,1 QPS) dépassent 4 Workers (116,5 QPS) d'environ 33 %. La charge de travail simulée est limitée par le processeur, donc au-delà de 2 Worker, vous rencontrez un conflit CPU/mémoire qui annule le parallélisme supplémentaire. Un véritable agent lié aux E/S qui attend principalement un Endpoint de modèle peut évoluer davantage que cette simulation, alors assurez-vous de tester votre propre agent.
- Taille du compute : Large a fourni environ 2,2 fois le throughput de Medium (278,0 contre 123,5 de QPS de pointe moyenne).
- Latence : Grande a tourné à environ 20 % de moins que Moyenne (environ 906 ms contre 1 180 ms p50), avec un TTFT d'environ 1 100 ms sur Grande contre 1 720-1 820 ms sur Moyenne.
- Fiabilité : le taux de défaillance est resté à ou près de 0 % pour chaque configuration, même avec 1 000 utilisateurs simultanés.
Parce que le LLM était simulé (streaming simulé avec des délais fixes par segment), il s’agit de chiffres de throughput d’infrastructure plutôt que de chiffres d’agent de bout en bout. Ils mesurent le nombre de requêtes que le FastAPI AgentServer de Databricks Apps peut traiter en parallèle, et non la latence d'un modèle réel. Un agent de production qui appelle un endpoint LLM en direct observe un QPS plus faible et une latence plus élevée, dominée par le temps de réponse du modèle. Vos propres chiffres varient selon la complexité de l’agent, la taille de la charge utile, les appels d’outil, la région et l’Endpoint de modèle que vous appelez. Pour un dimensionnement précis, effectuez un test de charge sur votre propre agent.
Les résultats tabulés ci-dessous montrent la ventilation complète par configuration.
Conditions de test
- Exécution de référence : 5 tours identiques contre 8 configurations d'application (4 de compute moyen, 4 de compute grand), chacun avec un nombre de workers uvicorn différent.
- Montée en charge : 20 à 1 000 utilisateurs concurrents, par paliers de 20 utilisateurs maintenus pendant 10 secondes chacun (50 paliers par configuration).
- **Agent fictif** : réponses en streaming d'environ 95 segments par requête, simulant le streaming de jetons LLM.
- **Volume** : environ 1,46 million de requêtes totales sur toutes les exécutions.
QPS de pointe par configuration
Le débit maximal (QPS) est moyenné sur les 5 exécutions.
Taille de compute | Workers | QPS de pointe moyenne | Plage de pic | Taux d'échec |
|---|---|---|---|---|
Medium | 2 | 155,1 | 137,0 - 166,6 | 0,0 % |
Medium | 4 | 116,5 | de 112,6 à 121,8 | 0,1 % |
Medium | 6 | 111,9 | 102,6-117,5 | 0,0 % |
Medium | 8 | 110,3 | 108,3-112,1 | 0,0 % |
Large | 6 | 281,6 | De 268,2 à 292,4 | 0,0 % |
Large | 8 | 268,2 | de 265,8 à 271,0 | 0,0 % |
Large | 10 | 288,1 | 280,3 - 299,4 | 0,0 % |
Large | 12 | 274,2 | de 269,4 à 278,8 | 0,0 % |
Moyenne par taille de compute :
Taille de compute | QPS de pointe moyenne | QPS moyenne |
|---|---|---|
Medium | 123,5 | 45,5 |
Large | 278,0 | 100,1 |
Lors de cette exécution, le grand compute a fourni environ 2,2 fois le throughput du compute moyen.
Dépannage
Problème | Solutions |
|---|---|
Jeton d'authentification expiré en plein test | Pour les tests de plus d'environ 1 heure, passez d'OAuth U2M à M2M en transmettant |
Échec du contrôle de santé | Vérifiez que l'application est ACTIVE : |
0 QPS ou aucun résultat | Vérifiez |
QPS faible malgré un nombre élevé d'utilisateurs | L'application est saturée. Essayez plus de Worker ou un compute plus important. |
Taux de défaillance élevé | L'application est surchargée. Réduisez |
Le tableau de bord n’affiche aucune donnée ramp | Vérifiez que |
Ressources supplémentaires
- Testez avec de véritables appels LLM : ignorez l'étape de simulation et déployez votre agent réel pour mesurer la latence de bout en bout, y compris le temps de réponse du LLM.
- Optimiser le nombre de worker : utilisez les résultats de la matrice de test pour trouver le nombre optimal de worker pour votre taille de compute.
- Tutoriel : Évaluer et améliorer une application GenAI pour mesurer la précision, la pertinence et la sécurité ainsi que le throughput.
- Mettez votre agent Databricks Apps en production pour la séquence complète de préparation à la production, y compris AI Gateway.