Mengkueri titik akhir penyajian yang dioptimalkan rute

Artikel ini menjelaskan cara mengambil kredensial autentikasi dan URL yang sesuai sehingga Anda dapat mengkueri penyajian model atau penyajian fitur pada titik akhir yang dioptimalkan untuk rute Anda.

Persyaratan

  • Model yang melayani titik akhir atau fitur yang melayani titik akhir yang mengaktifkan pengoptimalan rute. Lihat Pengoptimalan rute pada titik akhir penyajian.
  • Mengkueri titik akhir yang dioptimalkan rute hanya mendukung penggunaan token OAuth. Token akses pribadi tidak didukung.

Panduan cepat: panduan kueri menyeluruh

Resep berikut menggabungkan setiap langkah yang diperlukan untuk mengkueri titik akhir yang dioptimalkan rute dari klien eksternal ke dalam satu alur yang dapat dijalankan. Gunakan bagian ini jika Anda ingin memverifikasi penyetelan yang berfungsi dengan cepat. Lihat bagian berikut untuk detail selengkapnya tentang setiap langkah.

# 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"

Dapatkan URL yang dioptimalkan untuk rute

Peringatan

Mulai 22 September 2025, semua titik akhir yang dioptimalkan rute yang baru dibuat harus dikueri secara eksklusif melalui URL yang dioptimalkan rute. Titik akhir yang dibuat setelah tanggal ini tidak mendukung kueri melalui URL ruang kerja.

Jika titik akhir yang dioptimalkan rute Anda dibuat sebelum 22 September 2025:

  • URL ruang kerja standar juga dapat digunakan untuk mengkueri titik akhir. Jalur URL ruang kerja standar tidak memberikan manfaat pengoptimalan rute.

    https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations

  • Titik akhir yang dioptimalkan untuk rute yang dibuat sebelum tanggal ini akan terus mendukung kedua jenis URL invokasi: jalur URL yang dioptimalkan untuk rute dan jalur URL ruang kerja standar.

Saat Anda membuat titik akhir teroptimasi rute, URL teroptimasi rute berikut dibuat untuk titik akhir.

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

Anda bisa mendapatkan URL ini dari yang berikut ini:

Menyajikan Antarmuka Pengguna

URL titik akhir yang dioptimalkan rute

REST API

Gunakan GET /api/2.0/serving-endpoints/{name} panggilan API. URL terdapat dalam objek respons dari titik akhir sebagai endpoint_url. Bidang ini hanya diisi jika titik akhir dioptimalkan untuk rute.

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

Databricks SDK

Gunakan perintah Serving Endpoints API get URL terdapat dalam objek respons dari titik akhir sebagai endpoint_url. Bidang ini hanya diisi jika titik akhir dioptimalkan untuk rute.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Mengambil token OAuth dan mengkueri titik akhir

Untuk meminta endpoint yang dioptimalkan untuk rute, Anda harus menggunakan token OAuth. Databricks merekomendasikan penggunaan perwakilan layanan dalam aplikasi produksi Anda untuk mengambil token OAuth secara terprogram. Bagian berikut menjelaskan panduan yang direkomendasikan tentang cara mengambil token OAuth untuk skenario pengujian dan produksi.

Mengambil token OAuth menggunakan Antarmuka Pengguna Penyedia Layanan

Langkah-langkah berikut menunjukkan cara mendapatkan token di Serving UI. Langkah-langkah ini direkomendasikan untuk pengembangan dan pengujian titik akhir Anda.

Untuk penggunaan dalam produksi, seperti menggunakan titik akhir yang dioptimalkan rute Anda dalam sebuah aplikasi, token Anda diambil menggunakan prinsip layanan. Lihat Mengambil token OAuth secara terprogram untuk panduan yang direkomendasikan untuk mengambil token OAuth Anda untuk kasus penggunaan produksi.

Dari UI Penyajian ruang kerja Anda:

  1. Pada halaman Endpoint penyajian, pilih endpoint yang dioptimalkan untuk rute Anda untuk melihat detail endpoint.
  2. Pada halaman detail titik akhir, pilih tombol Gunakan .
  3. Pilih tab Ambil Token.
  4. Pilih tombol Ambil Token OAuth. Token ini berlaku selama 1 jam. Ambil token baru jika token Anda saat ini kedaluwarsa.

Setelah Anda mengambil token OAuth, kueri titik akhir Anda menggunakan URL titik akhir dan token OAuth Anda.

REST API

Berikut ini adalah contoh 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"

Phyton

Berikut ini adalah contoh 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)

Mengambil token OAuth secara terprogram

Untuk skenario produksi, Databricks merekomendasikan menyetel perwakilan layanan yang dapat disematkan dalam aplikasi Anda untuk mengambil token OAuth secara otomatis. Token yang diambil ini digunakan untuk melakukan kueri pada titik akhir yang dioptimalkan untuk rute.

Ikuti langkah-langkah dalam Mengotorisasi akses perwakilan layanan ke Azure Databricks dengan OAuth hingga langkah 2 untuk membuat perwakilan layanan Anda, menetapkan izin, dan membuat rahasia OAuth untuk perwakilan layanan Anda. Setelah prinsipal layanan Anda dibuat, Anda harus memberi prinsipal layanan setidaknya izin Kueri pada titik akhir. Lihat Mengelola izin pada model yang melayani titik akhir.

Databricks Python SDK menyediakan API untuk langsung mengkueri titik akhir yang dioptimalkan rute.

Nota

Databricks SDK juga tersedia di Go, lihat Databricks SDK for Go.

