Fråga externa modellleverantörer (modellleverantörstjänster)

Fråga en extern modellleverantör (modellleverantörstjänst) via Unity Gateway, som tillhandahåller de lagrade uppgifterna och routar förfrågan till den externa leverantören, så att anropare inte hanterar leverantörshemligheten.

Requirements

• Behörighet för arbetsyta att fråga: Åtkomst till arbetsyta eller Konsumentåtkomst med Konsumentåtkomst till Unity Gateway i förhandsversion aktiverad för ditt konto (Offentlig förhandsversion). Se Hantera rättigheter och Hantera Azure Databricks förhandsvisningar.
• Följande behörigheter krävs. Se Discover och styr åtkomst till externa modellleverantörer (modellleverantörstjänster).
  • EXECUTE på modellprovidertjänsten
  • USE CATALOG på katalogen
  • USE SCHEMA för schemat

Identifiera en modellleverantörstjänst

Du väljer en modellprovidertjänst för en begäran med Databricks-Model-Provider-Service huvudet och anger tjänstens tredelade namn:

Databricks-Model-Provider-Service: main.default.openai_prod

Autentisera med din Azure Databricks token, inte providerns autentiseringsuppgifter. Bas-URL:en är din arbetsyte-URL följt av /ai-gateway.

Fråge-API:er som stöds

Hanterade vägar gör varje leverantörs API tillgängligt under en stabil Unity Gateway-path. Unity Gateway översätter mellan förfrågan och leverantören, tillämpar styrning som räcken och hastighetsgränser, och registrerar användning. Det här är det rekommenderade sättet att fråga en modellleverantörstjänst.

I följande exempel skickas en chatt som slutförs via en OpenAI-modellprovidertjänst med hjälp av den hanterade OpenAI-sökvägen. Eftersom förfrågan använder OpenAI Chat Completions API kan du rikta OpenAI-klienten till Unity Gateway-bas-URL:en.

Python

from openai import OpenAI

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={"Databricks-Model-Provider-Service": "main.default.openai_prod"},
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in exactly 3 words."}],
)
print(response.choices[0].message.content)

REST

curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in exactly 3 words."}]
  }'

Vilken hanterad sökväg du anropar beror på providerns API:

Modellen i begärandetexten (eller segmentet Gemini-sökväg) måste vara en modell som modellprovidertjänsten tillåter.

Anropa andra API:er (vidarebefordran)

Om en hanterad sökväg inte täcker en leverantörsändpunkt, såsom en OpenAI-fil eller batch-endpoint, kan du skicka förfrågan vidare till leverantören oförändrad. Unity Gateway tar bort prefixet /ai-gateway , bifogar den lagrade legitimationen och vidarebefordrar den återstående vägen till leverantören.

Om du vill aktivera ohanterad genomströmning väljer du Vidarebefordra alla URL-sökvägar under Avancerade alternativ när du skapar eller uppdaterar modellprovidertjänsten i användargränssnittet.

När du har aktiverat direkt vidarebefordran anropar du leverantörens inbyggda sökväg under /ai-gateway. Du kan till exempel lista filer på OpenAI-filslutpunkten:

curl https://<workspace-url>/ai-gateway/files \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod"

Vidarebefordran av rubriker och frågeparametrar

Som standard skickar inte Unity Gateway klientens förfrågningshuvuden eller frågeparametrar till upstream-leverantören. Två flaggor för tjänstkonfiguration ändrar detta, och de gäller för både hanterade och ohanterade sökvägar:

• forward_headers: När true, vidarebefordrar Unity Gateway klientförfrågningshuvuden till leverantören. Aktivera detta när en leverantör kräver en header som Unity Gateway inte ställer in åt dig, såsom OpenAI-Organization.
• forward_query_parameters: När true, vidarebefordrar Unity Gateway klientfrågeparametrar till leverantören.

Ange dem på modellprovidertjänsten som alla andra konfigurationsfält:

curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services/main.default.openai_prod \
  -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "update_mask=config.forward_headers,config.forward_query_parameters" \
  --data '{ "config": { "forward_headers": true, "forward_query_parameters": true } }'

Märk begäranden för användningsspårning

Du kan koppla anpassade nyckel/värde-taggar till enskilda begäranden med hjälp av Databricks-Ai-Gateway-Request-Tags HTTP-huvudet. Unity Gateway loggar förfrågningstaggar i kolumnen request_tags i både systemtabellen för användningsspårning och inferenstabellerna. Du kan sedan spåra kostnader, attributanvändning och filteranalys efter projekt, team, miljö eller en annan dimension.

Huvudvärdet måste vara ett JSON-objekt som mappar strängnycklar till strängvärden. Ett exempel:

{ "project": "chatbot", "team": "ml-platform", "environment": "production" }

Skicka taggarna bredvid Databricks-Model-Provider-Service rubriken. Använd parametern extra_headers (Python) eller skicka headern direkt (REST API):

Python

from openai import OpenAI
import json

client = OpenAI(
    api_key="<databricks-token>",
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={"Databricks-Model-Provider-Service": "main.default.openai_prod"},
)

request_tags = {"project": "chatbot", "team": "ml-platform"}

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    extra_headers={"Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)},
)

REST

curl https://<workspace-url>/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Databricks-Model-Provider-Service: main.default.openai_prod" \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "What is Databricks?"}]
  }'

Nästa steg

• Upptäck och styr åtkomst till externa modellleverantörer (modellleverantörstjänster)
• Användning av spårmodeller
• Styr externa modellleverantörer (modellleverantörstjänster)