Consultar o ponto de extremidade de serviço otimizado da rota

Este artigo descreve como obter as credenciais de autenticação e o URL apropriados para que o senhor possa consultar sua rota otimizada servindo modelo ou Feature Serving endpoint.

Requisitos

• Um modelo de serviço endpoint ou Feature Serving endpoint que tenha a otimização de rota ativada, consulte Otimização de rota no endpoint de serviço.
• Tokens de autenticação. O ponto de extremidade com otimização de rota suporta apenas OAuth tokens, o acesso pessoal tokens não é suportado.

Busque o URL otimizado da rota

Quando o senhor cria um endpoint otimizado para rota, é criado um URL otimizado para rota exclusivo para o seu endpoint. O ponto de extremidade otimizado de rota só pode ser consultado usando seu URL dedicado. O formato do URL é o seguinte:

https://<unique-id>.serving.cloud.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

Você pode obter esse URL de uma das seguintes opções:

• Usando a GET /api/2.0/serving-endpoints/{name} API call. O URL está presente no objeto de resposta do site endpoint como endpoint_url. Esse campo só é preenchido se o site endpoint for otimizado para rota.

• A página de detalhes do endpoint de atendimento na interface de usuário de atendimento.

Obtenha um OAuth tokens e consulte o endpoint

Para consultar sua rota otimizada em endpoint, o senhor deve usar um token OAuth. Databricks recomenda o uso da entidade de serviço em seus aplicativos de produção para buscar o site OAuth tokens de forma programática. As seções a seguir descrevem as orientações recomendadas sobre como obter tokens OAuth para cenários de teste e produção.

Obtenha tokens OAuth usando a UI de serviço

As etapas a seguir mostram como buscar tokens na UI de serviço. Essas etapas são recomendadas para desenvolver e testar seu endpoint.

Para uso em produção, como usar sua rota otimizada endpoint em um aplicativo, seus tokens são obtidos usando uma entidade de serviço. Consulte Obter tokens OAuth programaticamente para obter orientações recomendadas sobre como obter tokens OAuth para casos de uso de produção.

Na interface de usuário de serviço do site workspace:

1. Na página Serving endpoint, selecione sua rota otimizada endpoint para ver os detalhes de endpoint.
2. Na página de detalhes do endpoint, selecione o botão Usar .
3. Selecione Fetch tokens tab.
4. Selecione o botão Fetch OAuth tokens . Esses tokens são válidos por 1 hora. Obtenha novos tokens se os tokens atuais expirarem.

Depois de obter os tokens OAuth, consulte o site endpoint usando o URL endpoint e os tokens OAuth.

REST API

A seguir, um exemplo de API REST:

Bash

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 seguir, um exemplo em Python:

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)

Obter um OAuth tokens programaticamente

Para cenários de produção, o site Databricks recomenda a configuração de uma entidade de serviço para ser incorporada ao seu aplicativo para buscar programaticamente OAuth tokens. Esses dados obtidos em tokens são usados para consultar o ponto final otimizado da rota.

Siga as etapas em Authorize entidade de serviço access to Databricks with OAuth até a etapa 2 para criar sua entidade de serviço, atribuir permissões e criar um segredo OAuth para sua entidade de serviço. Depois que sua entidade de serviço for criada, o senhor deve conceder à entidade de serviço pelo menos a permissão de consulta no site endpoint. Consulte gerenciar permissões em seu modelo de serviço endpoint.

A Databricks Python SDK fornece um API para consultar diretamente uma rota otimizada endpoint.

nota

O SDK da Databricks também está disponível em Go, consulte SDK da Databricks para Go.

O exemplo requer o seguinte para consultar um endpoint otimizado para rota usando o SDK da Databricks:

• Nome do endpoint de serviço (o SDK busca o URL correto do endpoint com base nesse nome)
• ID do cliente principal do serviço
• Segredo principal do serviço
• nome do host do espaço de trabalho

Veja a seguir um exemplo de consulta:

Python

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

Obter um OAuth tokens manualmente

Em cenários em que o Databricks SDK ou a Serving UI não podem ser usados para obter os tokens OAuth, o senhor pode obter manualmente os tokens OAuth. As orientações desta seção se aplicam principalmente a cenários em que os usuários têm um cliente personalizado que desejam usar para consultar o endpoint na produção.

Quando o senhor busca manualmente os tokens OAuth, deve especificar authorization_details na solicitação.

• Construa o <token-endpoint-URL> substituindo https://<databricks-instance> pelo URL workspace da sua implantação Databricks em https://<databricks-instance>/oidc/v1/token. Por exemplo, https://my-workspace.cloud.databricks.com/oidc/v1/token

• Substitua <client-id> pela ID do cliente da entidade de serviço, que também é conhecida como ID do aplicativo.

• Substitua <client-secret> pelo segredo OAuth da entidade de serviço que o senhor criou.

• Substitua <endpoint-id> pelo ID endpoint da rota otimizada endpoint. Este é o ID alfanumérico do endpoint, que pode ser encontrado em hostName do URL do endpoint. Por exemplo, se o endpoint de serviço for https://abcdefg.serving.cloud.databricks.com/9999999/serving-endpoints/test, o ID do endpoint será abcdefg.

• Substitua <action> pela permissão de ação dada à entidade de serviço. A ação pode ser query_inference_endpoint ou manage_inference_endpoint.

REST API

A seguir, um exemplo de API REST:

Bash

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

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

Depois de obter os tokens OAuth, consulte o site endpoint usando o URL endpoint e os tokens OAuth.

REST API

A seguir, um exemplo de API REST:

Bash

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 seguir, um exemplo em Python:

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)