Interroger des points de terminaison de service optimisés pour l’itinéraire

Cet article explique comment extraire les informations d’identification et l’URL d’authentification appropriées afin de pouvoir interroger votre point de terminaison model serving optimisé pour l’itinéraire ou feature serving.

Spécifications

• Un point de terminaison de service de modèle ou un point de terminaison de service de fonctionnalité avec optimisation de l'itinéraire activée. Consultez l'optimisation des itinéraires sur les points de terminaison.
• L’interrogation de points de terminaison optimisés en fonction de l'itinéraire ne supporte que l’utilisation de jetons OAuth. Les jetons d’accès personnels ne sont pas pris en charge.

Récupérer l’URL optimisée pour l’itinéraire

Lorsque vous créez un point de terminaison optimisé pour l’itinéraire, l’URL optimisée pour l’itinéraire suivante est créée pour le point de terminaison.

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

Vous pouvez obtenir cette URL à partir des éléments suivants :

Interface utilisateur de mise en service

API REST

Utilisez l’appel d’API GET /api/2.0/serving-endpoints/{name} . L’URL est présente dans l’objet de réponse du point de terminaison en tant que endpoint_url. Ce champ est renseigné uniquement si le point de terminaison est optimisé pour l’itinéraire.

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

Kit de développement logiciel (SDK) Databricks

Utilisez l’appel Serving Endpoints API get . L’URL est présente dans l’objet de réponse du point de terminaison en tant que endpoint_url. Ce champ est renseigné uniquement si le point de terminaison est optimisé pour l’itinéraire.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Récupérer un jeton OAuth et interroger le point de terminaison

Pour interroger votre point de terminaison optimisé pour l’itinéraire, vous devez utiliser un jeton OAuth. Databricks recommande d'utiliser principaux de service dans vos applications de production pour extraire des jetons OAuth par programmation. Les sections suivantes décrivent les conseils recommandés sur la façon d’extraire un jeton OAuth pour les scénarios de test et de production.

Récupérer un jeton OAuth à l’aide de l’interface utilisateur de service

Les étapes suivantes montrent comment récupérer un jeton dans l’interface utilisateur de service. Ces étapes sont recommandées pour le développement et le test de votre point de terminaison.

Pour une utilisation en production, comme l’utilisation de votre point de terminaison optimisé pour l’itinéraire dans une application, votre jeton est récupéré à l’aide d’un principal de service. Consultez Récupérer un jeton OAuth par programmation pour obtenir des conseils recommandés pour extraire votre jeton OAuth pour les cas d’usage de production.

À partir de l’interface utilisateur de service de votre espace de travail :

1. Dans la page Points de terminaison de service, sélectionnez votre point de terminaison optimisé pour l’itinéraire pour afficher les détails du point de terminaison.
2. Dans la page détails du point de terminaison, sélectionnez le bouton Utiliser .
3. Sélectionnez l’onglet Récupérer le jeton.
4. Sélectionnez le bouton Récupérer le jeton OAuth. Ce jeton est valide pendant 1 jours. Récupérez un nouveau jeton si votre jeton actuel expire.

Après avoir extrait le jeton OAuth, interrogez votre point de terminaison à l’aide de votre URL de point de terminaison et du jeton OAuth.

API REST

Voici un exemple d’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"

Python

Voici un exemple 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)

Récupérez un jeton OAuth par programmation

Pour les scénarios de production, Databricks recommande de configurer des principales de service à incorporer dans votre application pour récupérer automatiquement des jetons OAuth. Ces jetons extraits sont utilisés pour interroger les points de terminaison optimisés pour l’itinéraire.

Suivez les étapes décrites dans Autoriser l’accès au principal de service à Azure Databricks avec OAuth à l’étape 2 pour créer votre principal de service, attribuer des autorisations et créer un secret OAuth pour votre principal de service. Une fois votre principal de service créé, vous devez accorder au moins l’autorisation de requête sur le point de terminaison. Consultez Gérer les autorisations sur un point de terminaison de service de modèle.

Le Kit de développement logiciel (SDK) Python Databricks fournit une API pour interroger directement un point de terminaison optimisé pour l’itinéraire.

L’exemple suivant nécessite que les éléments suivants interrogent un point de terminaison optimisé pour l’itinéraire à l’aide du Kit de développement logiciel (SDK) Databricks :

• Nom du point de terminaison de service (le kit de développement logiciel (SDK) récupère l’URL correcte du point de terminaison en fonction de ce nom)
• ID de client du principal du service
• Secret du principal de service
• Nom d’hôte de l’espace de travail

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

Récupérer manuellement un jeton OAuth

Pour les scénarios où le Kit de développement logiciel (SDK) Databricks ou l’interface utilisateur de service ne peut pas être utilisé pour extraire votre jeton OAuth, vous pouvez récupérer manuellement un jeton OAuth. Les instructions de cette section s’appliquent principalement aux scénarios où les utilisateurs ont un client personnalisé qu’ils souhaitent utiliser pour interroger le point de terminaison en production.

Lorsque vous récupérez manuellement un jeton OAuth, vous devez spécifier authorization_details dans la requête.

• Construisez l’élément <token-endpoint-URL> en remplaçant https://<databricks-instance> par l’URL de l’espace de travail de votre déploiement Databricks dans https://<databricks-instance>/oidc/v1/token. Par exemple, https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Remplacez <client-id> par l’ID client du principal de service, également appelé ID d’application.
• Remplacez <client-secret> par le secret OAuth du principal de service que vous avez créé.

• Remplacez <endpoint-id> par l’ID de point de terminaison du point de terminaison optimisé pour l’itinéraire. Il s’agit de l’ID alphanumérique du point de terminaison que vous pouvez trouver dans l’URL hostName du point de terminaison. Par exemple, si le point de terminaison de service est https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, l’ID de point de terminaison est abcdefg.

• Remplacez <action> par la permission d’action accordée au principal de service. L’action peut être query_inference_endpoint ou manage_inference_endpoint.

API REST

Voici un exemple d’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"'"]}]'

Python

Voici un exemple 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}")

Après avoir extrait le jeton OAuth, interrogez votre point de terminaison à l’aide de votre URL de point de terminaison et du jeton OAuth.

API REST

Voici un exemple d’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"

Python

Voici un exemple 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)