Databricks Appsエージェントの負荷テストを実施します。

負荷テストでは、Databricks Appsエージェントがパフォーマンスを低下させる前に処理できる1秒あたりの最大クエリ数（QPS）を検出します。このページでは、以下の操作方法を説明します。

インフラストラクチャのスループットをLLMの遅延から切り離すために、エージェントのモックバージョンをデプロイしてください。
Locustを使用して、飽和負荷までの段階的負荷テストを実行します。
インタラクティブなダッシュボードで結果を分析します。

Claude Codeのスキルを使ってAIが支援する手順に従うことも、各ステップを手動で設定することもできます。

負荷テストダッシュボードのアニメーションプレビュー。コンピュート構成全体での QPS、レイテンシ、およびランプの進行グラフが表示されます。

要件

Databricks Appsが有効になっているDatabricksワークスペース。
OpenAI Agents SDK、LangGraph、またはカスタムフレームワークを使用してDatabricks Appsにデプロイされた（またはデプロイ準備が整った）エージェントアプリ。AIエージェントを作成してDatabricks Appsにデプロイする方法を参照してください。
Databricks CLIがインストールされ、認証されました。Databricks CLI のインストールまたはアップデートを参照してください。
Python 3.10以降とuvパッケージマネージャーが必要です。
（AI支援パスの場合） Claude Codeがインストールされています。
(~1 時間を超える負荷テストの場合) M2M OAuth資格情報 ( client_idおよびclient_secret ) を持つサービスプリンシパル。「 OAuthを使用したDatabricksへのサービスプリンシパルアクセスの承認」を参照してください。
- 短時間の負荷テスト（約1時間未満）であれば、 databricks auth loginから取得した既存のユーザー（U2M）OAuth認証情報で問題なく動作します。より長いテストの場合は、 Databricksサービスプリンシパルで M2M OAuth使用します。U2M 仮想は、長い実行中に期限切れになり、テスト途中で失敗します。 Databricksサービスプリンシパルを作成するには、ワークスペース管理者アクセスが必要です。

AIによるセットアップ（推奨）

Claude Codeを使用する場合、 /load-testingスキルがワークフローを自動化します。エージェントコードを読み込み、モックを生成し、負荷テストスクリプトを作成し、デプロイメントの手順を案内します。

プロンプト

クロード・コードに頼んでやってもらいましょう。

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

または、以下のステップに従ってください。

ステップ 1: エージェントテンプレートのクローンを作成する

/load-testingスキルは、 databricks/app-templatesリポジトリに、最上位のagent-load-testingスキルとして、また個々のエージェントテンプレートに事前に同期された状態で含まれています。もしあなたが既にapp-templatesプロジェクトに取り組んでいるなら、既にそのスキルは身についているはずです。

リポジトリをクローンし、負荷テストを行うエージェントのテンプレートディレクトリに移動します。

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

ステップ 2: 負荷テストスキルを実行する

Claude Codeで以下を実行します。

Text
/load-testing

このスキルでは、次のステップをインタラクティブに説明します。実際のエージェントをテストする場合は、モックをスキップできます。また、アプリが既に実行されている場合は、デプロイをスキップすることもできます。

収集 : 導入ステータス、コンピュートサイズ、ワーカー構成、およびOAuth認証情報について尋ねます。
負荷テストスクリプトの作成 ：プロジェクトに合わせてlocustfile.py 、 run_load_test.py 、 dashboard_template.pyを生成します。
LLM のモック化 : ご使用の SDK (OpenAI Agents SDK、LangGraph、またはカスタム) に特化したモッククライアントを作成し、実際の LLM 呼び出しを構成可能なストリーミング遅延に置き換えます。
テストアプリのデプロイ : コンピュートサイズとワーカー数が異なる複数のアプリ構成をデプロイする手順を説明します。
テストの実行 ：M2M OAuth認証と飽和状態への段階的負荷増加による負荷テストを実行します。
結果の生成 ：QPS、レイテンシ、および障害メトリクスを含むインタラクティブなHTMLダッシュボードを生成します。

手動設定

AI支援なしで負荷テストをセットアップして実行するには、次のステップに従ってください。

ステップ 1: エージェントのLLM呼び出しをモックする (オプション)

実際のLLMレイテンシーを含むエンドツーエンドの結果が必要な場合は、このステップをスキップしてください。 Databricks Appsのインフラストラクチャのスループットを個別に測定するには、LLMをモックして、リクエストごとのレイテンシ（通常1～30秒）がボトルネックにならないようにします。

