メインコンテンツまでスキップ

クエリ ルートの最適化サービング エンドポイント

この記事では、ルート最適化 モデルサービング エンドポイントをクエリできるように、適切な認証資格情報とURLを取得する方法について説明します。

必要条件​

  • ルート最適化が有効になっているモデルサービングエンドポイントについては、「 サービスエンドポイントでのルート最適化」を参照してください。
  • 認証トークン。ルート最適化エンドポイントは OAuth トークンのみをサポートし、パーソナル アクセス トークンはサポートされていません。

ルート最適化URLを取得する​

ルート最適化エンドポイントを作成すると、エンドポイントに対して一意のルート最適化 URL が作成されます。ルート最適化エンドポイントは、専用 URL を使用してのみクエリを実行できます。URL の形式は次のとおりです。

https://<unique-id>.serving.gcp.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

この URL は、次のいずれかから取得できます。

  • GET /api/2.0/serving-endpoints/{name} API 呼び出しを使用する。URL は、エンドポイントの応答オブジェクトに endpoint_urlとして存在します。このフィールドは、エンドポイントがルート最適化されている場合にのみ入力されます。

  • Serving UI の Serving エンドポイントの詳細ページ。

ルート最適化エンドポイント URL

OAuth トークンをフェッチし、エンドポイントをクエリする​

ルート最適化エンドポイントをクエリするには、OAuth トークンを使用する必要があります。Databricks 本番運用アプリケーションでサービスプリンシパルを使用して、プログラムで OAuth トークンを取得することをお勧めします。 次のセクションでは、テストおよび本番運用シナリオで OAuth トークンをフェッチする方法に関する推奨ガイダンスについて説明します。

Serving UI を使用した OAuth トークンの取得​

次の手順は、Serving UI でトークンをフェッチする方法を示しています。これらの手順は、エンドポイントの開発とテストに推奨されます。

本番運用で使用する場合、たとえば、アプリケーションでルート最適化エンドポイントを使用する場合、トークンはサービスプリンシパルを使用してフェッチされます。 OAuthOAuth本番運用のユースケースで トークンをフェッチするための推奨ガイダンスについては、「 トークンをプログラムでフェッチ する」を参照してください。

ワークスペースの Serving UI から:

  1. [配信エンドポイント] ページで、ルート最適化エンドポイントを選択してエンドポイントの詳細を表示します。
  2. エンドポイントの詳細ページで、 [使用 ] ボタンを選択します。
  3. [トークンの取得 ] タブを選択します。
  4. OAuth トークンの取得 ボタンを選択します。このトークンは1時間有効です。 現在のトークンの有効期限が切れた場合は、新しいトークンをフェッチします。

OAuth トークンをフェッチしたら、エンドポイント URL と OAuth トークンを使用してエンドポイントをクエリします。

次に、REST API の例を示します。

Bash

URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

プログラムで OAuth トークンをフェッチする​

本番運用のシナリオでは、 Databricks は、プログラムによってトークンをフェッチするために、アプリケーション内に埋め込むようにサービスプリンシパルを設定する OAuth 推奨します。 これらのフェッチされたトークンは、ルート最適化エンドポイントのクエリに使用されます。

サービス プリンシパルの Databricks へのアクセスを OAuth の認証の手順 2 の手順に従って、サービスプリンシパルを作成し、アクセス許可を割り当て、サービスプリンシパルの OAuth シークレットを作成します。 サービスプリンシパルを作成したら、サービスプリンシパルにエンドポイントに対する 少なくともクエリ権限 を付与する必要があります。 「 モデルサービング エンドポイントの権限を管理する」を参照してください。

Databricks Python SDK には、ルート最適化エンドポイントを直接クエリするための API が用意されています。

注記

Databricks SDK は Go でも使用できます ( 「Databricks SDK for Go」を参照)。

この例では、Databricks SDK を使用してルート最適化エンドポイントをクエリするには、次のものが必要です。

  • 配信エンドポイント名 (SDK はこの名前に基づいて正しいエンドポイント URL をフェッチします)
  • サービスプリンシパルのクライアントID
  • サービスプリンシパルのシークレット
  • ワークスペースのホスト名

次に、クエリの例を示します。

Python
from databricks.sdk import WorkspaceClient
import databricks.sdk.core as client

endpoint_name = "<Serving-Endpoint-Name>" ## Insert the endpoint name here

# Initialize Databricks SDK
c = client.Config(
    host="<Workspace-Host>", ## For example, my-workspace.cloud.databricks.com
    client_id="<Client-Id>", ## Service principal ID
    client_secret="<Secret>"   ## Service principal secret
)
w = WorkspaceClient(
    config = c
)

response = w.serving_endpoints_data_plane.query(endpoint_name, dataframe_records = ....)

OAuth トークンを手動で取得する​

Databricks SDK または Serving UI を使用して OAuth トークンをフェッチできないシナリオでは、OAuth トークンを手動でフェッチできます。このセクションのガイダンスは、主に、ユーザーが本番運用でエンドポイントのクエリに使用するカスタマイズされたクライアントを持っているシナリオに適用されます。

OAuth トークンを手動で取得する場合は、要求で authorization_details を指定する必要があります。

  • <token-endpoint-URL>を作成するには、https://<databricks-instance> を Databricks デプロイのワークスペース URL に置き換えます https://<databricks-instance>/oidc/v1/token。例えば https://my-workspace.gcp.databricks.com/oidc/v1/token

  • <client-id> をサービスプリンシパルのクライアント ID (アプリケーション ID とも呼ばれます) に置き換えます。

  • <client-secret> を、作成したサービスプリンシパルの OAuth シークレットに置き換えます。

  • <endpoint-id> をルート最適化エンドポイントのエンドポイント ID に置き換えます。これは、エンドポイント URL の hostName にあるエンドポイントの英数字の ID です。たとえば、サービス エンドポイントが https://abcdefg.serving.gcp.databricks.com/9999999/serving-endpoints/testの場合、エンドポイント ID は abcdefgです。

  • <action> を、サービスプリンシパルに付与されたアクション権限に置き換えます。アクションは query_inference_endpoint または manage_inference_endpointにすることができます。

次に、REST API の例を示します。

Bash


export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>
export ENDPOINT_ID=<endpoint-id>
export ACTION=<action>  # for example, 'query_inference_endpoint'

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'
--data-urlencode 'authorization_details=[{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"'"/serving-endpoints/$ENDPOINT_ID"'","actions": ["'"$ACTION"'"]}]'

OAuth トークンをフェッチしたら、エンドポイント URL と OAuth トークンを使用してエンドポイントをクエリします。

次に、REST API の例を示します。

Bash

URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

に最終更新