Rota optimize edilmiş sunum uç noktalarını sorgulama

Bu makalede, rota için iyileştirilmiş model sunumunuzu veya özellik sunma uç noktanızı sorgulayabileceğiniz uygun kimlik doğrulama kimlik bilgilerini ve URL'yi nasıl getirebileceğiniz açıklanır.

Gereksinimler

• Uç noktaya hizmet veren bir model veya rota iyileştirmesi etkinleştirilmiş uç noktaya hizmet veren özellik. Bkz. Hizmet uç noktaları üzerinde yol iyileştirme.
• Rota için iyileştirilmiş uç noktaları sorgulama yalnızca OAuth belirteçlerinin kullanılmasını destekler. Kişisel erişim belirteçleri desteklenmez.

Hızlı başlangıç: uçtan uca sorgu tarifi

Aşağıdaki örnek akış, harici bir istemci aracılığıyla rota için optimize edilmiş bir uç noktayı sorgulamak üzere gereken tüm adımları tek bir çalıştırılabilir akışta bir araya getirir. Çalışan bir kurulumu hızlı bir şekilde doğrulamak istiyorsanız bu bölümü kullanın. Her adımla ilgili daha fazla ayrıntı için aşağıdaki bölümlere bakın.

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

Rota için iyileştirilmiş URL'yi getirme

Rota için optimize edilmiş bir uç nokta oluşturduğunuzda, bu uç nokta için aşağıdaki rota için optimize edilmiş URL oluşturulur.

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

Bu URL'yi aşağıdakilerden alabilirsiniz:

Kullanıcı Arayüzü Sunma

REST API

API çağrısını GET /api/2.0/serving-endpoints/{name} kullanın. URL, uç noktanın yanıt nesnesinde olarak endpoint_urlbulunur. Bu alan yalnızca uç nokta yol için iyileştirilmişse doldurulur.

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

Databricks SDK

Serving Endpoints API get Aramayı kullanın. URL, uç noktanın yanıt nesnesinde olarak endpoint_urlbulunur. Bu alan yalnızca uç nokta yol için iyileştirilmişse doldurulur.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

OAuth belirtecini getirme ve uç noktayı sorgulama

Rota için iyileştirilmiş uç noktanızı sorgulamak için bir OAuth belirteci kullanmanız gerekir. Databricks, OAuth belirteçlerini program aracılığıyla getirmek için üretim uygulamalarınızda hizmet sorumlularının kullanılmasını önerir. Aşağıdaki bölümlerde, test ve üretim senaryoları için bir OAuth belirtecinin nasıl getirilmeye yönelik önerilen yönergeler açıklanmaktadır.

Sunucu Arayüzünü kullanarak OAuth belirteci al.

Aşağıdaki adımlar, Serving kullanıcı arayüzünde bir belirtecin nasıl alınacağını gösterir. Uç noktanızı geliştirme ve test etme için bu adımlar önerilir.

Üretim kullanımı için, örneğin rota için optimize edilmiş uç noktanızı bir uygulamada kullanırken, belirteciniz bir hizmet ilkesi kullanılarak alınır. Üretim kullanım örnekleri için OAuth belirtecinizi getirme konusunda önerilen yönergeler için OAuth belirtecini program aracılığıyla getirme bölümüne bakın.

Çalışma alanınızın Sunma kullanıcı arabiriminden:

1. Uç noktaları sunma sayfasında, uç nokta ayrıntılarını görmek için rota için iyileştirilmiş uç noktanızı seçin.
2. Uç nokta ayrıntıları sayfasında Kullan düğmesini seçin.
3. Belirteç Getir sekmesini seçin.
4. OAuth Belirtecini Getir düğmesini seçin. Bu belirteç 1 saat geçerlidir. Mevcut belirtecinizin süresi dolarsa yeni bir belirteç alın.

OAuth belirtecini getirdikten sonra uç nokta URL'nizi ve OAuth belirtecinizi kullanarak uç noktanızı sorgularsınız.

REST API

Rest API örneği aşağıda verilmiştir:

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

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

Piton

Aşağıda bir Python örneği verilmiştir:

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 belirtecini programatik olarak alma

Üretim senaryolarında, Databricks, OAuth belirteçlerini otomatik olarak almak için uygulamanızın içine yerleştirmek üzere hizmet ilkelerinin ayarlanmasını önerir. Bu getirilen belirteçler, rota için optimize edilmiş uç noktaları sorgulamak için kullanılır.

