Útvonaloptimalizált kiszolgálóvégpontok lekérdezése

Ez a cikk bemutatja, hogyan lehet lekérni a megfelelő hitelesítési adatokat és URL-címet, hogy le tudja kérdezni az útvonaloptimalizált modellkiszolgálás vagy feature kiszolgáló végpontját.

Követelmények

  • Útvonaloptimalizálással engedélyezett modellkiszolgáló végpont vagy jellemzőkiszolgáló végpont. Lásd : Útvonaloptimalizálás a végpontok kiszolgálására.
  • Az útvonaloptimalizált végpontok lekérdezése csak OAuth-jogkivonatok használatát támogatja. A személyes hozzáférési jogkivonatok nem támogatottak.

Rövid útmutató: végpontok közötti lekérdezési recept

Az alábbi recept egyesíti az útvonaloptimalizált végpont külső ügyfélből egyetlen futtatható folyamatba való lekérdezéséhez szükséges összes lépést. Ezt a szakaszt akkor használja, ha gyorsan ellenőrizni szeretné a működő beállításokat. Az egyes lépésekkel kapcsolatos további részletekért tekintse meg az alábbi szakaszokat.

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

Az útvonaloptimalizált URL-cím beolvasása

Figyelmeztetés

2025. szeptember 22-től az összes újonnan létrehozott útvonaloptimalizált végpontot kizárólag az útvonaloptimalizált URL-címen keresztül kell lekérdezni. Az ezen dátum után létrehozott végpontok nem támogatják a munkaterület URL-címén keresztüli lekérdezést.

Ha az útvonaloptimalizált végpont 2025. szeptember 22. előtt lett létrehozva:

  • A szabványos munkaterület URL-címe a végpont lekérdezésére is használható. A szabványos munkaterület URL-elérési útja nem biztosítja az útvonaloptimalizálás előnyeit.

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

  • Az ezen dátum előtt létrehozott útvonaloptimalizált végpontok továbbra is támogatják a meghívások URL-címeit: az útvonaloptimalizált URL-címet és a szabványos munkaterület URL-elérési útját.

Útvonaloptimalizált végpont létrehozásakor a rendszer a következő útvonaloptimalizált URL-címet hozza létre a végponthoz.

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

Ezt az URL-címet az alábbiakból szerezheti be:

Felhasználói felület kiszolgálása

útvonaloptimalizált végpont URL-címe

REST API

Használja az GET /api/2.0/serving-endpoints/{name} API-hívást. Az URL-cím a végpont válaszobjektumában a következőképpen endpoint_urljelenik meg: . Ez a mező csak akkor lesz feltöltve, ha a végpont útvonaloptimalizált.

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

Databricks SDK

Használja a Serving Endpoints API get hívást. Az URL-cím a végpont válaszobjektumában a következőképpen endpoint_urljelenik meg: . Ez a mező csak akkor lesz feltöltve, ha a végpont útvonaloptimalizált.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

OAuth-jogkivonat lekérése és a végpont lekérdezése

Az útvonaloptimalizált végpont lekérdezéséhez OAuth-jogkivonatot kell használnia. A Databricks szolgáltatásnevek használatát javasolja az éles alkalmazásokban az OAuth-jogkivonatok programozott lekéréséhez. Az alábbi szakasz ismerteti az ajánlott útmutatást az OAuth token tesztelési és éles környezetekben való használatához.

OAuth-jogkivonat lekérése a kiszolgálói felhasználói felület használatával

Az alábbi lépések bemutatják, hogyan lehet jogkivonatot lekérni a kiszolgáló felhasználói felületén. Ezek a lépések a végpont fejlesztéséhez és teszteléséhez ajánlottak.

Éles használat esetén, például az útvonaloptimalizált végpont alkalmazáson belüli használata esetén a jogkivonat egy szolgáltatásnév használatával lesz lekérve. A gyakorlati felhasználási esetekhez szükséges OAuth-jogkivonat lekéréséhez javasolt útmutatásért tekintse meg a programozott módon történő OAuth-jogkivonat lekérését.

