メインコンテンツまでスキップ
に最終更新

高 QPS で AI Search エンドポイントのスループットをスケーリングする

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

重要

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

高QPSを使用するのは、次のような場合です：

  • お客様のアプリケーションには、50 QPSを超える持続的なスループットが必要です。
  • 通常の負荷時に429 (リクエストが多すぎます) エラーが発生します。
  • トラフィックが増加すると、平均利用率が低く見える場合でも、レイテンシは低下します。

要件​

  • High QPSは標準エンドポイントでのみ利用可能です。ストレージ最適化エンドポイントはサポートされていません。

  • 高QPSの本番運用ワークロードには、サービスプリンシパルのOAuth認証とインデックスURLを使用します。個人アクセストークン (PAT) とワークスペースクエリURLはプロトタイピングには適していますが、最適化されたクエリ経路を使用せず、数十QPSに制限されています。

  • ワークスペースにプライベートアクセス設定オブジェクトがアタッチされている場合、インデックスの種類やオブジェクトの設定に関係なく、ワークスペース内のどのインデックスも最適化されたクエリールートを使用できません。

    • フロントエンド接続またはバックエンド接続に Private Service Connect を使用するワークスペースには、プライベートアクセス設定オブジェクトがあります。
    • この構成では、クエリーはワークスペースクエリーURLを使用しますが、これは数十QPSに制限されているため、Endpointはそれより高い目標QPSに達することができません。
    • QPSが高いワークロードでは、プライベートアクセス設定オブジェクトがアタッチされていないワークスペースを使用します。別のワークスペースを使用できない場合は、Databricksアカウントチームにお問い合わせください。

  • 管理された埋め込みモデルを使用するDelta Syncインデックスは、ワークスペースでIPアクセスリスト機能が有効になっている場合、最適化されたクエリールートを使用できません。

    • その構成では、インデックスへのクエリーはワークスペースのクエリーURLを使用しますが、これは数十QPSに制限されているため、Endpointはそれ以上のターゲットQPSに達することができません。これは、query_vectorを通過するクエリーを含め、インデックスに対するすべてのクエリーに適用されます。
    • プライベートアクセス設定オブジェクトがないワークスペースでは、セルフマネージド型埋め込みを使用してターゲットQPSに到達します。これには、埋め込みベクトル列を持つDelta Syncインデックス、またはDirect Vector Accessインデックスを使用します。埋め込みを提供するためのオプションを参照してください。

ターゲットQPSを設定する​

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

新しいエンドポイントを作成する際：

  1. 左側のサイドバーで、 コンピュート をクリックします。

  2. 「**AI Search**」タブをクリックし、「**エンドポイントを作成**」をクリックします。

    AI Searchコンピュートを作成します。

  3. 「高度な設定」で、ターゲットQPS値を入力してください。

    「AI Searchエンドポイントの作成」ダイアログを作成します。

既存のエンドポイントを更新する際：

  1. エンドポイントの詳細ページに移動してください。

  2. 右側のパネルで、鉛筆アイコン。 「ターゲットQPS」 の横にある鉛筆アイコン をクリックします。

    ターゲットQPSを編集してください。

  3. 新しい値を入力し、「 保存 」をクリックします。

    ターゲットQPS値を入力してください。

Service Principalの設定​

高QPSクエリーには、インデックスに対してauthorization_detailsを持つOAuthトークン、またはアップサートと削除のが必要です。本番運用にはService Principalを使用します。Service Principalを設定するには：

  1. Service Principalを追加し、インデックスを含むワークスペースに割り当てます。

  2. Service Principal用のOAuthシークレットを作成します：

    • OAuthシークレットを作成のステップに従ってください。
    • スコープ で すべての APIs を選択します。Python SDKは all-apis スコープをリクエストし、トークンはそのシークレットのスコープを超えることができないため、より狭いスコープに制限されたシークレットは SDK のトークンを取得できません。REST の例でも all-apis がリクエストされます。このスコープはシークレットを広範にするため、このページで権限のみを持つ専用のService Principalを使用します。
    • クライアントIDとシークレットをアプリケーションコードに含めるのではなく、Secret Scopeに保存してください。

  3. Service Principalに以下のUnity Catalog権限を付与します。

    • インデックスを含むカタログに対するUSE CATALOG権限。
    • インデックスを含むスキーマに対する USE SCHEMA 権限。
    • インデックスに対するSELECT権限。
    • Service PrincipalがDirect Vector Accessインデックスでデータをアップサートまたは削除する場合、インデックスに対するSELECTおよびMODIFY権限。

    Service Principalがインデックスを所有している場合、SELECTまたはMODIFYは不要ですが、USE CATALOGとUSE SCHEMAは依然として必要です。

  4. Databricks管理の埋め込みモデルを使用するインデックスの場合、埋め込みモデルサービングEndpointと、インデックスにmodel_endpoint_name_for_queryが設定されている場合はそのEndpointにも権限を付与します。必要な権限はEndpointのタイプによって異なります。

    • トークン単位の従量課金 基盤モデル APIs エンドポイント （databricks-gte-large-enなど）: アカウントがUnity Catalog権限で基盤モデルを制限している場合を除き、権限の付与は不要です。その場合は、モデルにEXECUTE権限を付与してください。
    • プロビジョニング済み throughput とカスタムサービング Endpoint ： query_text でクエリーを実行するには クエリー可能 を付与します。query_vector でクエリーを実行して Python SDK を使用する場合でも、少なくとも 表示可能 を付与してください。get_index() はこれらのサービング エンドポイントを読み取るため、権限がないと失敗します。

