Köra frågor mot routningsoptimerade serverslutpunkter

Den här artikeln beskriver hur du hämtar lämpliga autentiseringsuppgifter och webbadress så att du kan fråga din ruttoptimerade modellbetjänings eller funktionsbetjänings slutpunkt.

Kravspecifikation

• En modell som betjänar slutpunkt eller funktionsserverslutpunkt som har routningsoptimering aktiverat. Se Ruttoptimering på serverändpunkter.
• Det går bara att göra förfrågningar mot rout-optimerade slutpunkter med OAuth-tokens. Personliga åtkomsttoken stöds inte.

Snabbstart: heltäckande guide för frågor

Följande recept kombinerar varje steg som behövs för att köra frågor mot en routningsoptimerad slutpunkt från en extern klient till ett enda körningsbart flöde. Använd det här avsnittet om du vill verifiera en fungerande konfiguration snabbt. Mer information om varje steg finns i följande avsnitt.

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

Hämta den ruttoptimerade URL:en

När du skapar en vägoptimerad slutpunkt skapas följande routningsoptimerade URL för slutpunkten.

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

Du kan hämta den här URL:en från följande:

Serveringsgränssnitt

REST-API

Använd API-anropet GET /api/2.0/serving-endpoints/{name} . URL:en finns i svarsobjektet för slutpunkten som endpoint_url. Det här fältet fylls bara i om slutpunkten är routningsoptimerad.

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

Databricks SDK

Använd samtalet Serving Endpoints API get . URL:en finns i svarsobjektet för slutpunkten som endpoint_url. Det här fältet fylls bara i om slutpunkten är routningsoptimerad.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Hämta en OAuth-token och anropa slutpunkten

Om du vill köra frågor mot din routningsoptimerade slutpunkt måste du använda en OAuth-token. Databricks rekommenderar att du använder tjänstens huvudnamn i dina produktionsprogram för att hämta OAuth-token programmatiskt. I följande avsnitt beskrivs rekommenderad vägledning om hur du hämtar en OAuth-token för test- och produktionsscenarier.

Hämta en OAuth-token med hjälp av användargränssnittet för servering

Följande steg visar hur du hämtar en token i användargränssnittet för servering. De här stegen rekommenderas för utveckling och testning av slutpunkten.

För användning i produktion, som att använda din ruttoptimerade slutpunkt i en applikation, hämtas din token med hjälp av ett tjänsthuvud. Se Hämta en OAuth-token programmatiskt för rekommenderad vägledning för att hämta din OAuth-token för produktionsanvändningsfall.

Från arbetsytans serveringsgränssnitt :

1. På sidan Serveringsslutpunkter väljer du din routningsoptimerade slutpunkt för att se slutpunktsinformation.
2. På sidan slutpunktsinformation väljer du knappen Använd .
3. Välj fliken Hämta token.
4. Välj knappen 'Hämta OAuth-token' . Den här token är giltig i 1 timme. Hämta en ny token om din aktuella token upphör att gälla.

När du har hämtat OAuth-token skickar du en förfrågan till slutpunkten med hjälp av slutpunkts-URL och OAuth-token.

REST-API

Följande är ett REST API-exempel:

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

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

python

Följande är ett Python-exempel:

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ämta en OAuth-token programmatiskt

För produktionssyften rekommenderar Databricks att du konfigurerar tjänstekonton för att integrera med ditt program och hämta OAuth-token på ett automatiserat sätt. Dessa hämtade token används för att skicka frågor till ruttoptimerade slutpunkter.

Följ stegen i Auktorisera tjänstens huvudnamnsåtkomst till Azure Databricks med OAuth via steg 2 för att skapa tjänstens huvudnamn, tilldela behörigheter och skapa en OAuth-hemlighet för tjänstens huvudnamn. När tjänstehuvudkontot har skapats måste du ge tjänstehuvudkontot minst begärandebehörighet på slutpunkten. Se Hantera behörigheter för en modell som betjänar slutpunkten.

Databricks Python SDK tillhandahåller ett API för att direkt fråga en routningsoptimerad slutpunkt.

Nästa exempel kräver följande för att köra frågor mot en routningsoptimerad slutpunkt med hjälp av Databricks SDK:

• Serverdelsnamn (SDK hämtar rätt slutpunkts-URL baserat på det här namnet)
• Klient-ID för tjänstens huvudnamn
• Tjänstens huvudnamnshemlighet
• Värdnamn för arbetsyta

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 = ....)

Hämta OAuth-tokenen manuellt

För scenarier där Databricks SDK eller serveringsgränssnittet inte kan användas för att hämta din OAuth-token kan du manuellt hämta en OAuth-token. Vägledningen i det här avsnittet gäller främst scenarier där användare har en anpassad klient som de vill använda för att köra frågor mot slutpunkten i produktionen.

När du hämtar en OAuth-token manuellt måste du ange authorization_details i begäran.

• Skapa <token-endpoint-URL> genom att ersätta https://<databricks-instance> med arbetsytans URL för din Databricks-distribution i https://<databricks-instance>/oidc/v1/token. Till exempel: https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Ersätt <client-id> med tjänstens huvudnamns klient-ID, som även kallas program-ID.
• Ersätt <client-secret> med tjänstens huvudnamns OAuth-hemlighet som du skapade.

• Ersätt <endpoint-id> med slutpunkts-ID för den routningsoptimerade slutpunkten. Det här är det alfanumeriska ID:t för slutpunkten som du hittar i hostName slutpunkts-URL:en. Om serverdelsslutpunkten till exempel är https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, är slutpunkts-ID:t abcdefg.

• Ersätt <action> med åtgärdsbehörigheten som ges till tjänstens huvudnamn. Åtgärden kan vara query_inference_endpoint eller manage_inference_endpoint.

REST-API

Följande är ett REST API-exempel:

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

Följande är ett Python-exempel:

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

När du har hämtat OAuth-token skickar du en förfrågan till slutpunkten med hjälp av slutpunkts-URL och OAuth-token.

REST-API

Följande är ett REST API-exempel:

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

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

python

Följande är ett Python-exempel:

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)

Ringa från en agent eller ett externt program

AI-kodningsassistenter och externa program som frågar efter routningsoptimerade slutpunkter kan inte använda en utvecklares personliga åtkomsttoken eller OAuth-token för arbetsytan. De måste använda ett huvudnamn för tjänsten med OAuth M2M-flödet och inkludera authorization_details i tokenbegäran. Flödet är:

1. Skapa ett huvudnamn för tjänsten på kontonivå och en OAuth-hemlighet för den. Se Auktorisera tjänstens huvudnamnsåtkomst till Azure Databricks med OAuth.
2. Tilldela tjänstens huvudnamn till arbetsytan och bevilja den CAN_QUERY på slutpunkten.
3. Från applikationen skapar du en endpoint-begränsad token genom att anropa POST <workspace-host>/oidc/v1/token med autentiseringsuppgifterna för tjänsthuvudnamnet och authorization_details som refererar till endpoint-ID:t. Se Hämta en OAuth-token manuellt.
4. Anropa den routningsoptimerade URL:en med den resulterande token.

Avsnittet Snabbstart ovan innehåller ett enda skript som kan klistras in och som omfattar varje steg.

Felsökning