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

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

必要条件

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

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

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

https://<unique-id>.serving.cloud.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 から:

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

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

REST API
Python

次に、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"

次に Python の例を示します。

Python

import requests
import json

url = "<url>"
oauth_token = "<token>"

data = {
    "dataframe_split": {
        "columns": ["feature_1", "feature_2"],
        "data": [
            [0.12, 0.34],
            [0.56, 0.78],
            [0.90, 0.11]
        ]
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {oauth_token}"
}

response = requests.post(url, headers=headers, json=data)

# Print the response
print("Status Code:", response.status_code)
print("Response Body:", response.text)

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

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

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

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 を指定する必要があります。

https://<databricks-instance> を Databricks デプロイのワークスペース URL に置き換えて、<token-endpoint-URL>を構築します。たとえば、 https://<databricks-instance>/oidc/v1/token.
<client-id> をサービスプリンシパルのクライアント ID (アプリケーション ID とも呼ばれます) に置き換えます。
<client-secret> を、作成したサービスプリンシパルの OAuth シークレットに置き換えます。
<endpoint-id> をルート最適化エンドポイントのエンドポイント ID に置き換えます。これは、エンドポイント URL の hostName にあるエンドポイントの英数字の ID です。
<action> を、サービスプリンシパルに付与されたアクション権限に置き換えます。アクションは query_inference_endpoint または manage_inference_endpointにすることができます。

REST API
Python

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

Bash


export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>
export ENDPOINT_ID=<endpoint-id>
export ACTION=<action>

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"'"]}]'

Python
import os import requests

# Set your environment variables or replace them directly here
CLIENT_ID = os.getenv("CLIENT_ID")
CLIENT_SECRET = os.getenv("CLIENT_SECRET")
ENDPOINT_ID = os.getenv("ENDPOINT_ID")
ACTION = "query_inference_endpoint" # Can also be `manage_inference_endpoint`

# Token endpoint URL
TOKEN_URL = "<token-endpoint-URL>"

# Build the payload, note the creation of authorization_details
payload = { 'grant_type': 'client_credentials', 'scope': 'all-apis', 'authorization_details': f'''[{{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/{ENDPOINT_ID}","actions":["{ACTION}"]}}]''' }

# Make the POST request with basic auth
response = requests.post( TOKEN_URL, auth=(CLIENT_ID, CLIENT_SECRET), data=payload )

# Check the response
if response.ok:
  token_response = response.json()
  access_token = token_response.get("access_token")
  if access_token:
    print(f"Access Token: {access_token}")
  else:
    print("access_token not found in response.")
else: print(f"Failed to fetch token: {response.status_code} {response.text}")

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

REST API
Python

次に、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"

次に Python の例を示します。

Python

import requests
import json

url = "<url>"
oauth_token = "<token>"

data = {
    "dataframe_split": {
        "columns": ["feature_1", "feature_2"],
        "data": [
            [0.12, 0.34],
            [0.56, 0.78],
            [0.90, 0.11]
        ]
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {oauth_token}"
}

response = requests.post(url, headers=headers, json=data)

# Print the response
print("Status Code:", response.status_code)
print("Response Body:", response.text)

必要条件​

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

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

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

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

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

必要条件

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

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

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

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

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