查询路由优化的服务终结点

2025-05-30

本文介绍如何提取适当的身份验证凭据和 URL，以便查询路由优化的模型服务或功能服务终结点。

要求

启用路由优化的模型服务终结点或功能服务终结点，请参阅服务终结点的路由优化。
身份验证令牌。路由优化的终结点仅支持 OAuth 令牌，不支持个人访问令牌。

提取路由优化的 URL

创建路由优化终结点时，将为终结点创建唯一的路由优化 URL。只能使用其专用 URL 查询路由优化终结点。 URL 的格式如下所示：

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

可以从以下任一项获取此 URL：

使用GET /api/2.0/serving-endpoints/{name} API 调用。 URL 存在于终结点的响应对象中，如下所示 endpoint_url。仅当路由端点经过路线优化时，才会填充此字段。
服务 UI 中的服务终结点详细信息页。

路由优化的终结点 URL

提取 OAuth 令牌并查询终结点

若要查询路由优化终结点，必须使用 OAuth 令牌。 Databricks 建议在生产应用程序中使用服务主体以编程方式提取 OAuth 令牌。以下部分介绍了有关如何为测试和生产方案提取 OAuth 令牌的建议指南。

使用 Serving UI 获取 OAuth 令牌

以下步骤演示如何在服务 UI 中提取令牌。建议使用这些步骤进行开发和测试终结点。

对于生产用途，例如在应用程序中使用路由优化的终结点，标记是通过服务主体提取的。有关获取用于生产用例的 OAuth 令牌的建议指南，请参阅以编程方式提取 OAuth 令牌。

从工作区的服务 UI 中：

在“服务终结点”页上，选择路由优化的终结点以查看终结点详细信息。
在终结点详细信息页上，选择“ 使用 ”按钮。
选择“提取令牌”选项卡。
选择“提取 OAuth 令牌”按钮。此令牌的有效期为 1 小时。如果当前令牌过期，则提取新令牌。

获取 OAuth 令牌后，使用您的终结点 URL 和 OAuth 令牌来查询终结点。

REST API

下面是 REST API 示例：


URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

Python语言

下面是 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)

以编程方式提取 OAuth 令牌

对于生产场景，Databricks 建议设置服务主体嵌入到应用程序中，以编程方式提取 OAuth 标记。这些提取的标记用于查询路由优化的终结点。

按照使用 OAuth 通过服务主体授权以无人参与方式访问 Azure Databricks 资源中的步骤操作，直至完成步骤 2，以创建服务主体、分配权限并为服务主体创建 OAuth 机密。创建服务主体后，必须至少授予服务主体对终结点的 查询权限 。请参阅管理模型服务终结点的权限。

Databricks Python SDK 提供 API 来直接查询路由优化终结点。

注释

Databricks SDK 在 Go 中也可用，请参阅 Databricks SDK for Go。

要查询使用 Databricks SDK 的路线优化终结点，此示例需要执行以下步骤：

提供终结点名称（SDK 基于此名称提取正确的终结点 URL）
服务主体客户端 ID
服务主体机密
工作区主机名

下面是一个查询示例：

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

手动提取 OAuth 标记

对于无法使用 Databricks SDK 或服务 UI 提取 OAuth 标记的场景，可以手动提取 OAuth 标记。本节指南主要适用于用户在生产环境中使用自定义客户端查询终结点的场景。

手动提取 OAuth 令牌时，必须在请求中指定 authorization_details 。

通过将 <token-endpoint-URL> 替换为 Databricks 部署的工作区 URL 来构造 https://<databricks-instance>。例如，https://<databricks-instance>/oidc/v1/token。
将 <client-id> 替换为服务主体的客户端 ID（也称为应用程序 ID）。
将 <client-secret> 替换为你创建的服务主体的 OAuth 机密。
将 <endpoint-id> 替换为路由优化终结点的终结点 ID。这是终结点的字母数字 ID，可以在终结点 URL 的 hostName 中找到它。
将 <action> 替换为向服务主体授予的操作权限。该操作可以是 query_inference_endpoint 或 manage_inference_endpoint。

REST API

下面是 REST API 示例：



export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>
export ENDPOINT_ID=<endpoint-id>
export ACTION=<action>

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语言

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}")

获取 OAuth 令牌后，使用您的终结点 URL 和 OAuth 令牌来查询终结点。

REST API

下面是 REST API 示例：


URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

Python语言

下面是 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)

通过

查询路由优化的服务终结点

要求

提取路由优化的 URL

提取 OAuth 令牌并查询终结点

使用 Serving UI 获取 OAuth 令牌

REST API

Python语言

以编程方式提取 OAuth 令牌

手动提取 OAuth 标记

REST API

Python语言

REST API

Python语言

反馈

其他资源