Compartir a través de

Consulta de puntos de conexión de servicio optimizados para rutas

En este artículo se describe cómo obtener las credenciales de autenticación y la dirección URL adecuadas para consultar su endpoint de servicio de modelo optimizado para rutas o servicio de características.

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.

Captura de la dirección URL optimizada para rutas

Advertencia

A partir del 22 de septiembre de 2025, todos los puntos de conexión optimizados para rutas recién creados deben consultarse exclusivamente a través de la dirección URL optimizada para rutas. Los puntos de conexión creados después de esta fecha no admiten la consulta a través de la dirección URL del área de trabajo.

Si el punto de conexión optimizado para rutas se creó antes del 22 de septiembre de 2025:

  • La dirección URL del área de trabajo estándar también se puede usar para consultar el punto de conexión. La ruta URL del espacio de trabajo estándar no proporciona las ventajas de la optimización de rutas.

    https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations

  • Los endpoints optimizados por ruta creados antes de esta fecha siguen admitiendo ambas URL de invocación: el camino optimizado por ruta y el camino estándar del área de trabajo.

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

dirección URL del punto de conexión optimizado para rutas

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 su uso en producción, como el uso del punto de conexión optimizado para rutas en una aplicación, el token se obtiene mediante un principal 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 de servicio, seleccione el punto de conexión optimizado para rutas para ver los detalles del punto de conexión.
  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.

Nota:

El SDK de Databricks también está disponible en Go, consulte SDK de Databricks para Go.

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ó.
  • Reemplace <endpoint-id> por el identificador de punto de conexión 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)
  • Last updated on