Eseguire query sugli endpoint di servizio ottimizzati per le route

Questo articolo descrive come recuperare le credenziali di autenticazione e l'URL appropriati in modo da poter eseguire query sul modello ottimizzato per la route o l'endpoint di gestione delle funzionalità .

Requisiti

• Un modello che gestisce l'endpoint o la funzionalità che gestisce l'endpoint con ottimizzazione della route abilitata. Vedere Ottimizzazione della route per la gestione degli endpoint.
• L'esecuzione di query sugli endpoint ottimizzati per i percorsi supporta solo l'uso di token OAuth. I token di accesso personali non sono supportati.

Avvio rapido: ricetta delle query end-to-end

La ricetta seguente combina ogni passaggio necessario per eseguire query su un endpoint ottimizzato per la route da un client esterno in un singolo flusso eseguibile. Usare questa sezione se si vuole verificare rapidamente una configurazione funzionante. Per altri dettagli su ogni passaggio, vedere le sezioni seguenti.

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

Recupera l'URL ottimizzato per il percorso

Quando si crea un endpoint ottimizzato per il percorso, viene creato il seguente URL ottimizzato per il percorso per l'endpoint.

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

È possibile ottenere questo URL dai seguenti elementi:

Interfaccia utente di gestione

REST API (Interfaccia di Programmazione delle Applicazioni REST)

Utilizzare la chiamata API GET /api/2.0/serving-endpoints/{name}. L'URL è presente nell'oggetto risposta dell'endpoint come endpoint_url. Questo campo viene popolato solo se l'endpoint è ottimizzato per il percorso.

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

Databricks SDK

Usa la Serving Endpoints API get chiamata. L'URL è presente nell'oggetto risposta dell'endpoint come endpoint_url. Questo campo viene popolato solo se l'endpoint è ottimizzato per il percorso.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Recuperare un token OAuth ed eseguire query sull'endpoint

Per eseguire query nell'endpoint ottimizzato per la route, è necessario usare un token OAuth. Databricks consiglia di usare le entità servizio nelle applicazioni di produzione per recuperare i token OAuth a livello di codice. Le sezioni seguenti descrivono le indicazioni consigliate su come recuperare un token OAuth per scenari di test e produzione.

Recuperare un token OAuth usando l'interfaccia utente di servizio

I passaggi seguenti mostrano come recuperare un token nell’interfaccia utente di servizio. Questi passaggi sono consigliati per lo sviluppo e il test dell'endpoint.

Per l'uso in produzione, ad esempio l'uso dell'endpoint ottimizzato per la route in un'applicazione, il token viene recuperato usando un'entità servizio. Per indicazioni consigliate per il recupero del token OAuth per i casi d'uso di produzione, vedere Recuperare un token OAuth a livello di codice.

Dall'interfaccia utente di servizio dell'area di lavoro:

1. Nella pagina degli endpoint di servizio, selezionare il percorso ottimizzato per visualizzare i dettagli dell'endpoint.
2. Nella pagina dei dettagli dell'endpoint selezionare il pulsante Usa .
3. Selezionare la scheda Fetch Token (Recupera token).
4. Selezionare il pulsante Fetch OAuth Token (Recupera token OAuth ). Questo token è valido solo per un’ora. Recupera un nuovo token se il token corrente scade.

Dopo aver recuperato il token OAuth, eseguire una query sull'endpoint usando l'URL dell'endpoint e il token OAuth.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

Di seguito è riportato un esempio di API REST:

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

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

Pitone

Di seguito è riportato un esempio 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)

Recuperare un token OAuth a livello di codice

Per gli scenari di produzione, Databricks consiglia di configurare le entità servizio da incorporare all'interno dell'applicazione per recuperare i token OAuth a livello di codice. Questi token recuperati vengono usati per eseguire query sugli endpoint ottimizzati per la route.

Seguire la procedura descritta in Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth al passaggio 2 per creare l'entità servizio, assegnare autorizzazioni e creare un segreto OAuth per l'entità servizio. Dopo aver creato l'entità servizio, è necessario concedere almeno all'entità servizio l'autorizzazione Query per l'endpoint. Vedere Gestire le autorizzazioni per un endpoint di gestione del modello.

Databricks Python SDK fornisce un'API per eseguire direttamente query su un endpoint ottimizzato per il routing.

L'esempio seguente richiede quanto segue per eseguire una query su un endpoint ottimizzato per la route usando Databricks SDK:

• Nome dell'endpoint di gestione (l'SDK recupera l'URL dell'endpoint corretto in base a questo nome)
• ID cliente del principale servizio
• Segreto del principale del servizio
• Nome host dell'area di lavoro

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

Recuperare manualmente un token OAuth

Per gli scenari in cui Databricks SDK o l'interfaccia utente di servizio non possono essere usati per recuperare il token OAuth, è possibile recuperare manualmente un token OAuth. Le indicazioni contenute in questa sezione si applicano principalmente agli scenari in cui gli utenti hanno un client personalizzato che vogliono usare per eseguire query sull'endpoint nell'ambiente di produzione.

Quando si recupera manualmente un token OAuth, è necessario specificare authorization_details nella richiesta.

• Costruisci il <token-endpoint-URL> sostituendo https://<databricks-instance> con l'URL dell'area di lavoro della tua distribuzione Databricks in https://<databricks-instance>/oidc/v1/token. Ad esempio, https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Sostituire <client-id> con l'ID client del principale del servizio, noto anche come ID applicazione.
• Sostituire <client-secret> con il segreto OAuth del principale del servizio che hai creato.

• Sostituire <endpoint-id> con l'ID dell'endpoint ottimizzato per il percorso. Si tratta dell'ID alfanumerico dell'endpoint che è possibile trovare nell'elemento hostName dell'URL dell'endpoint. Ad esempio, se l'endpoint di gestione è https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, l'ID endpoint è abcdefg.

• Sostituisci <action> con l'autorizzazione dell'azione assegnata all'entità servizio. L’azione può essere query_inference_endpoint o manage_inference_endpoint.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

Di seguito è riportato un esempio di API REST:

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

Pitone

Di seguito è riportato un esempio 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}")

Dopo aver recuperato il token OAuth, eseguire una query sull'endpoint usando l'URL dell'endpoint e il token OAuth.

REST API (Interfaccia di Programmazione delle Applicazioni REST)

Di seguito è riportato un esempio di API REST:

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

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

Pitone

Di seguito è riportato un esempio 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)

Chiamata da un agente di intelligenza artificiale o da un'applicazione esterna

Gli assistenti di programmazione basati sull'IA e le applicazioni esterne che interrogano endpoint ottimizzati per il routing non possono usare il token di accesso personale di uno sviluppatore né i token OAuth dell'area di lavoro. Devono usare un service principal con il flusso OAuth M2M e includere authorization_details nella richiesta del token. Il flusso è:

1. Creare un service principal a livello di account e un segreto OAuth per esso. Consulta Autorizzare l'accesso del principale del servizio ad Azure Databricks con OAuth.
2. Assegnare l'entità servizio all'area di lavoro e concederle CAN_QUERY sull'endpoint.
3. Dall'applicazione, crea un token con ambito limitato all'endpoint chiamando POST <workspace-host>/oidc/v1/token con le credenziali del service principal e authorization_details che fa riferimento all'ID dell'endpoint. Vedere Recuperare manualmente un token OAuth.
4. Richiama l'URL ottimizzato per il percorso utilizzando il token risultante.

La sezione Avvio rapido precedente contiene un singolo script copiabile che copre ogni passaggio.

Troubleshooting