ルート最適化された提供エンドポイントをクエリする

この記事では、ルート最適化 モデルサービス または 機能サービス エンドポイントに対してクエリを実行できるように、適切な認証資格情報と URL をフェッチする方法について説明します。

要求事項

• ルートの最適化が有効になっているモデルサービスエンドポイントまたは機能サービスエンドポイント。 サービス エンドポイントでのルートの最適化に関する説明を参照してください。
• ルート最適化エンドポイントのクエリでは、OAuth トークンの使用のみがサポートされます。 個人用アクセス トークンはサポートされません。

クイックスタート: エンドツーエンドのクエリ手順

次のレシピでは、外部クライアントからルート最適化エンドポイントに対してクエリを実行するために必要なすべての手順を 1 つの実行可能フローに結合します。 作業中のセットアップをすばやく確認する場合は、このセクションを使用します。 各手順の詳細については、次のセクションを参照してください。

# 1. Set the variables for your environment.
export DATABRICKS_HOST="https://<your-workspace>.cloud.databricks.com"
export ENDPOINT_NAME="<your-endpoint>"
export WORKSPACE_ID="<workspace-id>"

# 2. Create an account-level service principal and an OAuth secret for it.
SP_ID=$(databricks account service-principals create \
  --json '{"displayName":"my-app","active":true}' --output json | jq -r '.id')
SECRET_JSON=$(databricks account service-principal-secrets create "$SP_ID" --output json)
export CLIENT_ID=$(databricks account service-principals get "$SP_ID" --output json | jq -r '.applicationId')
export CLIENT_SECRET=$(echo "$SECRET_JSON" | jq -r '.secret')

# 3. Assign the service principal to the workspace and grant CAN_QUERY on the endpoint.
databricks account workspace-assignment update "$WORKSPACE_ID" "$SP_ID" \
  --json '{"permissions":["USER"]}'
ENDPOINT_ID=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.id')
databricks permissions update serving-endpoints "$ENDPOINT_ID" \
  --json "{\"access_control_list\":[{\"service_principal_name\":\"$CLIENT_ID\",\"permission_level\":\"CAN_QUERY\"}]}"

# 4. Mint an endpoint-scoped OAuth token. `authorization_details` is required for
# route-optimized endpoints -- a plain `scope=all-apis` token is rejected with
# 401 "Missing authorization details" when used against the route-optimized URL.
TOKEN=$(curl -sS -X POST -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=all-apis" \
  --data-urlencode "authorization_details=[{\"type\":\"workspace_permission\",\"object_type\":\"serving-endpoints\",\"object_path\":\"/serving-endpoints/$ENDPOINT_ID\",\"actions\":[\"query_inference_endpoint\"]}]" \
  "$DATABRICKS_HOST/oidc/v1/token" | jq -r '.access_token')

# 5. Invoke the endpoint at its route-optimized URL.
RO_URL=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.endpoint_url')
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"inputs":[[0.12,0.34]]}' "https://$RO_URL"

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

ルート最適化エンドポイントを作成すると、エンドポイントに対して次のルート最適化 URL が作成されます。

https://<unique-id>.<shard>.serving.azuredatabricks.net/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

この URL は次から取得できます。

ユーザーインターフェースの提供

REST API

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

GET /api/2.0/serving-endpoints/my-endpoint
{
  "name": "my-endpoint"
}

Databricks SDK

Serving Endpoints API get呼び出しを使用します。 URL は、エンドポイントの応答オブジェクトに endpoint_urlとして存在します。 このフィールドは、エンドポイントがルート最適化されている場合にのみ設定されます。

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

workspace.serving_endpoints.get("my-endpoint")

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

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

提供 UI を使用して OAuth トークンを取得する

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

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

ワークスペースの [サービス ] UI から:

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

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

REST API

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

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 トークンをプログラムでフェッチするために、アプリケーション内に埋め込むサービス プリンシパルを設定することをお勧めします。 これらのフェッチされたトークンは、ルート最適化エンドポイントのクエリに使用されます。

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

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

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

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

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.0.azuredatabricks.net/oidc/v1/token のように指定します。

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

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

• <action> を、サービス プリンシパルに付与されているアクション アクセス許可に置き換えます。 アクションには、query_inference_endpoint または manage_inference_endpoint を指定できます。

REST API

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

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

Python

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

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

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)

AI エージェントまたは外部アプリケーションからの呼び出し

ルート最適化エンドポイントにクエリを実行する AI コーディング アシスタントと外部アプリケーションは、開発者の個人用アクセス トークンまたはワークスペース OAuth トークンを使用できません。 OAuth M2M フローでサービス プリンシパルを使用し、トークン要求に authorization_details を含める必要があります。 フローは次のとおりです。

1. アカウント レベルでサービス プリンシパルを作成し、それに対する OAuth シークレットを作成します。 Azure Databricks へのサービス プリンシパル アクセスを OAuth で承認する方法については、こちらを参照してください。
2. サービス プリンシパルをワークスペースに割り当て、エンドポイントで CAN_QUERY 付与します。
3. アプリケーションから、サービス プリンシパルの資格情報を使用して POST <workspace-host>/oidc/v1/token を呼び出し、エンドポイント ID を参照する authorization_details を指定して、エンドポイント スコープ トークンを発行します。 OAuth トークンを手動でフェッチするを参照してください。
4. 結果のトークンを使用して、ルート最適化 URL を呼び出します。

上記の クイック スタート セクションには、すべての手順をカバーする 1 つのコピー可能な貼り付け可能なスクリプトが含まれています。

Troubleshooting