モックは、構成可能なストリーミング遅延を備えた定型応答を返し、完全なリクエスト/レスポンスパイプライン (SSE ストリーミング、ツールディスパッチ、 SDKランナー) を保持し、 LLMのみを交換します。これにより、 Databricks Appsプラットフォームが提供できる最大 QPS が明らかになり、負荷テスト中の基盤モデルAPIコストが回避されます。

モックのタイミングは、2つの環境変数によって制御されます。

変数	デフォルト	説明
`MOCK_CHUNK_DELAY_MS`	`10`	ストリームテキストチャンク間の遅延 (ミリ秒単位)
`MOCK_CHUNK_COUNT`	`80`	応答ごとのテキストチャンク数

デフォルト設定では、各模擬応答は約800ミリ秒（10ミリ秒×80チャンク）かかり、実際のLLM応答（3～15秒）よりも大幅に高速です。スループットの数値は、モデルではなくプラットフォームを反映している。

実際のLLMクライアントを置き換えるモッククライアントを作成します。エージェントコードの残りの部分は変更されず、アプローチは使用するSDKによって異なります。OpenAIについては、 databricks/app-templatesのmock_openai_client.pyリファレンス実装を参照してください。同じパターンは他のSDKにも適用できます。

OpenAI Agents SDK
LangGraph
Custom agents

agent_server/mock_openai_client.pyを作成します。これは、ストリーミング機能を備えたchat.completions.create()を実装するMockAsyncOpenAIクラスです。これは、ツール呼び出しチャンクを即座に返し（LLMがツールを呼び出すことを決定したことをシミュレート）、 MOCK_CHUNK_DELAY_MSおよびMOCK_CHUNK_COUNT環境変数から設定可能な遅延でテキスト応答チャンクを返します。

それをエージェントに置き換えます。

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

エージェントコードの残りの部分（ハンドラー、ツール、ストリーミングロジック）は変更されません。

ChatDatabricksモデルを、事前に構築されたAIMessageオブジェクトを返すモックに置き換えてください。

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

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

モックは、最初の呼び出しではツール呼び出しを含むAIMessageオブジェクトを返し、以降の呼び出しではテキストコンテンツを返す必要があり、ストリーミング遅延は設定可能です。

ステップ 2: 負荷テストスクリプトをセットアップする

プロジェクト内にload-test-scripts/ディレクトリを作成してください。負荷テストフレームワークは、フレームワークに依存せず、あらゆるDatabricks Appsエージェントで動作する3つのスクリプトで構成されています。

Text
<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

このフレームワークには以下のファイルが含まれています。

locustfile.py : Locust 負荷テスト。これは、 stream: trueでPOST /invocationsリクエストを送信し、SSE ストリームを解析し、カスタムメトリクスとして最初のトークンまでの時間を追跡し、自動更新を備えた M2M OAuthトークン交換を使用し、各レベルをstep_duration秒間保持しながらユーザーをstep_sizeからmax_usersにランプするStepRampShapeを実装します。
run_load_test.py : 構成ごとに個別のメトリクスを使用して、各アプリの URL を順番にテストする CLI オーケストレーター。OAuthセキュリティの更新、各テストの前のヘルスチェックとウォームアップの実行を処理し、結果をload-test-runs/<run-name>/<label>/に保存します。
dashboard_template.py : Chart.js を使用して、KPI カード、棒グラフ (設定による QPS、レイテンシ、TTFT)、QPS ランプ進行線グラフ、および完全な結果テーブルを含む自己完結型の HTML ダッシュボードを生成します。スタンドアロンで実行可能: uv run dashboard_template.py ../load-test-runs/<run-name>/ 。

依存関係をインストールします

負荷テストスクリプトは、エージェントの本番運用の依存関係を汚染することを避けるために、 load-test-scripts/内で独自のpyproject.tomlを使用します。 load-test-scripts/pyproject.tomlを作成する:

Toml
[project]
name = "load-test-scripts"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
  "locust>=2.32,<2.40",
  "urllib3<2.3",
  "requests",
]

注記

ピン留めlocustから<2.40 。新しいバージョン（ >=2.43 ）には、長時間の負荷テストを壊す既知のRecursionErrorがあります。

load-test-scripts/ディレクトリ内からインストールしてください。

Bash
cd load-test-scripts/
uv sync

ステップ 3: さまざまな構成でテストアプリをデプロイする

