Interroger des fournisseurs de modèles externes (services de fournisseurs de modèles)

Interrogez un fournisseur de modèles externe (service de fournisseur modèle) via Unity Gateway, qui fournit les identifiants stockés et redirige la requête vers le fournisseur externe, afin que les appelants ne gèrent pas le secret du fournisseur.

Exigences

• Droit d’interroger l’espace de travail : Accès à l’espace de travail, ou accès consommateur avec l’aperçu Accès consommateur à Unity Gateway activé pour votre compte (Aperçu public). Voir Gérer les droits et Gérer les aperçus Azure Databricks.
• Les autorisations suivantes sont nécessaires. Voir Découvrir et régir l’accès aux fournisseurs modèles externes (services de fournisseurs modèles).
  • EXECUTE sur le service du fournisseur de modèles
  • USE CATALOG sur le catalogue
  • USE SCHEMA sur le schéma

Identifier un service de fournisseur de modèles

Vous sélectionnez un service du fournisseur de modèle pour une requête à l’aide de l’en-tête Databricks-Model-Provider-Service, dont la valeur est définie sur le nom en trois parties du service :

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

Authentifiez-vous avec votre jeton Azure Databricks, et non avec les informations d'identification du fournisseur. L’URL de base est l’URL de votre espace de travail suivie de /ai-gateway.

Consulter les API prises en charge

Les chemins gérés rendent accessibles l’API de chaque fournisseur via un chemin stable de passerelle Unity. Unity Gateway traduit entre la requête et le fournisseur, applique une gouvernance telle que des garde-fous et des limites de fréquence, et utilise les enregistrements. Il s’agit de la méthode recommandée pour interroger un service fournisseur de modèles.

L’exemple suivant envoie une complétion de chat via un service de fournisseur de modèles OpenAI en utilisant le chemin OpenAI managé. Parce que la requête utilise l’API OpenAI Chat Completions, vous pouvez orienter le client OpenAI vers l’URL de base de la passerelle Unity.

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

Le chemin managé que vous appelez dépend de l’API du fournisseur :

Le modèle dans le corps de la requête (ou le segment de chemin Gemini) doit être un modèle que le service fournisseur de modèles autorise.

Interroger d’autres API (passthrough)

Si un chemin géré ne couvre pas un point de terminaison fournisseur, comme un fichier OpenAI ou un point de terminaison batch, vous pouvez transmettre la requête au fournisseur sans modification. Unity Gateway retire le /ai-gateway préfixe, attache l’identifiant stocké et transmet le chemin restant au fournisseur.

Pour activer la transmission non managée, sélectionnez Transférer tous les chemins d’URL sous Options avancées lorsque vous créez ou mettez à jour le service fournisseur de modèles dans l’interface utilisateur.

Après avoir activé le mode passthrough, appelez le chemin d’accès natif du fournisseur sous /ai-gateway. Par exemple, listez les fichiers via le point de terminaison /files d’OpenAI :

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

Transfert des en-têtes et des paramètres de requête

Par défaut, Unity Gateway ne transmet pas les en-têtes de requête ou les paramètres de requête du client au fournisseur en amont. Deux indicateurs de configuration de service changent ceci et s’appliquent aux chemins managés et non managés :

• forward_headers: Lorsque true, Unity Gateway transmet les en-têtes de requêtes clients au fournisseur. Activez cela lorsqu’un fournisseur nécessite un en-tête que Unity Gateway ne définit pas pour vous, comme OpenAI-Organization.
• forward_query_parameters: Lorsque true, Unity Gateway transmet les paramètres de requête client au fournisseur.

Définissez-les sur le service du fournisseur de modèles comme n’importe quel autre champ de configuration :

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

Étiqueter les demandes de suivi de l’utilisation

Vous pouvez attacher des balises clé-valeur personnalisées à des requêtes individuelles à l’aide de l’en-tête Databricks-Ai-Gateway-Request-Tags HTTP. Unity Gateway enregistre les balises de requête dans la colonne request_tags de la table système de suivi de l’utilisation ainsi que dans les tables d’inférence. Vous pouvez ensuite suivre les coûts, l’utilisation des attributs et filtrer l’analytique par projet, équipe, environnement ou une autre dimension.

La valeur d’en-tête doit être un objet JSON qui associe des clés de chaîne à des valeurs de chaîne. Par exemple:

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

Envoyez l’en-tête de balises en même temps que l’en-tête Databricks-Model-Provider-Service . Utilisez le extra_headers paramètre (Python) ou passez l’en-tête directement (API REST) :

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

Étapes suivantes

• Découvrir et régir l’accès aux fournisseurs modèles externes (services de fournisseurs modèles)
• Suivre l’utilisation du modèle
• Gérer les fournisseurs externes de modèles (services de fournisseurs de modèles)