Abfrage externer Modellanbieter (Modellanbieterdienste)

Abfragen Sie einen externen Modellanbieter (Modellanbieter-Service) über das Unity AI Gateway, das die gespeicherten Zugangsdaten bereitstellt und die Anfrage an den externen Anbieter weiterleitet, sodass Anrufer das Provider-Geheimnis nicht verwalten.

Requirements

• Arbeitsbereichsberechtigung zur Abfrage: Arbeitsbereichszugriff oder Verbraucherzugriff mit aktiviertem Consumer-Zugang zur Unity AI Gateway-Vorschau für Ihr Konto (öffentliche Vorschau). Siehe Berechtigungen verwalten und Azure Databricks-Vorschauen verwalten.
• Die folgenden Berechtigungen sind erforderlich. Siehe Entdecken und den Zugriff auf externe Modellanbieter (Modellanbieter-Dienste) regeln.
  • EXECUTE auf dem Modellanbieterdienst
  • USE CATALOG im Katalog
  • USE SCHEMA im Schema

Identifizieren eines Modellanbieterdiensts

Sie wählen einen Modellanbieterdienst für eine Anforderung mit dem Header Databricks-Model-Provider-Service aus, der auf den dreiteiligen Namen des Diensts festgelegt ist:

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

Authentifizieren Sie sich mit Ihrem Azure Databricks-Token, nicht mit den Anmeldeinformationen des Anbieters. Die Basis-URL ist Ihre Arbeitsbereichs-URL, gefolgt von /ai-gateway.

Unterstützte APIs abfragen

Verwaltete Pfade stellen die API jedes Anbieters unter einem stabilen Unity AI-Gatewaypfad zur Verfügung. Unity AI Gateway übersetzt zwischen der Anfrage und dem Anbieter, wendet Governance-Mechanismen wie Leitplanken und Ratenlimits an und zeichnet die Nutzung auf. Dies ist die empfohlene Methode zum Abfragen eines Modellanbieterdiensts.

Im folgenden Beispiel wird mit dem verwalteten OpenAI-Pfad ein Chatabschluss über einen OpenAI-Modellanbieterdienst gesendet. Da die Anforderung die OpenAI-Chatabschluss-API verwendet, können Sie den OpenAI-Client auf die Unity AI Gateway-Basis-URL verweisen.

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

Der verwaltete Pfad, den Sie aufrufen, hängt von der API des Anbieters ab:

Das Modell im Anforderungstext (oder das Segment des Gemini-Pfads) muss ein Modell sein, das der Modellanbieterdienst zulässt.

Andere APIs abfragen (Passthrough)

Wenn ein verwalteter Pfad keinen Provider-Endpunkt abdeckt, wie etwa eine OpenAI-Datei oder einen Batch-Endpunkt, können Sie die Anfrage unverändert an den Anbieter weiterleiten. Unity AI Gateway entfernt das /ai-gateway Präfix, fügt die gespeicherten Anmeldeinformationen an und leitet den verbleibenden Pfad an den Anbieter weiter.

Um nicht verwaltetes Passthrough zu aktivieren, wählen Sie beim Erstellen oder Aktualisieren des Modellanbieterdienstes in der UI unter Erweiterte Optionen die Option Alle URL-Pfade weiterleiten aus.

Rufen Sie nach dem Aktivieren von Passthrough den nativen Pfad des Anbieters unter /ai-gateway auf. Listen Sie beispielsweise Dateien über den OpenAI-Dateiendpunkt auf:

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

Weiterleitung von Headern und Abfrageparametern

Standardmäßig übergibt Unity AI Gateway die Anforderungsheader oder Abfrageparameter des Clients nicht an den Upstream-Anbieter. Zwei Dienstkonfigurationskennzeichnungen ändern dies, und sie gelten sowohl für verwaltete als auch für nicht verwaltete Pfade:

• forward_headers: Wenn true, leitet das Unity AI Gateway die Client-Anfrage-Header an den Anbieter weiter. Aktivieren Sie diese Option, wenn ein Anbieter einen Header erfordert, den Unity AI Gateway nicht für Sie setzt, wie z. B. OpenAI-Organization.
• forward_query_parameters: Wenn true, leitet das Unity AI Gateway Client-Abfrageparameter an den Anbieter weiter.

Legen Sie sie für den Modellanbieterdienst wie jedes andere Konfigurationsfeld fest:

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

Tag-Anforderungen für die Verwendungsnachverfolgung

Sie können einzelnen Anfragen benutzerdefinierte Schlüssel-Wert-Tags mithilfe des HTTP-Headers Databricks-Ai-Gateway-Request-Tags hinzufügen. Unity AI Gateway protokolliert Anforderungs-Tags in der Spalte request_tags sowohl in der Systemtabelle zur Nutzungsverfolgung als auch in den Inferenztabellen. Anschließend können Sie Kosten, Attributnutzung und Filteranalysen nach Projekt, Team, Umgebung oder einer anderen Dimension nachverfolgen.

Der Header-Wert muss ein JSON-Objekt sein, das String-Schlüssel String-Werten zuordnet. Beispiel:

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

Senden Sie den Tag-Header zusammen mit dem Header Databricks-Model-Provider-Service. Verwenden Sie den extra_headers Parameter (Python) oder übergeben Sie den Header 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ächste Schritte

• Entdecken und steuern Sie den Zugang zu externen Modellanbietern (Modellanbieterdienste)
• Verwendung von Streckenmodellen
• Externe Modellanbieter steuern (Modellanbieterdienste)