異なるコンピュートサイズとワーカー数を持つ複数のDatabricks Appsをデプロイして、ワークロードに最適な構成を見つけます。

推奨テストマトリックス

以下の構成は、以前のテストで特定された最適な設定に焦点を当てています。より広い範囲をカバーしたい場合は、両側に設定を1つずつ追加してください（例： medium-w1またはlarge-w12 ）。ただし、通常は以下の6つで十分です。

コンピュートサイズ	ワーカー	提案されたアプリ名
M	2	`<your-app>-medium-w2`
M	3	`<your-app>-medium-w3`
M	4	`<your-app>-medium-w4`
Large	6	`<your-app>-large-w6`
Large	8	`<your-app>-large-w8`
Large	10	`<your-app>-large-w10`

コンピュートサイズの設定

Databricks CLIを使用して、アプリの作成または更新時にコンピュートサイズを設定します。

Bash
# 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

宣言型自動化バンドルを使用してワーカー数を設定する

start-server （ AgentServer.run()経由）は、 --workersフラグを直接受け入れます。DAB変数を使用して、 command配列内の実行カウントを渡します。

YAML
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'

デプロイと検証

Databricks CLIを使用して各ターゲットをデプロイします。

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

負荷テストを実行する前に、アプリがアクティブであることを確認してください。

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

注記

すべてのアプリがACTIVE状態になるまで待ってから先に進んでください。まだ開発途中のアプリは、誤解を招くような結果を生み出すことがあります。

ステップ 4: 負荷テストの実行

認証を設定する

実行予定時間に応じて認証方法を選択してください。

短時間のテスト（約1時間未満） ： databricks auth loginの既存のユーザー認証情報を使用してください。追加の設定は不要です。
長いテスト (一晩実行など、~1 時間以上) : Databricksサービスプリンシパルで M2M OAuth使用します。 U2M が期限切れになり、実行中にテストが中断されます。 Databricksサービスプリンシパルを作成するには、ワークスペース管理者アクセスが必要です。

M2M OAuthの場合、テストを実行する前にDatabricksサービスプリンシパル資格情報をエクスポートします。

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

論点参照

パラメーター	必須	デフォルト	説明
`--app-url`	はい	—	テスト対象アプリのURL（繰り返し使用可能）
`--client-id`	長時間のテストの場合	`DATABRICKS_CLIENT_ID` 環境	サービスプリンシパルクライアントID（M2M OAuth）
`--client-secret`	長時間のテストの場合	`DATABRICKS_CLIENT_SECRET` 環境	サービスプリンシパルクライアントシークレット（M2M OAuth）
`--label`	No	URLから自動生成	アプリごとに人間が読めるラベル（繰り返し使用可能）
`--compute-size`	No	自動検出または `medium`	アプリごとのコンピュートサイズタグ: `medium` 、 `large` (繰り返し可能)
`--max-users`	No	`300`	最大シミュレーションユーザー
`--step-size`	No	`20`	ランプステップごとにユーザーが追加されます
`--step-duration`	No	`30`	ランプステップあたりの秒数
`--spawn-rate`	No	`20`	ユーザー出現率（ユーザー/秒）
`--run-name`	No	`<timestamp>`	この実行の名前 - 結果は保存先 `load-test-runs/<run-name>/`
`--dashboard`	No	オフ	テスト完了後にインタラクティブなHTMLダッシュボードを生成する

コマンド例

簡単な単一アプリテスト（短時間実行 - あなたのdatabricks auth loginセッションを使用します）：

Bash
cd load-test-scripts/

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

推奨される6つの構成全体にわたる完全なマトリックス（長期実行 - M2M認証情報を渡す）。--compute-sizeフラグを--app-urlと同じ順序で渡す：

Bash
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

統計的な一貫性を確保するために複数回実行：

Bash
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

実行中に何が起こるか

ヘルスチェック ：アプリが正しくストリームしていることを確認します（ [DONE]を受信します）。
ウォームアップ ：アプリをウォームアップするために、連続してリクエストを送信します。
飽和までのランプ : step_duration秒ごとにユーザーをステップアップします。
飽和検出 ：ユーザー数を増やしてもQPS（1秒あたりのクエリ数）が横ばいになった場合、スループットの上限に達したことを意味します。

推定所要時間

テスト対象の各アプリは独自のランプを通じて実行されるため、合計の実行時間はマトリックス内の構成の数に応じて変化します。以下の式を使って、実行時間帯を計画してください。

