Dotazování koncových bodů obsluhy optimalizovaných pro trasu

Tento článek popisuje, jak načíst příslušné přihlašovací údaje a adresu URL, abyste mohli dotazovat směrově optimalizovanou obsluhu modelu nebo obsluhu koncového bodu funkcí.

Požadavky

Model obsluhující koncový bod nebo funkci obsluhující koncový bod, který má povolenou optimalizaci tras Viz Optimalizace trasy pro obsluhu koncových bodů.
Dotazování koncových bodů optimalizovaných pro směrování podporuje pouze použití tokenů OAuth. Osobní přístupové tokeny se nepodporují.

Rychlý start: kompletní recept na dotazy

Následující recept kombinuje každý krok potřebný k dotazování koncového bodu optimalizovaného pro směrování z externího klienta do jednoho spustitelného toku. Tuto část použijte, pokud chcete rychle ověřit funkční nastavení. Další podrobnosti o jednotlivých krocích najdete v následujících částech.

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

Načtěte adresu URL optimalizovanou pro trasu

Výstraha

Od 22. září 2025 se všechny nově vytvořené koncové body optimalizované pro směrování musí dotazovat výhradně prostřednictvím adresy URL optimalizované pro směrování. Koncové body vytvořené po tomto datu nepodporují dotazování prostřednictvím adresy URL pracovního prostoru.

Pokud se koncový bod optimalizovaný pro trasu vytvořil před 22. zářím 2025:

Standardní adresu URL pracovního prostoru lze také použít k dotazování koncového bodu. Standardní cesta URL pracovního prostoru neposkytuje výhody optimalizace tras.

https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations
Koncové body optimalizované pro směrování vytvořené před tímto datem nadále podporují obě adresy URL volání: cestu url optimalizovanou pro trasu a standardní cestu URL pracovního prostoru.

Při vytváření koncového bodu optimalizovaného pro směrování se pro koncový bod vytvoří následující adresa URL optimalizovaná pro trasu.

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

Tuto adresu URL můžete získat z následujícího:

Obsluha uživatelského rozhraní

Adresa URL koncového bodu optimalizované pro směrování

REST API

GET /api/2.0/serving-endpoints/{name} Použijte volání rozhraní API. Adresa URL se nachází v objektu odpovědi koncového bodu jako endpoint_url. Toto pole se vyplní jenom v případě, že je koncový bod optimalizovaný pro směrování.

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

Databricks SDK

Použijte toto volání Serving Endpoints API get. Adresa URL se nachází v objektu odpovědi koncového bodu jako endpoint_url. Toto pole se vyplní jenom v případě, že je koncový bod optimalizovaný pro směrování.

from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

Načtení tokenu OAuth a dotazování koncového bodu

K dotazování koncového bodu optimalizovaného pro směrování musíte použít token OAuth. Databricks doporučuje používat instanční objekty v produkčních aplikacích k programovému načítání tokenů OAuth. Následující části popisují doporučené pokyny k načtení tokenu OAuth pro testovací a produkční scénáře.

Získání tokenu OAuth pomocí uživatelského rozhraní pro službu

Následující postup ukazuje, jak získat token v rozhraní Serving UI. Tyto kroky se doporučují pro vývoj a testování koncového bodu.

Pro produkční použití, jako je použití koncového bodu optimalizovaného pro směrování v aplikaci, se token načte pomocí instančního objektu. Doporučené pokyny k načtení tokenu OAuth pro produkční případy použití najdete v tématu Programové načtení tokenu OAuth.

V uživatelském rozhraní obsluhy pracovního prostoru:

Na stránce Obsluha koncových bodů vyberte koncový bod optimalizovaný pro směrování a zobrazte podrobnosti o koncovém bodu.
Na stránce podrobností o koncovém bodu vyberte tlačítko Použít .
Vyberte záložku Načtení tokenu.
Vyberte tlačítko načíst token OAuth. Tento token je platný po dobu 1 hodiny. Pokud platnost aktuálního tokenu vyprší, načtěte nový token.

Po načtení tokenu OAuth zadejte dotaz na koncový bod pomocí adresy URL koncového bodu a tokenu OAuth.

REST API

Následuje příklad rozhraní 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

Následuje příklad Pythonu:


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)

Programové načtení tokenu OAuth

V produkčních scénářích doporučuje Databricks nastavit služby hlavních uživatelů, aby byly integrovány do vaší aplikace a automatizovaně načítaly tokeny OAuth. Tyto načtené tokeny se používají k dotazování koncových bodů optimalizovaných pro směrování.

Postupujte podle kroků v tématu Autorizace přístupu instančního objektu k Azure Databricks pomocí OAuth prostřednictvím kroku 2 a vytvořte instanční objekt, přiřaďte oprávnění a vytvořte pro instanční objekt tajný klíč OAuth. Po vytvoření instančního objektu musíte instančnímu objektu udělit alespoň oprávnění k dotazu na koncový bod. Viz Správa oprávnění pro koncový bod obsluhující model.

Sada Databricks Python SDK poskytuje rozhraní API pro přímé dotazování na koncový bod optimalizovaný pro směrování.

Poznámka:

Sada Databricks SDK je dostupná také v Go, viz Databricks SDK pro Go.

Následující příklad vyžaduje následující dotaz na koncový bod optimalizovaný pro směrování pomocí sady Databricks SDK:

Obsluha názvu koncového bodu (sada SDK načte správnou adresu URL koncového bodu na základě tohoto názvu).
ID klienta služebního principálu
Tajný klíč servisního principála
Název hostitele pracovního prostoru

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

Ruční načtení tokenu OAuth