Hizmet sorumlunuzu oluşturmak, izinleri atamak ve hizmet sorumlunuz için bir OAuth gizli dizisi oluşturmak için 2. adım boyunca OAuth ile Azure Databricks'e hizmet sorumlusu erişimini yetkilendirme başlığındaki adımları izleyin. Hizmet sorumlunuz oluşturulduktan sonra hizmet sorumlusuna en azından uç noktada Sorgu izni vermeniz gerekir. Bkz. Uç noktaya hizmet veren bir model üzerindeki izinleri yönetme.

Databricks Python SDK'sı, rota için iyileştirilmiş uç noktayı doğrudan sorgulamak için bir API sağlar.

Sonraki örnek, Databricks SDK'sını kullanarak yol için iyileştirilmiş bir uç noktayı sorgulamak için aşağıdakileri gerektirir:

• Uç nokta adı sunma (SDK, bu ada göre doğru uç nokta URL'sini getirir)
• Hizmet sorumlusu istemci kimliği
• Hizmet ilkesi parolası
• Çalışma alanı ana bilgisayar adı

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 belirtecini el ile getirme

Databricks SDK'sının veya Sunum Kullanıcı Arabiriminin OAuth belirtecinizi getirmek için kullanılamadığı senaryolar için, OAuth belirtecini el ile getirebilirsiniz. Bu bölümdeki yönergeler temel olarak, kullanıcıların üretimde uç noktayı sorgulamak için kullanmak istedikleri özelleştirilmiş bir istemciye sahip olduğu senaryolar için geçerlidir.

Bir OAuth belirtecini el ile getirdiğinizde, istekte belirtmeniz authorization_details gerekir.

• Databricks dağıtımınızın çalışma alanı URL'si <token-endpoint-URL> ile https://<databricks-instance> öğesini https://<databricks-instance>/oidc/v1/token yerine koyarak oluşturun. Örneğin, https://my-workspace.0.azuredatabricks.net/oidc/v1/token

• <client-id> hizmet sorumlusunun istemci kimliğiyle, aynı zamanda uygulama kimliği olarak da bilinen, değiştirin.
• <client-secret> öğesini, oluşturduğunuz hizmet cucerisinin OAuth gizli anahtarı ile değiştirin.

• Uç nokta kimliğini rota için iyileştirilmiş uç noktanın kimliği ile değiştirin <endpoint-id>. Bu, uç nokta URL'sinde bulabileceğiniz hostName uç noktanın alfasayısal kimliğidir. Örneğin, sunum uç noktası https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/test ise, uç nokta kimliği abcdefg olur.

• <action> öğesini, hizmet sorumlusu için verilen eylem izniyle değiştirin. Eylem query_inference_endpoint veya manage_inference_endpoint olabilir.

REST API

Rest API örneği aşağıda verilmiştir:

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"'"]}]'

Piton

Aşağıda bir Python örneği verilmiştir:

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 belirtecini getirdikten sonra uç nokta URL'nizi ve OAuth belirtecinizi kullanarak uç noktanızı sorgularsınız.

REST API

Rest API örneği aşağıda verilmiştir:

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

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

Piton

Aşağıda bir Python örneği verilmiştir:

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)

Yapay zeka aracısından veya dış uygulamadan arama

Rota için iyileştirilmiş uç noktaları sorgulayan yapay zeka kodlama yardımcıları ve dış uygulamalar, bir geliştiricinin kişisel erişim belirtecini veya çalışma alanı OAuth belirteçlerini kullanamaz. OAuth M2M akışıyla bir hizmet sorumlusu kullanmaları ve belirteç isteğine authorization_details eklemeleri gerekir. Akış şöyledir:

1. Hesap düzeyinde bir hizmet sorumlusu ve bu hizmet sorumlusu için bir OAuth gizli anahtarı oluşturun. Bkz. OAuth ile Azure Databricks'e hizmet sorumlusu erişimini yetkilendirme.
2. Hizmet asıl kimliğini çalışma alanına atayın ve uç noktada buna CAN_QUERY verin.
3. Uygulamadan, hizmet sorumlusu kimlik bilgileriyle POST <workspace-host>/oidc/v1/token öğesini çağırıp authorization_details içinde uç nokta kimliğini belirterek uç nokta kapsamlı bir belirteç oluşturun. Bkz OAuth belirtecini el ile getirme.
4. Rota için optimize edilmiş URL'yi elde edilen belirteçle çağırın.

Yukarıdaki Hızlı başlangıç bölümü, her adımı kapsayan tek bir kopya yapıştırılabilir betik içerir.

Troubleshooting