高い QPS を使用して AI Search エンドポイントのスループットをスケーリングする

既定では、標準エンドポイントでは、インデックスサイズに応じて 20 ~ 200 QPS がサポートされます。検索バー、レコメンデーションシステム、エンティティ照合などのリアルタイムアプリケーションには、多くの場合、100 ~ 1000 以上の QPS が必要です。標準エンドポイントでのみ、ターゲット QPS を設定できます。 Databricks は、そのスループットレベルに最も一致するようにインフラストラクチャをプロビジョニングします (ベストエフォート、保証されません)。

Important

ターゲット QPS を設定すると、追加の容量がプロビジョニングされるため、エンドポイントのコストが増加します。実際のクエリトラフィックに関係なく、この追加容量に対して課金されます。スループットのスケーリングはベストエフォートであり、保証されるものではありません。

次の場合は、高い QPS を使用します。

アプリケーションには、50 QPS を超える持続的スループットが必要です。
通常の負荷で 429 (要求が多すぎます) エラーが発生します。
平均使用率が低い場合でも、トラフィックが増加すると待機時間が低下します。

必要条件

High QPS は、標準エンドポイントでのみ使用できます。ストレージ最適化エンドポイントはサポートされていません。
高 QPS 運用ワークロードには、サービスプリンシパルの OAuth 認証とインデックス URL を使用します。個人用アクセストークン (AT) とワークスペースクエリ URL はプロトタイプ作成に適していますが、最適化されたクエリルートを使用せず、数十個の QPS に制限されます。
テキストクエリにマネージド埋め込みモデルを使用する差分同期インデックスの場合、ワークスペースで IP アクセスリストやプライベート接続 (Azure Private Link など) を使用している場合、最適化されたクエリルートは使用できません。その構成では、エンドポイントが構成済みのターゲット QPS に到達しない可能性があります。

ターゲット QPS の構成

新しいエンドポイントを作成するとき、または既存のエンドポイントを更新するときに、ターゲット QPS を設定します。ターゲットスループットに最も一致するために必要な追加の容量が自動的にプロビジョニングされます。スループットのスケーリングはベストエフォートであり、保証されません。実際の QPS は、インデックスサイズ、ベクター次元、クエリの複雑さ、フィルターの使用に依存します。

Databricks ユーザーインターフェース

新しいエンドポイントを作成する場合:

左側のサイドバーで、[ コンピューティング] をクリックします。
[ AI Search ] タブをクリックし、[ エンドポイントの作成] をクリックします。
[ 詳細設定] で、[ ターゲット QPS ] の値を入力します。

既存のエンドポイントを更新する場合:

エンドポイントの詳細ページに移動します。
右側のパネルで、鉛筆アイコンのをクリックします。 [ターゲット QPS] の横にあります。
新しい値を入力し、[保存] をクリック します。

Python SDK

from databricks.ai_search.client import AISearchClient

client = AISearchClient()

# Create a new endpoint with target QPS
endpoint = client.create_endpoint(
    name="my-high-qps-endpoint",
    endpoint_type="STANDARD",
    target_qps=500,
)

# Update an existing endpoint's target QPS
response = client.update_endpoint(name="my-endpoint", target_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"Requested target QPS: {scaling_info.get('requested_target_qps')}")
print(f"State: {scaling_info.get('state')}")
# State is "SCALING_CHANGE_IN_PROGRESS" while capacity is being provisioned,
# then transitions to "SCALING_CHANGE_APPLIED"

REST API

ターゲット QPS を使用してエンドポイントを作成します。

POST /api/2.0/vector-search/endpoints
{
  "name": "my-high-qps-endpoint",
  "endpoint_type": "STANDARD",
  "target_qps": 500
}

既存のエンドポイントでターゲット QPS を更新します。

PATCH /api/2.0/vector-search/endpoints/<ENDPOINT_NAME>
{
  "target_qps": 500
}

スケーリングの状態を確認します。

GET /api/2.0/vector-search/endpoints/<ENDPOINT_NAME>

応答 scaling_info フィールドには、 requested_target_qps とスケーリングの stateが表示されます。容量のプロビジョニング中に状態が SCALING_CHANGE_IN_PROGRESS され、 SCALING_CHANGE_APPLIEDに遷移します。

インデックス URL のクエリを実行する

