Zoek externe modelproviders (modelproviderservices)

Vraag een externe modelprovider (model provider service) via Unity Gateway, die de opgeslagen inloggegevens levert en het verzoek doorstuurt naar de externe provider, zodat bellers het providergeheim niet afhandelen.

Requirements

• Werkruimterecht om te zoeken: Workspace-toegang, of Consumententoegang met de Consumer-toegang tot Unity Gateway-preview ingeschakeld voor jouw account (Publieke Preview). Zie Rechtenbeheer beheren en Azure Databricks previews beheren.
• De volgende machtigingen zijn nodig. Zie Externe modelaanbieders detecteren en de toegang ertoe beheren (services voor modelaanbieders).
  • EXECUTE op de service van de modelaanbieder
  • USE CATALOG op de catalogus
  • USE SCHEMA in het schema

Een modelproviderservice identificeren

U selecteert een modelproviderservice voor een aanvraag met de Databricks-Model-Provider-Service header, ingesteld op de driedelige naam van de service:

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

Verifieer uzelf met uw Azure Databricks-token, niet met de inloggegevens van de provider. De basis-URL is uw werkruimte-URL gevolgd door /ai-gateway.

Ondersteunde API's voor query's

Beheerde paden maken de API van elke provider beschikbaar onder een stabiel Unity Gateway-pad. Unity Gateway verzorgt de vertaling tussen het verzoek en de provider, past beheermaatregelen toe zoals waarborgen en aanvraaglimieten, en legt het gebruik vast. Dit is de aanbevolen manier om een query uit te voeren op een modelproviderservice.

In het volgende voorbeeld wordt een chatvoltooiing verzonden via een OpenAI-modelproviderservice met behulp van het beheerde OpenAI-pad. Omdat het verzoek de OpenAI Chat Completions API gebruikt, kun je de OpenAI-client naar de Unity Gateway-basis-URL verwijzen.

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

Het beheerde pad dat u aanroept, is afhankelijk van de API van de provider:

Het model in de hoofdtekst van de aanvraag (of het Gemini-padsegment) moet een model zijn dat is toegestaan door de service van de modelprovider.

Andere API's bevragen (doorgeefmodus)

Als een beheerd pad een provider-endpoint niet dekt, zoals een OpenAI-bestand of batch-endpoint, kun je het verzoek ongewijzigd doorgeven aan de provider. Unity Gateway verwijdert het /ai-gateway voorvoegsel, voegt het opgeslagen inloggegevens toe en stuurt het resterende pad door naar de provider.

Als u onbeheerde passthrough wilt inschakelen, selecteert u Alle URL-paden doorsturen onder Geavanceerde opties wanneer u de service voor de modelprovider maakt of bijwerkt in de UI.

Nadat u passthrough hebt ingeschakeld, roept u het native pad van de provider aan via /ai-gateway. Maak bijvoorbeeld een lijst met bestanden op het eindpunt van de OpenAI-bestanden:

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

Headervelden en queryparameters doorsturen

Standaard geeft Unity Gateway de requestheaders of queryparameters van de client niet door aan de upstreamprovider. Twee serviceconfiguratievlagmen wijzigen dit en ze zijn van toepassing op zowel beheerde als onbeheerde paden:

• forward_headers: Wanneer true, stuurt Unity Gateway de clientverzoekheaders door naar de provider. Schakel dit in wanneer een provider een header vereist die Unity Gateway niet voor je heeft ingesteld, zoals OpenAI-Organization.
• forward_query_parameters: Wanneer true, stuurt Unity Gateway clientqueryparameters door naar de provider.

Stel deze in op de modelproviderservice, net als elk ander configuratieveld:

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

Tagaanvragen voor het bijhouden van gebruik

U kunt aangepaste sleutelwaardetags koppelen aan afzonderlijke aanvragen met behulp van de Databricks-Ai-Gateway-Request-Tags HTTP-header. Unity Gateway registreert aanvraagtags in de request_tags-kolom in zowel de systeemtabel voor gebruiksregistratie als de inferentietabellen. Vervolgens kunt u kosten, kenmerkgebruik en analyse filteren op project, team, omgeving of een andere dimensie.

De headerwaarde moet een JSON-object zijn dat tekenreekssleutels toewijst aan tekenreekswaarden. Voorbeeld:

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

Verzend de koptekst van de tags naast de Databricks-Model-Provider-Service koptekst. Gebruik de extra_headers parameter (Python) of geef de header rechtstreeks door (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?"}]
  }'

Volgende stappen 

• Ontdek en beheer toegang tot externe modelproviders (modelproviderservices)
• Modelgebruik bijhouden
• Beheer externe modelaanbieders (services van modelaanbieders)