A munkaterület kiszolgálói felhasználói felületén:

  1. A Végpontok kiszolgálása lapon válassza ki az útvonaloptimalizált végpontot a végpont részleteinek megtekintéséhez.
  2. A végpont részletei lapon válassza a Használat gombot.
  3. Válassza a Jogkivonat lekérése lapot.
  4. Válassza az OAuth-jogkivonat beolvasása gombot. Ez a jogkivonat 1 órán át érvényes. Új jogkivonat lekérése, ha az aktuális jogkivonat lejár.

Az OAuth-jogkivonat lekérése után kérje le a végpontot a végpont URL-címével és az OAuth-jogkivonattal.

REST API

A következő egy REST API-példa:


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

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

Python

A következő egy Python-példa:


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-token programozott lekérése

Éles forgatókönyvek esetén a Databricks azt javasolja, hogy állítsa be a szolgáltatási főazonosítókat az alkalmazásába, hogy programozottan lekérhesse az OAuth-jogkivonatokat. Ezek a lekért jogkivonatok az útvonaloptimalizált végpontok lekérdezésére szolgálnak.

Kövesse az Szolgáltatásnévazonosító hozzáférésének engedélyezése az Azure Databrickshez OAuth-hitelesítéssel című témakörben ismertetett lépéseket a 2. lépésig a szolgáltatásnévazonosító létrehozásához, az engedélyek hozzárendeléséhez, valamint egy OAuth-titkos kulcs létrehozásához a szolgáltatásnévazonosítóhoz. A szolgáltatásnév létrehozása után legalább lekérdezési engedélyt kell adnia a szolgáltatásnévnek a végponton. Lásd: Engedélyek kezelése egy végpontot kiszolgáló modellen.

A Databricks Python SDK egy API-t biztosít egy útvonaloptimalizált végpont közvetlen lekérdezéséhez.

Megjegyzés:

A Databricks SDK a Go-ban is elérhető, lásd: Databricks SDK for Go.

A következő példához az alábbiakra van szükség egy útvonaloptimalizált végpont lekérdezéséhez a Databricks SDK használatával:

  • Kiszolgálóvégpont neve (az SDK a név alapján lekéri a megfelelő végpont URL-címét)
  • Szolgáltatásfő kliensazonosítója
  • Szolgáltatásnév titkos kódja
  • Munkaterület állomásneve
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-jogkivonat manuális lekérése

Olyan esetekben, amikor a Databricks SDK vagy a kiszolgáló felhasználói felület nem használható az OAuth-jogkivonat lekérésére, manuálisan is lekérhet egy OAuth-jogkivonatot. Az ebben a szakaszban található útmutatás elsősorban azokra a forgatókönyvekre vonatkozik, amelyekben a felhasználók olyan testreszabott ügyfélrel rendelkeznek, amelyet a végpont éles környezetben való lekérdezéséhez szeretnének használni.

Ha manuálisan kér le egy OAuth-jogkivonatot, meg kell adnia authorization_details a kérésben.

  • A <token-endpoint-URL>-t úgy hozhatja létre, hogy a https://<databricks-instance>-t a Databricks üzembe helyezési munkaterületének URL-címére cseréli a https://<databricks-instance>/oidc/v1/token-ben. Például: https://my-workspace.0.azuredatabricks.net/oidc/v1/token
  • Cserélje le <client-id> a szolgáltatásnév objektumának ügyfélazonosítójával, amely alkalmazásazonosítóként is ismert.
  • Cserélje le a(z) <client-secret> a szolgáltatásfelelős által létrehozott OAuth titkos kódjára.
  • Cserélje le <endpoint-id> az útvonaloptimalizált végpont végpontazonosítójára. Ez annak a végpontnak az alfa-numerikus azonosítója, amelyet a hostName végpont URL-címében talál. Például, ha a kiszolgáló végpontja a https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, akkor a végpont azonosítója a abcdefg.
  • Cserélje le a(z) <action> elemet a szolgáltatásnévhez adott műveleti engedélyre. A művelet lehet query_inference_endpoint vagy manage_inference_endpoint.

