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.

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

A receita seguinte combina todos os passos necessários para consultar um endpoint otimizado para rotas a partir de um cliente externo num único fluxo executável. Utilize esta secção se quiser verificar rapidamente uma configuração funcional. Consulte as secções seguintes para 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 o endereço URL otimizado para rotas

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

Os passos seguintes mostram como obter um token na interface do utilizador de Serving. 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. Obtenha 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)

Obter 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)

Chamadas a partir de um agente de IA ou de uma aplicação externa

Assistentes de código com IA e aplicações externas que fazem consultas a endpoints otimizados por rota não podem utilizar o token de acesso pessoal de um programador nem os tokens OAuth do espaço de trabalho. Devem usar um principal de serviço com o fluxo OAuth M2M e incluir authorization_details no pedido de token. O fluxo é:

1. Crie um principal de serviço ao nível da conta e um segredo OAuth para isso. Ver Autorizar o acesso do principal de serviço ao Azure Databricks com OAuth.
2. Atribua o principal de serviço ao espaço de trabalho e conceda-lhe CAN_QUERY no endpoint.
3. Na aplicação, crie um token limitado ao endpoint chamando POST <workspace-host>/oidc/v1/token com as credenciais do principal de serviço e authorization_details fazendo referência ao ID do endpoint. Consulte Obter um token OAuth manualmente.
4. Invoque a URL otimizada para rotas com o token resultante.

A secção de Início Rápido acima contém um único script copiável e colado que cobre cada etapa.

Troubleshooting