Consultar pontos de extremidade do serviço otimizados para rotas

Este artigo descreve como buscar as credenciais de autenticação e a URL apropriadas para que você possa consultar seu ponto de extremidade do serviço de modelo ou do serviço de recurso com otimização de rota.

Requisitos

• Um ponto de extremidade do serviço de modelo ou ponto de extremidade do serviço de recurso que tem a otimização de rota habilitada. Otimização de rota em pontos de extremidade do serviço.
• A consulta de pontos de extremidade com otimização de rota oferece suporte somente ao uso de tokens OAuth. Não há suporte para tokens de acesso pessoal.

Início rápido: receita de consulta de ponta a ponta

A receita a seguir reúne todas as etapas necessárias para consultar um endpoint otimizado para rotas a partir de um cliente externo em um único fluxo executável. Use esta seção se você quiser verificar uma configuração de trabalho rapidamente. Confira as seções a seguir para obter mais detalhes sobre cada etapa.

# 1. Set the variables for your environment.
export DATABRICKS_HOST="https://<your-workspace>.cloud.databricks.com"
export ENDPOINT_NAME="<your-endpoint>"
export WORKSPACE_ID="<workspace-id>"

# 2. Create an account-level service principal and an OAuth secret for it.
SP_ID=$(databricks account service-principals create \
  --json '{"displayName":"my-app","active":true}' --output json | jq -r '.id')
SECRET_JSON=$(databricks account service-principal-secrets create "$SP_ID" --output json)
export CLIENT_ID=$(databricks account service-principals get "$SP_ID" --output json | jq -r '.applicationId')
export CLIENT_SECRET=$(echo "$SECRET_JSON" | jq -r '.secret')

# 3. Assign the service principal to the workspace and grant CAN_QUERY on the endpoint.
databricks account workspace-assignment update "$WORKSPACE_ID" "$SP_ID" \
  --json '{"permissions":["USER"]}'
ENDPOINT_ID=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.id')
databricks permissions update serving-endpoints "$ENDPOINT_ID" \
  --json "{\"access_control_list\":[{\"service_principal_name\":\"$CLIENT_ID\",\"permission_level\":\"CAN_QUERY\"}]}"

# 4. Mint an endpoint-scoped OAuth token. `authorization_details` is required for
# route-optimized endpoints -- a plain `scope=all-apis` token is rejected with
# 401 "Missing authorization details" when used against the route-optimized URL.
TOKEN=$(curl -sS -X POST -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=all-apis" \
  --data-urlencode "authorization_details=[{\"type\":\"workspace_permission\",\"object_type\":\"serving-endpoints\",\"object_path\":\"/serving-endpoints/$ENDPOINT_ID\",\"actions\":[\"query_inference_endpoint\"]}]" \
  "$DATABRICKS_HOST/oidc/v1/token" | jq -r '.access_token')

# 5. Invoke the endpoint at its route-optimized URL.
RO_URL=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.endpoint_url')
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"inputs":[[0.12,0.34]]}' "https://$RO_URL"

Obter a URL otimizada para a 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. Este campo só será preenchido se o ponto de extremidade for otimizado para rotas.

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

SDK do Databricks

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

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. O Databricks recomenda o uso de entidades de serviço em seus aplicativos de produção para buscar tokens OAuth de forma programática. 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 usar o ponto de extremidade com otimização de rota em um aplicativo, o token é buscado usando uma entidade 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 do serviço, selecione o ponto de extremidade com otimização de rota para conferir seus 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. Esses tokens buscados são usados para consultar os pontos de extremidade com otimização de rota.

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 ponto de extremidade do Serviço de Modelo.

O SDK do Databricks do Python fornece uma API para consultar diretamente um ponto de extremidade com otimização de 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 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)

Chamada de um agente de IA ou aplicativo externo

Assistentes de codificação com IA e aplicativos externos que acessam pontos de extremidade com otimização de rota não podem usar o token de acesso pessoal de um desenvolvedor nem tokens OAuth do workspace. Eles devem usar uma entidade de serviço com o fluxo OAuth M2M e incluir authorization_details na solicitação do token. O fluxo é:

1. Crie uma entidade de serviço no nível da conta e um segredo do OAuth para ela. Consulte Autorizar acesso da entidade de serviço ao Azure Databricks usando OAuth.
2. Atribua a entidade de serviço ao workspace e conceda CAN_QUERY a ela no ponto de extremidade.
3. No aplicativo, crie um token com escopo de ponto de extremidade chamando POST <workspace-host>/oidc/v1/token com as credenciais da entidade de serviço e authorization_details referenciando a ID do ponto de extremidade. Consulte Obter um token OAuth manualmente.
4. Invoque a URL com otimização de rota com o token resultante.

A seção Início Rápido acima contém um único script que pode ser colado por cópia que abrange todas as etapas.

Troubleshooting