Contoh berikutnya memerlukan hal berikut untuk mengkueri titik akhir yang dioptimalkan rute menggunakan Databricks SDK:

  • Nama titik akhir penyajian (SDK mengambil URL titik akhir yang benar berdasarkan nama ini)
  • ID Klien Principal Layanan
  • Rahasia perwakilan layanan
  • Nama host ruang kerja
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 = ....)

Mengambil token OAuth secara manual

Untuk skenario di mana Databricks SDK atau Antarmuka Pengguna Penyajian tidak dapat digunakan untuk mengambil token OAuth Anda, Anda dapat mengambil token OAuth secara manual. Panduan di bagian ini terutama berlaku untuk skenario di mana pengguna memiliki klien yang disesuaikan yang ingin mereka gunakan untuk mengkueri titik akhir dalam produksi.

Saat Anda mengambil token OAuth secara manual, Anda harus menentukan authorization_details dalam permintaan.

  • Buat <token-endpoint-URL> dengan mengganti https://<databricks-instance> dengan URL ruang kerja penyebaran Databricks Anda di https://<databricks-instance>/oidc/v1/token. Misalnya: https://my-workspace.0.azuredatabricks.net/oidc/v1/token
  • Ganti <client-id> dengan ID klien perwakilan layanan, yang juga dikenal sebagai ID aplikasi.
  • Ganti <client-secret> dengan rahasia OAuth prinsipal layanan yang Anda buat.
  • Ganti <endpoint-id> dengan ID titik akhir yang telah dioptimalkan rutenya. Ini adalah ID alfa-numerik dari titik akhir yang dapat Anda temukan di hostName URL titik akhir. Misalnya, jika titik akhir penyajian adalah https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, ID titik akhir adalah abcdefg.
  • Ganti <action> dengan izin tindakan yang diberikan kepada perwakilan layanan. Tindakannya bisa query_inference_endpoint atau manage_inference_endpoint.

REST API

Berikut ini adalah contoh 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"'"]}]'

Phyton

Berikut ini adalah contoh 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}")

Setelah Anda mengambil token OAuth, kueri titik akhir Anda menggunakan URL titik akhir dan token OAuth Anda.

REST API

Berikut ini adalah contoh 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"

Phyton

Berikut ini adalah contoh 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)

Memanggil dari agen atau aplikasi eksternal

Asisten pengodian AI dan aplikasi eksternal yang mengkueri titik akhir yang dioptimalkan rute tidak dapat menggunakan token akses pribadi pengembang atau token OAuth ruang kerja. Mereka harus menggunakan prinsipal layanan dengan alur OAuth M2M dan menyertakan authorization_details dalam permintaan token. Alurnya adalah:

  1. Buat perwakilan layanan di tingkat akun dan rahasia OAuth untuk itu. Lihat Otorisasi akses prinsipal layanan ke Azure Databricks dengan OAuth.
  2. Tetapkan perwakilan layanan ke ruang kerja dan berikan CAN_QUERY di titik akhir.
  3. Dari aplikasi, buat token dengan cakupan endpoint dengan memanggil POST <workspace-host>/oidc/v1/token menggunakan kredensial service principal dan authorization_details yang merujuk ke ID endpoint. Lihat Mengambil token OAuth secara manual.
  4. Panggil URL yang dioptimalkan untuk rute dengan token yang dihasilkan.

Bagian Mulai cepat di atas berisi satu skrip yang dapat disalin yang mencakup setiap langkah.

Troubleshooting

Kesalahan Cause Perbaiki
401 Malformed token dikembalikan dari URL yang dioptimalkan untuk rute Token tersebut adalah token akses pribadi atau token runtime cluster, bukan OAuth JWT. Titik akhir yang dioptimalkan rute hanya menerima token OAuth. Gunakan prinsipal layanan dengan alur OAuth M2M untuk mengambil token OAuth. Lihat Mengambil token OAuth secara terprogram.
401 Missing authorization details for accessing model serving endpoints dikembalikan dari URL yang dioptimalkan untuk rute Permintaan token tidak menyertakan klaim authorization_details yang membatasi cakupan token ke endpoint tertentu. Token biasa scope=all-apis tidak cukup. Teruskan authorization_details yang merujuk ke ID endpoint dan aksi query_inference_endpoint saat memanggil /oidc/v1/token. Lihat Mengambil token OAuth secara manual.
400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ... Anda mengirim permintaan ke URL ruang kerja https://<workspace>/serving-endpoints/<name>/invocations alih-alih URL yang dioptimalkan untuk rute. Gunakan URL yang dikembalikan dalam kolom endpoint_url di GET /api/2.0/serving-endpoints/<name>. Lihat Mengambil URL yang dioptimalkan untuk rute.
403 Permission denied dikembalikan dari URL yang dioptimalkan untuk rute meskipun token OAuth berisi authorization_details Perwakilan layanan tidak memiliki CAN_QUERY pada titik akhir, atau tindakan di authorization_details tidak cocok dengan izin yang diberikan. Berikan CAN_QUERY pada titik akhir kepada perwakilan layanan dan gunakan query_inference_endpoint sebagai tindakan. Lihat Mengelola izin pada model yang melayani titik akhir.
invalid_scope dikembalikan dari /oidc/v1/token Permintaan token melewati nilai cakupan selain all-apis. Satu-satunya ruang lingkup yang didukung untuk token endpoint yang dioptimalkan untuk rute adalah all-apis. Downscoping endpoint dilakukan melalui authorization_details, bukan scope.
  • Last updated on