Pontos de extremidade de serviço otimizados para rota de consulta

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 para rota ou ponto de extremidade de serviço de recurso .

Requerimentos

• Um endpoint de fornecimento de modelo ou um endpoint de fornecimento de recurso que tem a otimização de rotas habilitada. Consulte Otimização de rotas em pontos de extremidade de serviço.
• Consultar pontos de extremidade otimizados por rota suporta apenas o uso de tokens OAuth. Não há suporte para tokens de acesso pessoal.

Buscar o URL otimizado da rota

Quando se cria um endpoint otimizado para rota, a seguinte URL otimizada para rota é criada para esse endpoint.

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

Pode obter este URL a partir do seguinte:

Servindo a interface do usuário

API REST

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

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

Databricks SDK

Use uma Serving Endpoints API get chamada. A URL está presente no objeto de resposta do endpoint como endpoint_url. Este campo só será preenchido se o ponto de extremidade estiver otimizado por 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 seu endpoint otimizado por rota, deve usar um token OAuth. O Databricks recomenda o uso de entidades de serviço em seus aplicativos de produção para buscar tokens OAuth programaticamente. As seções a seguir descrevem orientações recomendadas sobre como buscar um token OAuth para cenários de teste e produção.

Buscar um token OAuth usando a UI de Servidores

As etapas a seguir mostram como buscar um token na interface do usuário de serviço. Essas etapas são recomendadas para desenvolver e testar seu endpoint.

Para utilização em produção, como a utilização do seu ponto final otimizado para rota numa aplicação, o seu token é obtido usando um principal de serviço. Consulte Buscar um token OAuth programaticamente para obter orientações recomendadas para buscar seu token OAuth para casos de uso de produção.

Na interface do usuário de Serving do seu espaço de trabalho:

1. Na página Pontos de serviço, selecione o ponto de extremidade otimizado para rota para visualizar os detalhes do ponto de extremidade.
2. Na página de detalhes do ponto final, selecione o botão Usar .
3. Selecione o separador Obter Token.
4. Selecione o botão Buscar token OAuth. Este token é válido por 1 hora. Buscar 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

Segue-se 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

A seguir está um exemplo de 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 principais de serviço para incorporar na sua aplicação, de forma a buscar programaticamente tokens de autenticação OAuth. Esses 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 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 a permissão Consulta no ponto de extremidade. Consulte Gerir permissões num endpoint de disponibilização de modelo.

O Databricks Python SDK fornece uma API para consultar diretamente um ponto de extremidade otimizado para rotas.

O próximo exemplo requer o seguinte para interrogar um endpoint otimizado para rotas usando o SDK do Databricks:

• Servindo o nome do ponto de extremidade (o SDK busca a URL correta do ponto de extremidade com base nesse nome)
• ID do cliente principal do serviço
• Segredo principal do 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 aplicam-se principalmente a cenários onde os utilizadores têm um cliente personalizado que desejam usar para realizar consultas ao endereço de destino em ambiente de produção.

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

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

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

• Substitua <endpoint-id> pelo ID do ponto de extremidade otimizado para rota. Este é o ID alfanumérico do ponto de extremidade que você pode encontrar no hostName 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, o ID do ponto de extremidade 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.

API REST

Segue-se 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

A seguir está um exemplo de 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

Segue-se 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

A seguir está um exemplo de 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)