Consultar puntos de conexión de servicio optimizados por ruta

En este artículo se describe cómo obtener las credenciales de autenticación y la URL adecuadas para que puedas consultar tu punto de conexión de Modelo de servicios o servicio de características optimizado por ruta.

Requisitos

• Un extremo de servicio de modelo o un extremo de servicio de características que tiene habilitada la optimización de rutas. Consulte Optimización de rutas en los puntos de conexión de servicio.
• La consulta de puntos de conexión optimizados para rutas solo admite el uso de tokens de OAuth. No se admiten tokens de acceso personal.

Inicio rápido: receta de consulta de extremo a extremo

La siguiente receta combina todos los pasos necesarios para consultar un punto de conexión optimizado para rutas desde un cliente externo en un único flujo ejecutable. Use esta sección si desea comprobar rápidamente una configuración de trabajo. Consulte las secciones siguientes para obtener más detalles sobre cada paso.

# 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"

Obtén la URL optimizada para rutas

Al crear un punto de conexión optimizado para rutas, se crea la siguiente dirección URL optimizada para rutas para el punto de conexión.

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

Puede obtener esta dirección URL de la siguiente manera:

Interfaz de usuario de servicio

API DE REST

Utilice la llamada a la API GET /api/2.0/serving-endpoints/{name}. La dirección URL está presente en el objeto de respuesta del punto de conexión como endpoint_url. Este campo solo se rellena si el punto de conexión está optimizado por ruta.

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

SDK de Databricks

Realice la Serving Endpoints API get llamada. La dirección URL está presente en el objeto de respuesta del punto de conexión como endpoint_url. Este campo solo se rellena si el punto de conexión está optimizado por ruta.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Capturar un token de OAuth y consultar el punto de conexión

Para consultar el punto de conexión optimizado para rutas, debe usar un token de OAuth. Databricks recomienda usar entidades de servicio en las aplicaciones de producción para obtener tokens de OAuth de manera programada. En las secciones siguientes se describen las instrucciones recomendadas sobre cómo capturar un token de OAuth para escenarios de prueba y producción.

Obtén un token OAuth mediante la interfaz gráfica del servicio

Los pasos siguientes muestran cómo capturar un token en la interfaz de usuario de servicio. Estos pasos se recomiendan para el desarrollo y las pruebas del punto de conexión.

Para uso en producción, como al utilizar su punto de conexión optimizado para rutas en una aplicación, su token se obtiene mediante una entidad de servicio. Consulte Captura de un token de OAuth mediante programación para obtener instrucciones recomendadas para capturar el token de OAuth para casos de uso de producción.

En la interfaz de usuario de servicio del área de trabajo:

1. En la página Puntos de conexión en servicio, selecciona tu punto de conexión optimizado para rutas para ver los detalles del mismo.
2. En la página de detalles del punto de conexión, seleccione el botón Usar .
3. Seleccione la pestañaFetch Token (Capturar token).
4. Seleccione botón Capturar token de OAuth. Este token tiene una validez de 1 hora. Capture un nuevo token si expira el token actual.

Después de capturar el token de OAuth, consulte el punto de conexión mediante la dirección URL del punto de conexión y el token de OAuth.

API DE REST

A continuación se muestra un ejemplo 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"

Pitón

A continuación se muestra un ejemplo 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)

Captura de un token de OAuth mediante programación

En escenarios de producción, Databricks recomienda configurar entidades de servicio para integrarlas en su aplicación y obtener tokens de OAuth mediante programación. Estos tokens recuperados se utilizan para consultar los puntos de conexión optimizados para rutas.

Siga los pasos descritos en Autorización del acceso de la entidad de servicio a Azure Databricks con OAuth en el paso 2 para crear la entidad de servicio, asignar permisos y crear un secreto de OAuth para la entidad de servicio. Una vez creada la entidad de servicio, debe conceder al menos permiso de consulta a la entidad de servicio en el punto de conexión. Consulte Administrar permisos en un punto de conexión para servir modelos.

El SDK de Python de Databricks proporciona una API para consultar directamente un punto de conexión optimizado para rutas.

En el ejemplo siguiente se requiere lo siguiente para consultar un punto de conexión optimizado para rutas mediante el SDK de Databricks:

• Servicio del nombre del punto de conexión (el SDK captura la dirección URL del punto de conexión correcta en función de este nombre)
• Id. de cliente de la entidad de servicio
• Secreto de la entidad de servicio
• Nombre de host del área de trabajo

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

Captura manual de un token de OAuth

En escenarios en los que el SDK de Databricks o la interfaz de usuario de servicio no se pueden usar para capturar el token de OAuth, puede capturar manualmente un token de OAuth. Las instrucciones de esta sección se aplican principalmente a escenarios en los que los usuarios tienen un cliente personalizado que quieren usar para consultar el punto de conexión en producción.

Al capturar manualmente un token de OAuth, debe especificar authorization_details en la solicitud.

• Construya el <token-endpoint-URL> reemplazando https://<databricks-instance> con la URL del área de trabajo de su implementación de Databricks en https://<databricks-instance>/oidc/v1/token. Por ejemplo: https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Reemplace por <client-id> el identificador de cliente de la entidad de servicio, que también se conoce como identificador de aplicación.
• Reemplace <client-secret> por el secreto de OAuth de la entidad de servicio que creó.

• Sustituye <endpoint-id> por el ID del punto de conexión optimizado para rutas. Este es el identificador alfanumérico del punto de conexión que puede encontrar en la hostName dirección URL del punto de conexión. Por ejemplo, si el punto de conexión de servicio es https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, el identificador del punto de conexión es abcdefg.

• Reemplace <action> por el permiso de acción concedido a la entidad de servicio. La acción puede ser query_inference_endpoint o manage_inference_endpoint.

API DE REST

A continuación se muestra un ejemplo 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"'"]}]'

Pitón

A continuación se muestra un ejemplo 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}")

Después de capturar el token de OAuth, consulte el punto de conexión mediante la dirección URL del punto de conexión y el token de OAuth.

API DE REST

A continuación se muestra un ejemplo 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"

Pitón

A continuación se muestra un ejemplo 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)

Llamada desde un agente de IA o una aplicación externa

Los asistentes de codificación de IA y las aplicaciones externas que consultan puntos de conexión optimizados para rutas no pueden usar el token de acceso personal o los tokens de OAuth del área de trabajo del desarrollador. Deben utilizar una entidad de servicio con el flujo OAuth M2M e incluir authorization_details en la solicitud de token. El flujo es:

1. Cree un principal de servicio a nivel de cuenta y un secreto de OAuth para este. Consulte Autorización del acceso de entidad de servicio a Azure Databricks con OAuth.
2. Asigna la entidad de servicio al espacio de trabajo y concédele CAN_QUERY en el punto de conexión.
3. Desde la aplicación, genera un token con ámbito de punto de conexión llamando a POST <workspace-host>/oidc/v1/token con las credenciales de la entidad de servicio y authorization_details haciendo referencia al ID del punto de conexión. Consulte Captura manual de un token de OAuth.
4. Invoque la dirección URL optimizada para rutas con el token resultante.

La sección Inicio rápido anterior contiene un único script pegable que cubre todos los pasos.

Troubleshooting