Testez la charge de votre agent Databricks Apps
Les tests de charge déterminent le nombre maximal de queries 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 simulée de votre agent pour isoler le throughput de l'infrastructure de la latence du LLM.
- Exécutez un test de charge de montée en charge jusqu'à 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 Databricks Apps activé.
- Une application d'agent déployée (ou prête à être déployée) sur Databricks Apps à l'aide du SDK OpenAI Agents, de LangGraph ou d'un framework personnalisé. Consultez Créer un agent d'IA et le déployer sur Databricks Apps.
- La CLI de Databricks est installée et authentifiée. Consultez Installer ou mettre à jour la CLI Databricks.
- Python 3.10+ avec le gestionnaire de packages
uv. - (Pour le chemin assisté par l'IA) Claude Code installé.
- (Pour les tests de charge d'une durée supérieure à environ 1 heure) Un Service Principal avec des informations d'identification OAuth M2M (
client_idetclient_secret). Consultez Autoriser l'accès du Service Principal à Databricks avec OAuth.- Pour les tests de charge courts (moins d'environ une heure), vos identifiants OAuth utilisateur (U2M) existants de
databricks auth loginfonctionnent correctement. Pour des tests plus longs, utilisez l'OAuth M2M avec un Service Principal Databricks — les jetons U2M expirent lors des exécutions longues et provoquent des échecs en milieu 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'environ une heure), vos identifiants OAuth utilisateur (U2M) existants de
Configuration assistée par l’IA (recommandée)
Si vous utilisez Claude Code, la compétence /load-testing automatise le workflow. Il lit le code de votre agent, génère une simulation, crée des scripts de test de charge et vous guide 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écuter la compétence de test de charge
Dans Claude Code, exécutez :
/load-testing
La compétence vous guide de manière interactive à travers les étapes suivantes. Vous pouvez ignorer la simulation pour tester votre agent réel, ou ignorer le déploiement si vos applications sont déjà en cours d'exécution.
- Collecte des parameters : pose des questions sur votre statut de déploiement, les tailles de compute, les configurations de worker et les identifiants OAuth.
- Création de scripts de test de charge : génère
locustfile.py,run_load_test.pyetdashboard_template.pyadaptés à votre projet. - Simulation de votre LLM : crée un client simulé spécifique à votre SDK (SDK OpenAI Agents, LangGraph ou personnalisé) qui remplace les appels LLM réels par des délais de streaming configurables.
- Déploiement d’applications de test : vous guide à travers le déploiement de plusieurs configurations d’applications avec différentes tailles de compute et nombre de Worker.
- Exécution des tests : exécute le test de charge avec l'authentification M2M OAuth et une montée en puissance 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 : Simuler les appels LLM de votre agent (facultatif)
Ignorez cette étape si vous souhaitez obtenir des résultats de bout en bout qui incluent la latence réelle du LLM. 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 1 à 30 secondes) ne devienne pas le goulot d'étranglement.
Une maquette renvoie des réponses prédéfinies avec un délai de streaming configurable, préservant l'intégralité du pipeline de requête/réponse (streaming SSE, dispatch d'outils, exécuteur SDK) et remplaçant uniquement le LLM. Ceci affiche le QPS maximal que la plateforme Databricks Apps peut fournir et évite les coûts de jetons d'API de modèle de fondation pendant les tests de charge.
La simulation du timing est contrôlée 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 paramètres par défaut, chaque réponse simulée prend environ 800 ms (10 ms x 80 segments), nettement plus rapide qu'une véritable réponse de LLM (3 à 15 secondes). Les chiffres du 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 segments d'appel d'outil (simulant la décision du LLM d'appeler un outil) et des segments de réponse textuelle avec un délai configurable à partir des variables d'environnement MOCK_CHUNK_DELAY_MS et MOCK_CHUNK_COUNT.
Échangez-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 du code de votre 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 devrait 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.
Encapsulez tous les appels d'API externes effectués par votre agent (LLM, AI Search, APIs d'outils) avec des implémentations de maquette 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 qui sont agnostiques au framework et fonctionnent avec tout 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 cadre comprend les fichiers suivants :
locustfile.py: Un test de charge Locust qui envoiePOST /invocationsrequêtes avecstream: true, analyse des Stream SSE, suit le temps jusqu'au premier jeton (TTFT) en tant que métrique personnalisée, utilise l'échange de jetons M2M OAuth avec auto-refresh, et met en œuvre unStepRampShapequi fait monter en puissance 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 refresh du jeton OAuth, exécute un contrôle 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 utilisant Chart.js avec des cartes KPI, des graphiques à barres (QPS, latence, TTFT par configuration), des graphiques linéaires de progression de la rampe QPS et un tableau complet des résultats. 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 leur propre pyproject.toml à l'intérieur de load-test-scripts/ afin d'éviter de polluer les dépendances de production de votre agent. Créez 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) présentent un RecursionError connu qui interrompt les tests de charge longs.
Installer à 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 nombres de worker afin de trouver la configuration optimale pour votre charge de travail.
Matrice de test recommandée
Les configurations ci-dessous se concentrent sur le point idéal identifié lors des tests précédents. 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 de l’application suggéré |
|---|---|---|
Medium | 2 |
|
Medium | 3 |
|
Medium | 4 |
|
Large | 6 |
|
Large | 8 |
|
Large | 10 |
|
Configurer la taille de compute
Utilisez le Databricks CLI 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
Configurez le nombre de Worker avec les 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 l'état ACTIVE avant de poursuivre. Les applications qui sont encore en cours de démarrage produisent des résultats trompeurs.
Étape 4 : Exécuter 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 d'environ 1 heure) : utilisez vos identifiants utilisateur existants de
databricks auth login. Aucune configuration supplémentaire requise. - Tests longs (plus d'une heure environ, comme les exécutions nocturnes) : utilisez M2M OAuth 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 requiert un accès administrateur au Workspace.
Pour l'OAuth M2M, exportez les identifiants 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 de paramètres
parameter | Obligatoire | Par défaut | Description |
|---|---|---|---|
| Oui | — | URL(s) de l'application à tester (répétable) |
| Pour les tests longs |
| ID client du service principal (OAuth M2M) |
| Pour les tests longs |
| Secret client de Service principal (M2M OAuth) |
| Non | Dérivé automatiquement de l'URL | Étiquette lisible par l'homme par application (répétable) |
| Non | Détecté automatiquement ou | Balise de taille de compute par application : |
| Non |
| Nombre maximal d'utilisateurs simulés simultanés |
| Non |
| Utilisateurs ajoutés par étape de montée en charge |
| Non |
| Secondes par étape de rampe |
| Non |
| Taux d’apparition des utilisateurs (utilisateurs/s) |
| 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'application unique (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 pour les 6 configurations recommandées (exécution longue — transfert des identifiants M2M). Passez --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
- Vérification de l'état de santé : vérifie que l'application Stream correctement (reçoit
[DONE]). - **Démarrage** : envoie des requêtes séquentielles pour démarrer l'application.
- Montée en charge jusqu'à saturation : augmente les utilisateurs simultanés toutes les
step_durationsecondes. - Détection de saturation : lorsque le QPS atteint un plateau 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 montée en charge, de sorte que le temps d’exécution total monte en charge avec le nombre de configurations dans 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 default (--max-users 300 --step-size 20 --step-duration 30) :
- 15 étapes x 30 secondes = environ 7,5 minutes par application
- Pour la matrice de 6 configurations recommandée : environ 45 minutes par exécution.
Étape 5 : afficher et interpréter les résultats
-
Ouvrir 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 pic de requêtes par seconde réussies), pic global de requêtes par seconde, latence la plus faible et nombre total de requêtes traitées.
- QPS par configuration : histogramme groupé affichant le QPS médian, le QPS de pointe hors é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 : temps avant le premier jeton (p50 et p95).
- Nombre total de requêtes servies : nombre de requêtes par configuration.
- Progression de la rampe QPS : graphiques linéaires avec tab pour QPS, QPS (hors défaillances), latence et défaillances. Inclut un curseur de nombre maximal d'utilisateurs pour zoomer sur des plages de simultanéité inférieures. Les graphiques sont regroupés par taille de compute (moyenne et grande côte à côte).
- Tableau des résultats complets : toutes les configurations avec QPS maximal, utilisateurs au maximum, percentiles de latence et taux d'échec.
- Paramètres de test : résumé de configuration pour la reproductibilité.
Comment interpréter les résultats
- **QPS maximal** : le QPS maximal atteint à chaque étape de la rampe. 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. L'ajout d'utilisateurs au-delà de ce point n'augmente pas le throughput.
- Taux de défaillance : devrait être de 0 % ou très faible. Un taux de défaillance élevé signifie que l'application est surchargée à ce niveau de simultanéité.
- **Graphique de rampe QPS** : recherchez l'endroit où la ligne s'aplatit. C'est le point de saturation : l'ajout d'utilisateurs supplémentaires n'augmentera pas le throughput.
Exécution de référence de benchmark sur des données synthétiques
Cette section présente les résultats d'une exécution de benchmark Databricks interne mesurée par rapport à une application d'agent synthétique, où chaque appel LLM était simulé. C'est un exercice distinct des tests de charge de votre propre agent : utilisez-le pour voir le type de 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 compute.
- Plus de Workers n'est pas toujours mieux. Sur Medium, 2 Workers (155,1 QPS) battent 4 Workers (116,5 QPS) d'environ 33 %. La charge de travail simulée est limitée par le CPU, donc au-delà de 2 Workers, vous rencontrez des conflits CPU/mémoire qui annulent le parallélisme supplémentaire. Un véritable agent lié aux E/S qui attend principalement un Endpoint de modèle peut monter en charge davantage que cette simulation, alors assurez-vous de tester votre propre agent.
- Taille de calcul : Le grand format a fourni environ 2,2x le throughput du format Moyen (278,0 vs 123,5 QPS de pointe moyen).
- Latence : Grande était inférieure de ~20 % à Moyenne (~906 ms contre 1 180 ms p50), avec un TTFT de ~1 100 ms sur Grande contre 1 720 à 1 820 ms sur Moyenne.
- Fiabilité : le taux de défaillance est resté à 0 % ou près de 0 % pour chaque configuration, même avec 1 000 utilisateurs simultanés.
Puisque le LLM a été simulé (le streaming étant simulé avec des délais fixes par bloc), ce sont des chiffres de throughput d'infrastructure plutôt que des 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 constate un QPS plus faible et une latence plus élevée, dominés par le temps de réponse du modèle. Vos propres chiffres varient en fonction de la complexité de l'agent, de la taille de la charge utile, des appels d'outils, de la région et de l'Endpoint de modèle que vous appelez. Pour un dimensionnement précis, exécutez un test de charge sur votre propre agent.
Les résultats tabulés ci-dessous présentent la ventilation complète par configuration.
Conditions de test
- Exécution de référence : 5 manches identiques pour 8 configurations d'applications (4 de taille moyenne, 4 de taille importante compute), chacune avec un nombre de worker uvicorn différent.
- Rampe : 20 à 1 000 utilisateurs simultanés, par étapes de 20 utilisateurs maintenues pendant 10 secondes chacune (50 étapes par configuration).
- Agent simulé : réponses en streaming d'environ 95 fragments par requête, simulant le streaming de jetons LLM.
- Volume : environ 1,46 million de demandes totales sur toutes les exécutions.
QPS maximale par configuration
Le QPS de pointe est moyenné sur les 5 exécutions.
Taille de compute | Workers | QPS moyen maximal | Plage maximale | Taux d’échec |
|---|---|---|---|---|
Medium | 2 | 155,1 | 137,0 à 166,6 | 0,0 % |
Medium | 4 | 116,5 | 112,6-121,8 | 0,1 % |
Medium | 6 | 111,9 | 102,6 à 117,5 | 0,0 % |
Medium | 8 | 110,3 | de 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 | de 280,3 à 299,4 | 0,0 % |
Large | 12 | 274,2 | de 269,4 à 278,8 | 0,0 % |
Moyenné par taille de compute :
Taille de compute | QPS moyen maximal | QPS moyenne |
|---|---|---|
Medium | 123,5 | 45,5 |
Large | 278,0 | 100,1 |
Dans cette exécution, le grand compute a fourni environ 2,2 fois le throughput du compute moyen.
Dépannage
Problème | Solutions |
|---|---|
Le jeton d'authentification a expiré en plein test. | Pour les tests de plus de ~1 heure, passez d’OAuth U2M à M2M en transmettant |
La vérification de l'état de santé échoue | 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 Workers ou un compute plus grand. |
Taux d'échec élevé | L'application est surchargée. Réduire |
Le tableau de bord n'affiche aucune donnée de progression | Vérifiez que |
Ressources supplémentaires
- **Tester avec de véritables appels LLM** : ignorer l'étape de simulation et déployer votre agent réel pour mesurer la latence de bout en bout, y compris le temps de réponse du LLM.
- Ajuster le nombre de worker : utilisez les résultats de la matrice de test pour trouver le nombre optimal de worker pour la taille de votre compute.
- Didacticiel : évaluer et améliorer une application GenAI pour mesurer la précision, la pertinence et la sécurité ainsi que le throughput.
- Mettez en production votre agent Databricks Apps pour la séquence complète de préparation à la production, y compris la Passerelle AI.