Запрос оптимизированных для маршрутизации конечных точек обслуживания

В этой статье описывается, как получить соответствующие учетные данные проверки подлинности и URL-адрес, чтобы можно было запросить конечную точку обслуживания модели, оптимизированной для маршрута, или конечной точки обслуживания компонентов .

Требования

• Модель, обслуживающая конечную точку или конечную точку обслуживания компонентов, включающую оптимизацию маршрута. См. статью "Оптимизация маршрутов" для конечных точек обслуживания.
• Запросы к конечным точкам, оптимизированным для маршрутов, поддерживают использование только маркеров OAuth. Персональные токены доступа не поддерживаются.

Быстрый старт: сценарий сквозного запроса

Следующий рецепт объединяет каждый шаг, необходимый для запроса конечной точки, оптимизированной для маршрута, из внешнего клиента в единый поток запуска. Используйте этот раздел, если вы хотите быстро проверить рабочую настройку. Дополнительные сведения о каждом шаге см. в следующих разделах.

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

Получение URL-адреса, оптимизированного для маршрутизации

При создании оптимизированной для маршрута конечной точки для конечной точки создается следующий URL-адрес, оптимизированный для маршрута.

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

Этот URL-адрес можно получить из следующего:

Обслуживающий пользовательский интерфейс

REST API

GET /api/2.0/serving-endpoints/{name} Используйте вызов API. URL-адрес присутствует в объекте ответа конечной точки как endpoint_url. Это поле заполняется только в том случае, если конечная точка оптимизирована для маршрутизации.

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

Databricks SDK

Используйте вызов Serving Endpoints API get. URL-адрес присутствует в объекте ответа конечной точки как endpoint_url. Это поле заполняется только в том случае, если конечная точка оптимизирована для маршрутизации.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Получение маркера OAuth и запрос конечной точки

Чтобы запросить конечную точку, оптимизированную для маршрута, необходимо использовать маркер OAuth. Databricks рекомендует использовать субъекты-службы в рабочих приложениях для программного получения маркеров OAuth. В следующих разделах описаны рекомендации по получению токена OAuth для тестовых и производственных сценариев.

Получение маркера OAuth с помощью интерфейса обслуживания

Ниже показано, как получить маркер в пользовательском интерфейсе обслуживания. Эти действия рекомендуется для разработки и тестирования конечной точки.

Для использования в рабочей среде, например с помощью конечной точки, оптимизированной для маршрутизации в приложении, токен извлекается с помощью служебного принципала. Ознакомьтесь с рекомендациями по программному получению токена OAuth для рабочих вариантов использования.

Из пользовательского интерфейса служебного раздела вашей рабочей области:

1. На странице "Обслуживание конечных точек" выберите конечную точку, оптимизированную для маршрута, чтобы просмотреть сведения о конечной точке.
2. На странице сведений о конечной точке нажмите кнопку "Использовать ".
3. Выберите вкладку Получение токена.
4. Нажмите кнопку Получить маркер 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:

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. Эти токены используются для запроса конечных точек, оптимизированных по маршруту.

Выполните действия, описанные в разделе "Авторизация доступа субъекта-службы к Azure Databricks" с помощью OAuth на шаге 2, чтобы создать субъект-службу, назначить разрешения и создать секрет OAuth для субъекта-службы. После создания субъекта-службы необходимо предоставить субъекту-службе по крайней мере разрешение запроса на конечную точку. См. раздел "Управление разрешениями" в конечной точке обслуживания модели.

Пакет SDK для Python Databricks предоставляет API для прямого запроса к оптимизированной для маршрута конечной точке.

В следующем примере требуется выполнить запрос к конечной точке, оптимизированной для маршрутизации, с помощью пакета SDK Databricks:

• Имя конечной точки обслуживания (пакет SDK получает правильный URL-адрес конечной точки на основе этого имени)
• Идентификатор клиента служебного принципала
• Секрет субъекта-службы
• Имя хоста рабочей области

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 вручную

В сценариях, когда пакет SDK Databricks или пользовательский интерфейс обслуживания не может использоваться для получения маркера OAuth, вы можете вручную получить маркер OAuth. Рекомендации в этом разделе в основном относятся к сценариям, в которых у пользователей есть настраиваемый клиент, который они хотят использовать для запроса конечной точки в рабочей среде.

При получении маркера OAuth вручную необходимо указать authorization_details в запросе.

• Создайте <token-endpoint-URL>, заменив https://<databricks-instance> на URL-адрес рабочей области вашего развертывания Databricks в https://<databricks-instance>/oidc/v1/token. Например: https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• Замените <client-id> идентификатором клиента субъекта-службы, который также называется идентификатором приложения.
• Замените <client-secret>, введя созданный секрет OAuth для учетной записи службы.

• Замените <endpoint-id> идентификатором конечной точки, оптимизированной для маршрута. Это альфа-числовый идентификатор конечной точки, которую можно найти в hostName URL-адресе конечной точки. Например, если конечная точка обслуживания является https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test, идентификатор конечной точки имеет значение abcdefg.

• Замените <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>  # 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:

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:

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‑токены рабочего пространства. Они должны использовать субъект-службу с потоком OAuth M2M и включать authorization_details в запрос токена. Последовательность действий:

1. Создайте сервисный субъект на уровне аккаунта и его секрет OAuth. См Авторизация доступа сервисного принципала к Azure Databricks с помощью OAuth.
2. Назначьте субъект-службу для рабочей области и предоставьте ей CAN_QUERY для конечной точки.
3. В приложении создайте токен, ограниченный конечной точкой, вызвав POST <workspace-host>/oidc/v1/token с учетными данными субъекта-службы и указав в authorization_details идентификатор конечной точки. См. инструкции по получению токена OAuth вручную.
4. Вызовите URL-адрес, оптимизированный для маршрута, с помощью полученного маркера.

В приведенном выше разделе быстрого запуска содержится один скрипт, который охватывает каждый шаг.

Troubleshooting