Modellanbieterdienste abfragen

Important

Dieses Feature befindet sich in der Betaversion. Kontoadministratoren können den Zugriff auf dieses Feature über die Seite " Vorschauen " der Kontokonsole verwalten. Siehe Manage Azure Databricks Previews.

Auf dieser Seite wird beschrieben, wie Sie einen Modellanbieterdienst über Unity AI Gateway abfragen. Unity AI Gateway stellt die gespeicherten Zugangsdaten bereit und leitet die Anfrage an den externen Anbieter weiter, sodass Aufrufer das Secret des Anbieters nicht selbst verwalten müssen.

Requirements

Identifizieren eines Modellanbieterdiensts

Sie wählen einen Modellanbieterdienst für eine Anforderung mit dem Databricks-Model-Provider-Service Header 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 mithilfe des verwalteten OpenAI-Pfads 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:

Anbieter-API Verwalteter Pfad
OpenAI (Chat-Fertigstellungen) /ai-gateway/openai/v1/chat/completions
OpenAI (Antworten) /ai-gateway/openai/v1/responses
OpenAI (Einbettungen) /ai-gateway/openai/v1/embeddings
Anthropic (Nachrichten) /ai-gateway/anthropic/v1/messages
Gemini (Generieren von Inhalten) /ai-gateway/gemini/v1beta/models/<model>:generateContent

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 Anbieterendpunkt abdeckt , z. B. eine OpenAI-Datei oder ein Batchendpunkt, können Sie die Anforderung unverändert an den Anbieter übergeben. Unity AI Gateway entfernt das /ai-gateway Präfix, fügt die gespeicherten Anmeldeinformationen an und leitet den verbleibenden Pfad an den Anbieter weiter.

Nicht verwaltete Passthrough ist standardmäßig deaktiviert. Aktivieren Sie ihn für den Modellanbieterdienst, indem Sie ihn in der Dienstkonfiguration festlegen forward_unmanaged_pathstrue :

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_unmanaged_paths" \
  --data '{ "config": { "forward_unmanaged_paths": true } }'

Nachdem Sie Passthrough aktiviert haben, rufen Sie den nativen Pfad des Anbieters unter /ai-gateway auf:

curl https://<workspace-url>/ai-gateway/v1/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 Unity AI Gateway die Header von Clientanforderungen 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, Unity AI Gateway Clientabfrageparameter an den Anbieter weiterleitet.

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

  • Last updated on