Consultar endpoints de serviço com rota otimizada

Este artigo descreve como buscar as credenciais de autenticação e a URL apropriadas para que você possa consultar seu modelo de serviço otimizado por rota ou o endpoint de serviço de recursos.

Requisitos

• Um endpoint de serviço de modelo ou endpoint de serviço de funcionalidade que tem a otimização de rota habilitada. Otimização de rota em pontos de extremidade do serviço.
• A consulta de endpoints otimizados por rota suporta apenas o uso de tokens OAuth. Não há suporte para tokens de acesso pessoal.

Buscar a URL com otimização de rota

Quando você cria um ponto de extremidade com otimização de rota, a URL com otimização de rota a seguir é criada para o ponto de extremidade.

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

Você pode obter essa URL a partir do seguinte:

Interface do usuário de serviço

API REST

Use a chamada à GET /api/2.0/serving-endpoints/{name} API. A URL está presente no objeto de resposta do endpoint como endpoint_url. Esse campo só será preenchido se o ponto de extremidade for otimizado para rota.

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

SDK do Databricks

Use a Serving Endpoints API get chamada. A URL está presente no objeto de resposta do endpoint como endpoint_url. Esse campo só será preenchido se o ponto de extremidade for otimizado para rota.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Buscar um token OAuth e consultar o endpoint

Para consultar o ponto de extremidade com otimização de rota, você deve usar um token OAuth. Databricks recomenda usar principais de serviço em seus aplicativos de produção para buscar tokens OAuth programaticamente. As seções a seguir descrevem as diretrizes recomendadas sobre como buscar um token OAuth para cenários de teste e produção.

Buscar um token OAuth usando a IU de Serviço

As etapas a seguir mostram como buscar um token na interface do usuário de serviço. Estas etapas são recomendadas para o desenvolvimento e teste do ponto de extremidade.

Para uso em produção, como no uso do endpoint otimizado para rota em um aplicativo, o token é buscado usando um principal de serviço. Consulte Buscar um token OAuth programaticamente para obter diretrizes recomendadas para buscar seu token OAuth para casos de uso de produção.

Na IU de Serviço do espaço de trabalho:

1. Na página Pontos de Extremidade de Servimento, selecione o ponto de extremidade otimizado por rota para ver os detalhes.
2. Na página de detalhes do ponto de extremidade, selecione o botão Usar.
3. Selecione a guia Fetch Token.
4. Selecione o botão Buscar Token OAuth. Esse token é válido por 1 dias. Busque um novo token se o token atual expirar.

Depois de buscar o token OAuth, consulte seu ponto de extremidade usando a URL do ponto de extremidade e o token OAuth.

API REST

Veja a seguir um exemplo de 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

Veja a seguir um exemplo do 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)

Buscar um token OAuth programaticamente

Para cenários de produção, o Databricks recomenda configurar entidades de serviço para inserir no seu aplicativo e buscar tokens OAuth programaticamente. Os tokens buscados são usados para consultar endpoints otimizados para rotas.

Siga as etapas em Autorizar o acesso da entidade de serviço ao Azure Databricks com o 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 a entidade de serviço for criada, você deverá conceder à entidade de serviço pelo menos permissão de Consulta no ponto de extremidade. Consulte Gerenciar permissões em um endpoint de servir modelo.

O Python SDK do Databricks fornece uma API para consultar diretamente um endpoint otimizado para rota.

O próximo exemplo requer o seguinte para consultar um endpoint otimizado por rota por meio do SDK do Databricks:

• Nome do ponto de extremidade de serviço (o SDK busca a URL de ponto de extremidade correta com base nesse nome)
• ID do cliente principal de serviço
• Segredo da entidade de serviço
• Nome do host do espaço de trabalho

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 token OAuth manualmente

Para cenários em que o SDK do Databricks ou a interface do usuário de serviço não podem ser usados para buscar seu token OAuth, você pode buscar manualmente um token OAuth. As orientações nesta 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 em produção.

Ao buscar um token OAuth manualmente, você deve especificar authorization_details na solicitação.

• Construa a <token-endpoint-URL> substituindo https://<databricks-instance> pela URL do workspace da sua implantação do Databricks em https://<databricks-instance>/oidc/v1/token. Por exemplo, https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Substitua <client-id> pela ID de cliente da entidade de serviço, também é conhecida como ID de aplicativo.
• Substitua <client-secret> pelo segredo do OAuth da entidade de serviço que você criou.

• Substitua <endpoint-id> pela ID do ponto de extremidade com otimização de rota. Esta é a ID alfanumérica do ponto de extremidade que pode ser encontrado na hostName da URL do ponto de extremidade. Por exemplo, se o ponto de extremidade de serviço for https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, a ID do ponto de extremidade será abcdefg.

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

API REST

Veja a seguir um exemplo de 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

Veja a seguir um exemplo do 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 buscar o token OAuth, consulte seu ponto de extremidade usando a URL do ponto de extremidade e o token OAuth.

API REST

Veja a seguir um exemplo de 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

Veja a seguir um exemplo do 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)