query les fournisseurs de modèles externes (services de fournisseur de modèles)

Interrogez un fournisseur de modèles externes (service de fournisseur de modèles) via Unity AI Gateway, qui fournit les informations d'identification stockées et achemine la requête vers le fournisseur externe, afin que les appelants n'aient pas à gérer le secret du fournisseur.

Exigences

Les autorisations suivantes sont requises. Voir Découvrir et gouverner l'accès aux fournisseurs de modèles externes (services de fournisseur de modèle).
- EXECUTE sur le service de fournisseur de modèle
- USE CATALOG sur le catalogue
- USE SCHEMA sur le schéma

Identifier un service de fournisseur de modèle

Vous sélectionnez un service de fournisseur de modèle pour une requête avec l'en-tête Databricks-Model-Provider-Service, défini sur le nom en trois parties du service :

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

Authentifiez-vous avec votre jeton Databricks, et non avec les identifiants du fournisseur. L'URL de base est l'URL de votre Workspace suivie de /ai-gateway.

Interroger les APIs prises en charge

Les chemins d'accès gérés mettent à disposition l'API de chaque fournisseur sous un chemin d'accès stable Unity AI Gateway. Unity AI Gateway assure la traduction entre la requête et le fournisseur, applique la gouvernance, notamment des garde-fous et des limites de débit, et enregistre l'utilisation. C'est la méthode recommandée pour interroger un service de fournisseur de modèle.

L'exemple suivant envoie une complétion de chat via un service de fournisseur de modèle OpenAI en utilisant le chemin OpenAI géré. Étant donné que la requête utilise l'API OpenAI Chat Completions, vous pouvez diriger le client OpenAI vers l'URL de base de la passerelle Unity AI.

Python
REST

Python
from openai import OpenAI

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

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)

Bash
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 géré que vous appelez dépend de l'API du fournisseur :

API Fournisseur	Chemin d'accès géré
OpenAI (achèvements du chat)	`/ai-gateway/openai/v1/chat/completions`
OpenAI (réponses)	`/ai-gateway/openai/v1/responses`
OpenAI (intégrations)	`/ai-gateway/openai/v1/embeddings`
Anthropic (messages)	`/ai-gateway/anthropic/v1/messages`
Gemini (générer du contenu)	`/ai-gateway/gemini/v1beta/models/<model>:generateContent`
Gemini (générez du contenu avec des réponses en streaming)	`/ai-gateway/gemini/v1beta/models/<model>:streamGenerateContent`

API Fournisseur	Chemin d'accès géré
OpenAI (achèvements du chat)	`/ai-gateway/openai/v1/chat/completions`
OpenAI (réponses)	`/ai-gateway/openai/v1/responses`
OpenAI (intégrations)	`/ai-gateway/openai/v1/embeddings`
Anthropic (messages)	`/ai-gateway/anthropic/v1/messages`
Gemini (générer du contenu)	`/ai-gateway/gemini/v1beta/models/<model>:generateContent`
Gemini (générez du contenu avec des réponses en streaming)	`/ai-gateway/gemini/v1beta/models/<model>:streamGenerateContent`

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

Query d'autres APIs (Passthrough)

Si un chemin géré ne couvre pas un endpoint de fournisseur, tel qu'un endpoint de fichier ou de batch OpenAI, vous pouvez transmettre la requête au fournisseur sans modification. Unity AI Gateway supprime le préfixe /ai-gateway, joint les informations d'identification stockées et transmet le chemin restant au fournisseur.

Pour activer le passthrough non géré, sélectionnez **Transférer tous les chemins d'URL** sous **Options avancées** lorsque vous créez ou mettez à jour le service de fournisseur de modèle dans l'interface utilisateur.

remarque

Le suivi de l'utilisation et du coût des jetons, les limites de débit basées sur les jetons, le contrôle d'accès au modèle et les politiques de service ne s'appliquent pas aux requêtes de transfert.

Après avoir activé la transmission, appelez le chemin natif du fournisseur sous /ai-gateway. Par exemple, listez les fichiers sur l'Endpoint de fichiers OpenAI :

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

En-têtes et transfert des paramètres de query

Par default, Unity AI Gateway ne transmet pas les en-têtes de requête ou les paramètres de query du client au fournisseur en amont. Deux indicateurs de configuration de service modifient cela, et ils s'appliquent aux chemins gérés et non gérés :

forward_headers: lorsque true, Unity AI Gateway transmet les en-têtes de requête client au fournisseur. Activez cette option lorsqu'un fournisseur exige un en-tête que Unity AI Gateway ne définit pas pour vous, tel que OpenAI-Organization.
forward_query_parameters: lorsque true, Unity AI Gateway transfère les paramètres de query client au fournisseur.

Définissez-les sur le service de fournisseur de modèles comme tout autre champ de configuration :

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

Demandes de tag pour le suivi de l'utilisation

Vous pouvez attacher des tags personnalisés clé-valeur à des requêtes individuelles en utilisant l'en-tête HTTP Databricks-Ai-Gateway-Request-Tags. Unity AI Gateway Logs les tags de requête dans la colonne request_tags de la table système de suivi de l'utilisation et des tables d'inférence. Vous pouvez alors suivre les coûts, attribuer l'utilisation et filtrer l'analytique par projet, équipe, environnement ou autre dimension.

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

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

Envoyez l'en-tête des tags avec l'en-tête Databricks-Model-Provider-Service. Utilisez le extra_headers parameter (Python) ou transmettez l'en-tête directement (API REST) :

Python
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={&quot;Databricks-Model-Provider-Service&quot;: &quot;main.default.openai_prod&quot;},
)

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={&quot;Databricks-Ai-Gateway-Request-Tags&quot;: json.dumps(request_tags)},
)

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

Exigences​

Identifier un service de fournisseur de modèle​

Interroger les APIs prises en charge​

Query d'autres APIs (Passthrough)​

En-têtes et transfert des paramètres de query​

Demandes de tag pour le suivi de l'utilisation​

Étapes suivantes​