REST API

A következő egy REST API-példa:



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

A következő egy Python-példa:

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}")

Az OAuth-jogkivonat lekérése után kérje le a végpontot a végpont URL-címével és az OAuth-jogkivonattal.

REST API

A következő egy REST API-példa:


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

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

Python

A következő egy Python-példa:


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)

Hívás ügynökből vagy külső alkalmazásból

Az útvonaloptimalizált végpontokat lekérdező AI-kódolási asszisztensek és külső alkalmazások nem használhatják a fejlesztő személyes hozzáférési jogkivonatát vagy a munkaterület OAuth-jogkivonatait. Szolgáltatásnevet kell használniuk az OAuth M2M-folyamattal, és a(z) authorization_details elemet bele kell foglalniuk a tokenkérelembe. A folyamat a következő:

  1. Hozzon létre egy service principalt fiókszinten, valamint egy OAuth-titkot hozzá. Lásd: Szolgáltatás főfelhasználó hozzáférésének engedélyezése az Azure Databrickshez OAuth használatával.
  2. Rendelje hozzá a szolgáltatásnevet a munkaterülethez, és adja meg CAN_QUERY a végponton.
  3. Az alkalmazásból hozzon létre egy végpontra érvényes jogkivonatot a(z) POST <workspace-host>/oidc/v1/token meghívásával, a szolgáltatásnév hitelesítő adataival, valamint a(z) authorization_details használatával, amely a végpontazonosítóra hivatkozik. Lásd: OAuth-jogkivonat manuális lekérése.
  4. Hívja meg az útvonalra optimalizált URL-címet a kapott tokennel.

A fenti Gyors üzembe helyezés szakasz egyetlen másolható szkriptet tartalmaz, amely minden lépést lefed.

Hibaelhárítás

Hiba A probléma oka Kijavítás
401 Malformed token az útvonalra optimalizált URL-címről visszatérve A token személyes hozzáférési token vagy klaszter-futásidejű token, nem pedig OAuth JWT. Az útvonaloptimalizált végpontok csak OAuth-jogkivonatokat fogadnak el. OAuth-token lekéréséhez használjon szolgáltatásnevet az OAuth M2M-folyamat használatával. Lásd: OAuth-jogkivonat beolvasása programozott módon.
401 Missing authorization details for accessing model serving endpoints az útvonalra optimalizált URL-címről visszatérve A tokenkérelem nem tartalmazta azt a authorization_details claimet, amely az adott végpontra korlátozza a token hatókörét. Egy egyszerű scope=all-apis token nem elegendő. A(z) authorization_details paramétert a végpontazonosítóra és a(z) query_inference_endpoint műveletre hivatkozva adja át a(z) /oidc/v1/token meghívásakor. Lásd: OAuth-jogkivonat manuális lekérése.
400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ... A kérelmet az útvonaloptimalizált URL-cím helyett a munkaterület URL-címére https://<workspace>/serving-endpoints/<name>/invocations küldte. Használja a visszaadott URL-címet a endpoint_url következő mezőben GET /api/2.0/serving-endpoints/<name>: . Lásd : Az útvonaloptimalizált URL beolvasása.
403 Permission denied vissza lett adva az útvonal-optimalizált URL-ből annak ellenére, hogy az OAuth-token authorization_details A szolgáltatásnév nem rendelkezik CAN_QUERY a végponton, vagy a művelet authorization_details nem felel meg a megadott engedélynek. Adja meg CAN_QUERY a végponton a szolgáltatásnévnek, és használja query_inference_endpoint műveletként. Lásd: Engedélyek kezelése egy végpontot kiszolgáló modellen.
invalid_scope visszaadva innen: /oidc/v1/token A tokenkérelem a(z) all-apis értéktől eltérő hatókörértéket adott át. Az útvonaloptimalizált végponti jogkivonatok egyetlen támogatott hatóköre az all-apis. A végpont hatókörének szűkítése a(z) authorization_details használatával történik, nem a(z) scope használatával.
  • Last updated on