Zapytania dotyczące puntów końcowych zoptymalizowanych pod kątem trasy

W tym artykule opisano sposób pobierania odpowiednich poświadczeń uwierzytelniania i adresu URL, dzięki czemu można wykonywać zapytania dotyczące modelu zoptymalizowanego pod kątem trasy obsługującego lub obsługującego funkcję punktu końcowego.

Wymagania

• Modelowy punkt obsługi końcowej lub punkt obsługi funkcji z włączoną optymalizacją tras. Zobacz Optymalizacja tras w przypadku obsługi punktów końcowych.
• Wykonywanie zapytań dotyczących punktów końcowych zoptymalizowanych pod kątem tras obsługuje się wyłącznie za pomocą tokenów OAuth. Osobiste tokeny dostępu nie są obsługiwane.

Pobieranie adresu URL zoptymalizowanego pod kątem trasy

Podczas tworzenia punktu końcowego zoptymalizowanego pod kątem trasy dla punktu końcowego zostanie utworzony następujący adres URL zoptymalizowany pod kątem trasy.

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

Ten adres URL można uzyskać z następujących elementów:

Dostarczanie interfejsu użytkownika

interfejs API REST

Użyj wywołania funkcji API GET /api/2.0/serving-endpoints/{name}. Adres URL znajduje się w obiekcie odpowiedzi punktu końcowego jako endpoint_url. To pole jest wypełniane tylko wtedy, gdy punkt końcowy jest zoptymalizowany pod kątem trasy.

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

Databricks SDK

Użyj wywołania Serving Endpoints API get . Adres URL znajduje się w obiekcie odpowiedzi punktu końcowego jako endpoint_url. To pole jest wypełniane tylko wtedy, gdy punkt końcowy jest zoptymalizowany pod kątem trasy.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Pobieranie tokenu OAuth i wykonywanie zapytań względem punktu końcowego

Aby wykonać zapytanie dotyczące punktu końcowego zoptymalizowanego pod kątem trasy, należy użyć tokenu OAuth. Databricks zaleca używanie jednostek usługi w aplikacjach produkcyjnych do programowego pobierania tokenów OAuth. W poniższych sekcjach opisano zalecane wskazówki dotyczące pobierania tokenu OAuth na potrzeby scenariuszy testowych i produkcyjnych.

Pobierz token OAuth, używając interfejsu użytkownika serwującego

W poniższych krokach pokazano, jak pobrać token w interfejsie użytkownika obsługującego. Te kroki są zalecane do programowania i testowania punktu końcowego.

W przypadku użycia w środowisku produkcyjnym, na przykład gdy aplikacja korzysta z punktu końcowego zoptymalizowanego pod kątem trasy, token jest pobierany przy użyciu zasobu usługi. Zobacz Programowe pobieranie tokenu OAuth , aby uzyskać zalecane wskazówki dotyczące pobierania tokenu OAuth na potrzeby przypadków użycia w środowisku produkcyjnym.

Z poziomu interfejsu użytkownika obsługującego obszar roboczy:

1. Na stronie Obsługa punktów końcowych wybierz punkt końcowy zoptymalizowany pod kątem trasy, aby wyświetlić szczegóły punktu końcowego.
2. Na stronie szczegółów punktu końcowego wybierz przycisk Użyj .
3. Wybierz zakładkę Pobieranie tokenu.
4. Wybierz przycisk Pobierz token OAuth. Ten token jest ważny przez 1 godzinę. Pobierz nowy token, jeśli bieżący token wygaśnie.

Po pobraniu tokenu OAuth wykonaj zapytanie dotyczące punktu końcowego przy użyciu adresu URL punktu końcowego i tokenu OAuth.

interfejs API REST

Poniżej przedstawiono przykład interfejsu 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

Oto przykład języka 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)

Programowe pobieranie tokenu OAuth

W przypadku scenariuszy produkcyjnych Databricks zaleca skonfigurowanie zasadniczych instancji usługi, które można osadzić w aplikacji, aby programowo pobierać tokeny OAuth. Te pobrane tokeny są używane do wykonywania zapytań dotyczących punktów końcowych zoptymalizowanych pod kątem tras.

Wykonaj kroki opisane w temacie Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth do kroku 2, aby utworzyć jednostkę usługi, przypisać uprawnienia i utworzyć tajemnicę OAuth dla jednostki usługi. Po utworzeniu jednostki usługi należy nadać jednostce usługi co najmniej uprawnienie Zapytanie w punkcie końcowym. Zobacz Zarządzanie uprawnieniami w punkcie końcowym obsługującym model.

Zestaw SDK języka Python usługi Databricks udostępnia interfejs API do bezpośredniego wysyłania zapytań do punktu końcowego zoptymalizowanego pod kątem trasy.

W następnym przykładzie wymagane jest wykonanie następujących zapytań względem punktu końcowego zoptymalizowanego pod kątem trasy przy użyciu zestawu SDK usługi Databricks:

• Obsługa nazwy punktu końcowego (zestaw SDK pobiera prawidłowy adres URL punktu końcowego na podstawie tej nazwy)
• Identyfikator klienta podmiotu usługi
• Tajemnica głównego konta usługi
• Nazwa hosta obszaru roboczego

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ęczne pobieranie tokenu OAuth

W przypadku scenariuszy, w których nie można użyć zestawu SDK usługi Databricks lub interfejsu użytkownika obsługującego do pobrania tokenu OAuth, możesz ręcznie pobrać token OAuth. Wskazówki zawarte w tej sekcji dotyczą głównie scenariuszy, w których użytkownicy mają dostosowanego klienta, którego chcą używać do wykonywania zapytań dotyczących punktu końcowego w środowisku produkcyjnym.

Podczas ręcznego pobierania tokenu OAuth należy określić authorization_details w żądaniu.

• Skonstruuj konstrukcję <token-endpoint-URL> , zastępując ciąg https://<databricks-instance> adresem URL obszaru roboczego wdrożenia Databricks w https://<databricks-instance>/oidc/v1/token. Na przykład https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Zastąp <client-id> element identyfikatorem klienta jednostki usługi, który jest również nazywany identyfikatorem aplikacji.
• Zastąp element <client-secret> tajnym kluczem OAuth principal serwisu, który został utworzony.

• Zastąp <endpoint-id> identyfikatorem zoptymalizowanego pod kątem trasy punktu końcowego. Jest to alfanumeryczny identyfikator punktu końcowego, który można znaleźć w hostName adresie URL punktu końcowego. Jeśli na przykład obsługujący punkt końcowy to https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, identyfikator punktu końcowego to abcdefg.

• Zastąp <action> element uprawnieniem akcji nadanymi jednostce usługi. Akcja może mieć wartość query_inference_endpoint lub manage_inference_endpoint.

interfejs API REST

Poniżej przedstawiono przykład interfejsu 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

Oto przykład języka 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}")

Po pobraniu tokenu OAuth wykonaj zapytanie dotyczące punktu końcowego przy użyciu adresu URL punktu końcowego i tokenu OAuth.

interfejs API REST

Poniżej przedstawiono przykład interfejsu 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

Oto przykład języka 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)