インデックスのクエリには、AI Search Endpoint自体に対する権限は必要ありません。

Service Principalは、OAuthマシン間(M2M)認証で認証します。OAuthトークンには、インデックスに対してReadVectorIndexを許可するauthorization_details、またはアップサートと削除のWriteVectorIndexが含まれている必要があります。

埋め込みモデルサービングEndpointまたはmodel_endpoint_name_for_queryEndpointがルート最適化されている場合、トークンにはそれぞれquery_inference_endpointを許可するworkspace_permissionエントリも必要です。サービングEndpointがルート最適化されているかどうかを確認するには、GET /api/2.0/serving-endpoints/<name>によって返されるroute_optimizedフィールドを参照してください。

  • Python SDK : インデックスURLのクエリーに示すように、クライアントIDとシークレットをAISearchClientに渡します。SDKは、必要なauthorization_detailsを持つトークンを要求し、サービングEndpointエントリを自動的に追加します。ルート最適化されたmodel_endpoint_name_for_queryEndpointの場合、databricks-ai-search 0.79以上が必要です。
  • REST API : トークンを自分でリクエストしてください。「AI Searchインデックスをクエリする方法」のREST API tabにあるService Principalの例を参照してください。

テストには、ノートブックトークン交換で取得したトークンを使用することもできます。本番運用にはService Principalを使用します。

注記

権限の変更は、新しく発行されたトークンにのみ適用されます。権限を取り消しても、すでに発行されたトークンは無効になりません。そのトークンは、有効期限が切れるまで有効です。有効期限は最大1時間です。Python SDKを使用して、特権または埋め込みEndpointの設定を変更した後、get_index()を再度呼び出します。REST呼び出し元は、新しいトークンをリクエストする必要があります。

クエリーインデックスURL​

Endpointのスケーリング状態が SCALING_CHANGE_APPLIED になったら、Service Principalトークンなど、インデックスに authorization_details を指定したOAuthトークンを使用してインデックスURLにクエリーを送信します。このURLは、target_qpsによってプロビジョニングされた追加のクエリー処理能力を使用するために必要です。

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

Python
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 にクエリーリクエストを送信します。トークンは、インデックスに authorization_details を持つ OAuth トークンである必要があります。本番運用にはService Principalを使用してください。

sh
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の本番運用トラフィックには、/api/2.0/vector-search/indexes/<index_name>/queryのようなワークスペースクエリURLを使用しないでください。そのURLは最適化されたクエリ経路を使用していないため、エンドポイントが設定されたターゲットQPSに達する前に429エラーを返す可能性があります。

スケーリングの適用方法​

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

注記

スケーリング操作の進行中にターゲットQPSの更新を試行すると、RESOURCE_CONFLICTエラーが返されます。現在の操作が完了するのを待ってから、再試行してください。

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

高いQPSワークロードの場合、ボトルネックを見つけるには、以下のチェックを使用してください。

  • PATまたはワークスペースクエリーURLを使用している場合は、Service Principal OAuth 認証およびインデックスURLに切り替えてください。
  • scaling_info.state が SCALING_CHANGE_IN_PROGRESS である場合、状態が SCALING_CHANGE_APPLIED に変更されるまでお待ちください。
  • アプリケーションがquery_vectorでベクタークエリを送信する場合、埋め込みモデルはクエリパスにありません。スケーリングが完了しても429エラーが続く場合、リクエストの同時実行を減らすか、より高いtarget_qpsを設定してください。
  • アプリケーションがDatabricksマネージド埋め込みモデルを持つDelta Syncインデックスにテキストクエリを送信する場合、埋め込みモデルがボトルネックになる可能性があります。の代わりに のようなより小さい埋め込みモデルを使用するか、databricks-qwen3-embedding-0-6b databricks-gte-large-enプロビジョニングされたスループットの基盤モデルAPIエンドポイント または埋め込み用の別の専用Model Servingエンドポイントを使用してください。

制限事項：​

  • オートスケールなし：予測されるトラフィックに基づいて、ターゲットQPSを手動で設定する必要があります。トラフィックがプロビジョニングされたレベルを超過した場合、429エラーが発生します。「クエリ スパイクの計画」を参照してください。
  • 標準エンドポイントに限り：ストレージ最適化エンドポイントはtarget_qps をサポートしていません。
  • 最適化されたルートが必要です : 構成されたターゲットQPSは、サービスプリンシパルOAuth認証とインデックスURLを使用するトラフィックに適用されます。PATトラフィックとワークスペースのクエリURLトラフィックは、数十QPSに制限されています。
  • マネージド埋め込みモデルは 2 番目の制限を追加する場合があります : テキストクエリーにマネージド埋め込みモデルを使用する Delta Sync インデックスの場合、クエリースループットは、埋め込みモデルサービングエンドポイントにも依存します。モデルサービング容量を増やし、プロビジョニング済みスループットを使用するか、または自己管理の埋め込みを使用することで、予測可能なクエリースループットを実現できます。
このページの見出し