V situacích, kdy se k načtení tokenu OAuth nedá použít sada Databricks SDK nebo obslužné uživatelské rozhraní, můžete token OAuth načíst ručně. Pokyny v této části se týkají hlavně scénářů, kdy uživatelé mají přizpůsobeného klienta, kterého chtějí použít k dotazování koncového bodu v produkčním prostředí.

Při ručním načtení tokenu OAuth je nutné zadat authorization_details v požadavku.

Vytvořte <token-endpoint-URL> nahrazením https://<databricks-instance> za URL pracovního prostoru vašeho nasazení Databricks v https://<databricks-instance>/oidc/v1/token. Například https://my-workspace.0.azuredatabricks.net/oidc/v1/token

Nahraďte <client-id> ID klienta principálu služby, které se označuje také jako ID aplikace.
Nahraďte <client-secret> tajným kódem OAuth instančního objektu, který jste vytvořili.

Nahraďte <endpoint-id> ID koncového bodu koncového bodu optimalizovaného pro trasu. Toto je alfanumerické ID koncového bodu, které najdete v hostName adrese URL koncového bodu. Pokud je https://abcdefg.0.serving.azuredatabricks.net/9999999/serving-endpoints/testnapříklad obslužný koncový bod , ID koncového bodu je abcdefg.

Nahraďte <action> oprávněním k akci uděleným instančnímu objektu. Akce může být query_inference_endpoint nebo manage_inference_endpoint.

REST API

Následuje příklad rozhraní 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

Následuje příklad Pythonu:

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

Po načtení tokenu OAuth zadejte dotaz na koncový bod pomocí adresy URL koncového bodu a tokenu OAuth.

REST API

Následuje příklad rozhraní 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

Následuje příklad Pythonu:


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)

Volání z agenta AI nebo z externí aplikace

Asistenti pro kódování využívající AI a externí aplikace, které odesílají dotazy na koncové body optimalizované pro směrování požadavků, nemohou používat osobní přístupový token vývojáře ani tokeny OAuth pracovního prostoru. Musí použít instanční objekt služby s tokem OAuth M2M a do žádosti o token zahrnout authorization_details. Postup je následující:

Vytvořte instanční objekt služby na úrovni účtu a tajný klíč OAuth pro tento instanční objekt služby. Viz Autorizace přístupu servisního principála k Azure Databricks pomocí OAuth.
Přiřaďte instanční objekt k pracovnímu prostoru a udělte mu CAN_QUERY pro koncový bod.
Z aplikace vygenerujte token omezený na koncový bod voláním POST <workspace-host>/oidc/v1/token s přihlašovacími údaji instančního objektu služby a parametrem authorization_details, který odkazuje na ID koncového bodu. Viz ruční načtení tokenu OAuth.
Vyvolejte adresu URL optimalizovanou pro směrování s výsledným tokenem.

Výše uvedená část Rychlý start obsahuje jediný skript, který lze zkopírovat a vložit a který zahrnuje všechny kroky.

Troubleshooting

Error	Příčina	Opravit
`401 Malformed token` vráceno z adresy URL optimalizované pro směrování	Token je token osobního přístupu nebo token clusterového runtime, nikoli OAuth JWT. Koncové body optimalizované pro směrování přijímají pouze tokeny OAuth.	K získání tokenu OAuth použijte instanční objekt služby s tokem OAuth M2M. Viz programové načtení tokenu OAuth.
`401 Missing authorization details for accessing model serving endpoints` vráceno z adresy URL optimalizované pro směrování	V požadavku na token chyběl claim `authorization_details`, který omezuje rozsah oprávnění tokenu na konkrétní endpoint. Prostý `scope=all-apis` token nestačí.	Předejte `authorization_details` s odkazem na ID koncového bodu a akci `query_inference_endpoint` při volání `/oidc/v1/token`. Viz ruční načtení tokenu OAuth.
`400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ...`	Místo adresy URL optimalizované pro směrování jste odeslali požadavek na adresu URL `https://<workspace>/serving-endpoints/<name>/invocations` pracovního prostoru.	Použijte adresu URL vrácenou `endpoint_url` v poli `GET /api/2.0/serving-endpoints/<name>`. Viz Načtení adresy URL optimalizované pro směrování.
`403 Permission denied` vrácené z adresy URL optimalizované pro směrování, přestože token OAuth má `authorization_details`	Instanční objekt služby nemá `CAN_QUERY` v koncovém bodě nebo akce v `authorization_details` neodpovídá udělenému oprávnění.	U koncového bodu udělte instančnímu objektu služby oprávnění `CAN_QUERY` a jako akci použijte `query_inference_endpoint`. Viz Správa oprávnění pro koncový bod obsluhující model.
`invalid_scope` vráceno z `/oidc/v1/token`	Požadavek na token předal jinou hodnotu oboru než `all-apis`.	Jediným podporovaným oborem pro tokeny koncových bodů optimalizovaných pro směrování je `all-apis`. K omezení rozsahu koncového bodu dochází pomocí `authorization_details`, nikoli `scope`.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-06

Dotazování koncových bodů obsluhy optimalizovaných pro trasu

Požadavky

Rychlý start: kompletní recept na dotazy

Načtěte adresu URL optimalizovanou pro trasu

Obsluha uživatelského rozhraní

REST API

Databricks SDK

Načtení tokenu OAuth a dotazování koncového bodu

Získání tokenu OAuth pomocí uživatelského rozhraní pro službu

REST API

Python

Programové načtení tokenu OAuth

Ruční načtení tokenu OAuth

REST API

Python

REST API

Python

Volání z agenta AI nebo z externí aplikace

Troubleshooting

Váš názor

Další materiály