アプリごとの所要時間： (max_users / step_size) * step_duration秒。

デフォルト値（ --max-users 300 --step-size 20 --step-duration 30 ）の場合：

15 ステップ x 30 秒 = アプリごとに約 7.5 分
推奨される6構成マトリックスの場合：1回の実行につき約45分

ステップ 5: 結果を表示して解釈する

ダッシュボードを開く：

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

（オプション）テンプレートの更新後など、既存のデータからダッシュボードを再生成します。
Bash
```
cd load-test-scripts/
uv run dashboard_template.py ../load-test-runs/<run-name>/
```

ダッシュボードセクション

インタラクティブダッシュボードには以下が含まれます。

KPIカード ：最適な構成（ピーク成功QPS別）、全体のピークQPS、最低レイテンシ、および処理されたリクエストの総数。
構成別QPS ：各構成における中央値QPS、障害発生時を除く最大QPS、および最大QPSを並べて表示するグループ化された棒グラフ。
設定別のレイテンシ ：p50およびp95レイテンシを示すグループ化された棒グラフ。
設定によるTTFT ：最初のトークンまでの時間（p50とp95）。
処理されたリクエスト総数 ：構成ごとのリクエスト数。
QPS ランプ進行状況 ：QPS、QPS（障害を除く）、レイテンシ、および障害のタブが付いた折れ線グラフ。同時接続数の下限範囲にズームインするための最大ユーザー数スライダーが含まれています。チャートはコンピュートサイズごとにグループ化されています (中型と大型が並んでいます)。
結果一覧表 ：ピークQPS、ピーク時のユーザー数、レイテンシのパーセンタイル値、および障害率を含むすべての構成。
テストの問題 : 再現性のための構成の概要。

結果の解釈方法

ピークQPS ：各ランプステップで達成された最大QPS。これは、その構成におけるスループットの上限値です。
ピーク時のユーザー 数：ピークQPSが達成されたときのユーザー数。これ以上ユーザーを追加しても、スループットは向上しません。
故障率 ：0％または非常に低い値であるべきです。高い失敗率は、その同時実行レベルでアプリが過負荷状態にあることを意味します。
QPSランプチャート ：線が平坦になる箇所を探してください。それが飽和点です。ユーザー数を増やしてもスループットは向上しません。

トラブルシューティング

問題	ソリューション
認証トークンがテスト中に期限切れになりました	約 1 時間を超えるテストの場合は、 `--client-id`を渡して U2M から M2M OAuth に切り替えます。 `--client-secret`
ヘルスチェックが失敗しました	アプリがアクティブであることを確認してください。 `databricks apps get <name> --output json`
0 QPSまたは結果なし	エラーがないか`load-test-runs/<run-name>/<label>/locust_output.log`を確認してください。
ユーザー数は多いものの、QPSは低い。	アプリは飽和状態です。より多くのワーカーまたはより大きなコンピュートを試してください。
高い故障率	アプリが過負荷状態です。`--max-users`を減らすか、ワーカー/コンピュートを増やします。
ダッシュボードにはランプデータが表示されません	各結果サブディレクトリに`results_stats_history.csv`が存在することを確認する

次のステップ

実際のLLM呼び出しでテストします : モックをスキップ実際のエージェントをデプロイして、 LLM応答時間を含むエンドツーエンドのレイテンシを測定します。
ワーカー数を調整する : テストマトリックスの結果を使用して、コンピュートサイズに最適なワーカー数を見つけます。
チュートリアル：GenAIアプリケーションを評価・改善し、スループットに加え、精度、関連性、安全性を測定します。

要件​

AIによるセットアップ（推奨）​

ステップ 1: エージェント テンプレートのクローンを作成する​

ステップ 2: 負荷テスト スキルを実行する​

手動設定​

ステップ 1: エージェントのLLM呼び出しをモックする (オプション)​

ステップ 2: 負荷テスト スクリプトをセットアップする​

依存関係をインストールします​

ステップ 3: さまざまな構成でテスト アプリをデプロイする​

推奨テストマトリックス​

コンピュートサイズの設定​

宣言型自動化バンドルを使用してワーカー数を設定する​

デプロイと検証​

ステップ 4: 負荷テストの実行​

認証を設定する​

論点参照​

コマンド例​

実行中に何が起こるか​

推定所要時間​

ステップ 5: 結果を表示して解釈する​

ダッシュボードセクション​

結果の解釈方法​

トラブルシューティング​

次のステップ​

要件