エンドポイントのスケーリング状態が SCALING_CHANGE_APPLIEDされたら、サービスプリンシパル OAuth トークンを使用してインデックス URL にクエリを送信します。この URL は、 target_qpsによってプロビジョニングされた追加のクエリ容量を使用するために必要です。

Python アプリケーションの場合は、get_index()を 1 回呼び出し、返されたインデックスオブジェクトを再利用します。 Python SDK は、インデックス URL にクエリを送信します。

from databricks.ai_search.client import AISearchClient

client = AISearchClient(
    service_principal_client_id="...",
    service_principal_client_secret="...",
    workspace_url="https://<workspace-url>",
)

index = client.get_index(endpoint_name="my-high-qps-endpoint", index_name="catalog.schema.index")

# Reuse this index object for every query.
index.similarity_search(query_vector=[...], columns=["id", "text"], num_results=10)

REST またはPython以外のアプリケーションの場合は、最初にインデックス URL を取得してから、その URL にクエリ要求を送信します。トークンは、サービスプリンシパルの OAuth トークンである必要があります。

export WORKSPACE_URL=https://<workspace-url>
export INDEX_NAME=catalog.schema.index
export TOKEN=<oauth-token>

export INDEX_URL=$(curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "$WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME" \
  | jq -r '.status.index_url')

case "$INDEX_URL" in
  http://*|https://*) ;;
  *) INDEX_URL="https://$INDEX_URL" ;;
esac

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$INDEX_URL/query" \
  --data '{"num_results": 10, "query_vector": [...], "columns": ["id", "text"]}'

QPS 運用トラフィックが多い場合は、ワークスペースクエリ URL ( /api/2.0/vector-search/indexes/<index_name>/query など) を使用しないでください。この URL は最適化されたクエリルートを使用せず、エンドポイントが構成されたターゲット QPS に到達する前に 429 エラーを返す可能性があります。

スケーリングの適用方法

ターゲット QPS を設定すると、必要な容量が自動的にプロビジョニングされます。新しいスループットレベルは、プロビジョニングが完了した後に適用されます。変更をトリガーするためにインデックスを同期する必要はありません。

注

スケーリング操作の進行中にターゲット QPS を更新しようとすると、 RESOURCE_CONFLICT エラーが返されます。再試行する前に、現在の操作が完了するまで待ちます。

429 エラーのトラブルシューティング

QPS が多いワークロードの場合は、次のチェックを使用してボトルネックを見つけます。

PAT またはワークスペースクエリ URL を使用する場合は、サービスプリンシパルの OAuth 認証とインデックス URL に切り替えます。
scaling_info.stateがSCALING_CHANGE_IN_PROGRESS場合は、状態がSCALING_CHANGE_APPLIEDに変わるまで待ちます。
アプリケーションが query_vectorを使用してベクタークエリを送信する場合、埋め込みモデルはクエリパスにありません。スケーリングが完了した後も 429 エラーが続く場合は、要求のコンカレンシーを減らすか、より高い target_qpsを設定します。
アプリケーションが Databricks で管理される埋め込みモデルを使用して差分同期インデックスにテキストクエリを送信する場合、埋め込みモデルがボトルネックになる可能性があります。 databricks-qwen3-embedding-0-6bではなく、databricks-gte-large-enなどの小規模な埋め込みモデルを使用するか、プロビジョニングされたスループット基盤モデル API エンドポイントまたは埋め込み用の別の専用モデルサービスエンドポイントを使用します。

制限事項

自動スケールなし: 予想されるトラフィックに基づいてターゲット QPS を手動で設定する必要があります。トラフィックがプロビジョニングされたレベルを超えると、429 エラーが発生します。クエリスパイクへの対応策を参照してください。
標準エンドポイントのみ: ストレージ最適化エンドポイントは、 target_qpsをサポートしていません。
最適化されたルートが必要: 構成されたターゲット QPS は、サービスプリンシパルの OAuth 認証とインデックス URL を使用するトラフィックに適用されます。 PAT トラフィックとワークスペースクエリ URL トラフィックは、数十個の QPS で制限されます。
マネージド埋め込みモデルでは、2 つ目の制限を追加できます。テキストクエリにマネージド埋め込みモデルを使用する差分同期インデックスの場合、クエリのスループットも埋め込みモデルサービスエンドポイントに依存します。モデルのサービス容量を増やすか、プロビジョニングされたスループットを使用するか、予測可能なクエリスループットにセルフマネージド埋め込みを使用します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-17