쿼리 경로 최적화 서비스 엔드포인트

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 토큰을 가져오는 방법에 대한 권장 지침을 설명합니다.

서비스 UI를 사용하여 OAuth 토큰 가져오기

다음 단계에서는 서비스 UI에서 토큰을 가져오는 방법을 보여줍니다. 이러한 단계는 엔드포인트를 개발 및 테스트하는 데 권장됩니다.

애플리케이션에서 경로 최적화된 엔드포인트를 사용하는 것처럼, 프로덕션 사용을 위해 톤큰은 서비스 프린시펄을 사용하여 가져옵니다. 프로덕션 사용 사례에 대한 OAuth 토큰을 프로그래밍 방식으로 가져오는 권장 지침은 OAuth 토큰을 프로그래밍 방식으로 가져오는 방법을 참조하세요.

작업 영역의 서비스 UI에서:

서비스 엔드포인트 페이지에서 경로 최적화 엔드포인트를 선택하여 엔드포인트 세부 정보를 확인합니다.
엔드포인트 세부 정보 페이지에서 사용 단추를 선택합니다.
가져오기 토큰 탭을 선택합니다.
OAuth 토큰 가져오기 단추를 선택합니다. 이 토큰은 1시간 동안 유효합니다. 현재 토큰이 만료되면 새 토큰을 가져옵니다.

OAuth 토큰을 가져온 후 엔드포인트 URL 및 OAuth 토큰을 사용하여 엔드포인트를 쿼리합니다.

REST API (REST 애플리케이션 프로그래밍 인터페이스)

다음은 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 토큰을 프로그래밍 방식으로 가져오는 것이 좋습니다. 이러한 페치된 토큰은 경로 최적화 엔드포인트를 쿼리하는 데 사용됩니다.

2단계를 통해 OAuth를 사용하여 서비스 주체를 사용하여 Azure Databricks 리소스에 대한 무인 액세스 권한 부여 의 단계에 따라 서비스 주체를 만들고, 권한을 할당하고, 서비스 주체에 대한 OAuth 비밀을 만듭니다. 서비스 주체를 만든 후에는 서비스 주체에게 엔드포인트에 대한 쿼리 이상의 권한을 부여해야 합니다. 엔드포인트를 제공하는 모델에 대한 권한 관리를 참조하세요.

Databricks Python SDK는 경로 최적화 엔드포인트를 직접 쿼리하는 API를 제공합니다.

비고

Databricks SDK는 Go에서도 사용할 수 있습니다. Go 용 Databricks SDK를 참조하세요.

이 예제에서는 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.
서비스 주체의 클라이언트 ID로 <client-id>을(를) 애플리케이션 ID라고도 하는 것으로 바꾸십시오.
서비스 주체의 OAuth 비밀로 <client-secret>을(를) 교체하십시오.
<endpoint-id>을 경로 최적화 엔드포인트의 엔드포인트 ID로 바꿉니다. 엔드포인트 URL에서 hostName 찾을 수 있는 엔드포인트의 알파 숫자 ID입니다.
<action>을 서비스 주체에 지정된 작업 권한으로 바꿉니다. 작업은 query_inference_endpoint 또는 manage_inference_endpoint일 수 있습니다.

REST API (REST 애플리케이션 프로그래밍 인터페이스)

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

파이썬

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 애플리케이션 프로그래밍 인터페이스)

다음은 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)

다음을 통해 공유

쿼리 경로 최적화 서비스 엔드포인트

요구 사항

경로 최적화 URL 가져오기

OAuth 토큰 가져오기 및 엔드포인트 쿼리

서비스 UI를 사용하여 OAuth 토큰 가져오기

REST API (REST 애플리케이션 프로그래밍 인터페이스)

파이썬

프로그래밍 방식으로 OAuth 토큰 가져오기

수동으로 OAuth 토큰 가져오기

REST API (REST 애플리케이션 프로그래밍 인터페이스)

파이썬

REST API (REST 애플리케이션 프로그래밍 인터페이스)

파이썬

피드백

추가 리소스