Migrer vers Unity Gateway
Unity Gateway est le plan de contrôle Databricks pour l’IA d’entreprise. Construit sur Unity Catalog, il gère les services de modèles, les fournisseurs de modèles externes, les serveurs MCP, les agents, les compétences et les outils à partir d’un emplacement unique, avec les mêmes privilèges, contrôles des coûts, garde-fous et capacités d’observabilité que ceux que vous utilisez pour les données. Les endpoints AI Gateway hérités restent liés à un seul workspace et ne fournissent pas cette gouvernance centralisée.
Utilisez ce guide pour migrer les charges de travail de déploiement de modèles existantes et d'AI Gateway héritée vers Unity Gateway, et pour activer le paramètre de workspace Enforce Unity Gateway afin que tout le trafic d'IA générative soit gouverné par le biais de Unity Catalog.
Exigences
- Un workspace Databricks activé pour Unity Catalog. Consultez la page Activer le workspace pour Unity Catalog.
- Accès administrateur du workspace pour activer le paramètre Enforce Unity Gateway .
- Accès administrateur de compte pour interroger les tables d'utilisation
system.servinglorsque vous identifiez du trafic hérité.
Choisissez votre chemin de migration
Sélectionnez le chemin qui correspond à votre situation.
Votre situation | Chemin d'accès recommandé |
|---|---|
Vous n'utilisez pas AI Gateway, vous l'utilisez uniquement de manière occasionnelle, ou vous configurez un nouveau compte ou workspace | |
Vous avez des charges de travail AI Gateway héritées actives | |
Vous vous êtes inscrit à la version aperçu des autorisations pour Unity Catalog des modèles de fondation | Migrez les workloads existants et examinez les autorisations de votre service de modèle. Les autorisations définies sur des modèles individuels n'accordent pas automatiquement l'accès au service de modèle correspondant. |
start fresh with Unity Gateway
Si vous débutez avec Unity Gateway ou si vous configurez un nouveau compte ou un nouveau Workspace, start directement sur Unity Gateway.
Étape 1 : Examiner l'accès aux services de modèle hébergés par Databricks
Unity Gateway fournit des services de modèle hébergés par Databricks prêts à l’emploi dans le schéma system.ai. Vérifiez qui peut y accéder et restreignez l’accès si nécessaire.
default, tous les utilisateurs du compte disposent de EXECUTE sur les services de modèle fournis par le système. Chaque service de modèle nécessite également USE CATALOG sur system et USE SCHEMA sur system.ai. Pour appliquer le principe du moindre privilège, supprimez l'accès étendu aux schémas et accordez EXECUTE sur les services de modèle individuels. Les autorisations de modèle sous-jacentes n'accordent pas l'accès au service de modèle.
Action | Autorisations requises |
|---|---|
Interroger un service de modèle |
|
Créer un service de modèle |
|
Interroger un fournisseur de modèles externe |
|
Créer un fournisseur de modèles externe |
|
Pour l'accès basé sur des tags gouvernés et des attributs, consultez les GRANT policies.
Si vous étiez inscrit à l'aperçu Autorisations Unity Catalog pour les modèles de fondation, les autorisations définies sur les modèles individuels ne s'appliquent pas automatiquement aux services de modèle correspondants. Examinez et réappliquez vos octrois de moindre privilège sur les services de modèle.
Step 2: Enable Enforce Unity Gateway
Activez le paramètre de workspace Enforce Unity Gateway pour désactiver les anciennes expériences AI Gateway afin que tout le trafic d'IA générative soit gouverné via Unity Catalog. Si vous ne l'activez pas, vos configurations héritées existantes resteront inchangées.
Lorsque vous activez l'application, chaque surface de produit se comporte comme suit :
Exposer | Comportement lorsque l'application est activée |
|---|---|
All pay-per-token traffic must route through a model service. Databricks-provided pay-per-token serving endpoints (the | |
Vous ne pouvez plus créer d'Endpoint de service de throughput provisionné sans Unity Gateway. Les endpoints existants restent intacts et interrogeables. | |
Vous ne pouvez plus créer d'Endpoint de service de modèles externes sans Unity Gateway. Les endpoints existants restent intacts et interrogeables. |
Pour activer le paramètre :
- Connectez-vous à votre workspace Databricks en tant qu’administrateur de workspace.
- Accédez à Paramètres > Avancés .
- Activez l'option Enforce Unity Gateway .
Une fois l'application activée, les requêtes vers les Endpoint de service pay-per-token désactivés renvoient une erreur PERMISSION_DENIED :
{
"error_code": "PERMISSION_DENIED",
"message": "Querying pay-per-token foundation model endpoint 'databricks-gpt-5' is disabled for this workspace. Please use Unity Gateway."
}
L'activation de l'application interrompt le trafic vers les anciens Endpoint actifs. Si votre workspace exécute des charges de travail héritées, suivez les instructions de la page Migrer les charges de travail existantes et assurez-vous que le trafic a bien été basculé avant d'activer le paramètre.
Le paramètre Appliquer la passerelle Unity est disponible dans les workspaces qui possèdent des endpoints AI Gateway hérités. Il reste disponible après que leur trafic est tombé à zéro, de sorte que vous pouvez l'activer à la fin de votre migration. Les nouveaux workspaces activent l'application par default et n'affichent pas le paramètre. Si le paramètre n'est pas disponible dans votre workspace, contactez l'équipe de votre compte Databricks une fois que vous avez terminé et validé votre migration.
Lorsque l'application de la règle est activée, les limitations suivantes s'appliquent, car tous les produits qui reposaient sur d'anciens Endpoint de service n'ont pas migré vers Unity Gateway :
- AI Search : la création d’Endpoint AI Search via Unity Gateway n’est pas encore prise en charge. Les agents Knowledge Assistant et Multi-Agent Supervisor qui dépendent d’endpoints AI Search ne fonctionnent pas.
ai_query:ai_queryprend en charge uniquement les services de modèles fournis par le système danssystem.ai, et non les services de modèles personnalisés.- Databricks Apps : les applications configurées avec la ressource de l’endpoint de service de modèle (un Service Principal ayant accès aux modèles
system.ai) cessent de fonctionner. Accordez au Service PrincipalEXECUTEsur les model servicessystem.aicorrespondants, et mettez à jour l’application pour query model services.
Migrer les workloads existants
Si vous disposez de workloads AI Gateway hérités actifs, procédez comme suit avant d’activer l’application.
Étape 1 : identifier l'utilisation active héritée
Découvrez quels Endpoint hérités reçoivent toujours du trafic, dans quels Workspace et qui les appelle.
- Activer le suivi de l'utilisation sur vos endpoints hérités. Son activation étant idempotente, il est possible de l'exécuter à nouveau sans risque.
- Query the
system.serving.endpoint_usageandsystem.serving.served_entitiessystem tables for recent requests, callers, and last-request times. Only account admins can query these tables.
Étape 2 : Configurer les services et les fournisseurs de modèles
La gouvernance configurée sur un endpoint hérité n'est pas reportée. The existing configuration stays on the legacy endpoint. Créez ou identifiez le service de modèle ou le fournisseur de modèle externe dont vous avez besoin, puis recréez les paramètres sur lesquels vous vous appuyez, tels que les autorisations, les limites de débit, les budgets, les politiques de service, le suivi de l'utilisation, les tables d'inférence et le routage du trafic et les fallback. Mettez également à jour tous les workflows CI/CD ou Infrastructure-as-Code pour utiliser les Unity Gateway APIs.
Migrer chaque type de charge de travail vers la cible suivante :
Charge de travail existante | Cible de migration |
|---|---|
Modèle pay-per-token hébergé par Databricks | Utilisez le service de modèle fourni par le système correspondant dans |
Throughput provisionné hébergé par Databricks | Conservez le endpoint de serving de throughput provisionné existant et créez un service de modèle qui y fait référence. Accordez aux appelants |
Fournisseur externe | Créez un fournisseur de modèles externe avec votre fournisseur existant, vos identifiants, vos modèles exposés et vos appelants. Interrogez-le directement ou créez un service de modèle pour assurer une gouvernance spécifique au modèle ; dans ce cas, les paramètres du service de modèle prévalent. |
Étape 3 : Mettez à jour vos clients
Une fois que vous avez configuré le service de modèle ou le fournisseur de modèle externe, déplacez chaque charge de travail vers Unity Gateway. Migrez conjointement l'URL de la gateway et la portée du jeton d'accès personnel (PAT).
Clients API et SDK : pour les modèles hébergés sur Databricks, modifiez l’URL de base de /serving-endpoints à /ai-gateway/mlflow/v1 et changez le modèle du nom de l’endpoint vers le nom complet du service de modèle.
from openai import OpenAI
client = OpenAI(
api_key=token,
base_url="https://<workspace-url>/ai-gateway/mlflow/v1",
)
response = client.chat.completions.create(
model="<catalog>.<schema>.<model-service>",
messages=[...],
)
Pour les modèles externes, query le service de fournisseur de modèles en transmettant son nom dans un en-tête de requête.
from openai import OpenAI
client = OpenAI(
api_key=token,
base_url="https://<workspace-url>/ai-gateway/openai/v1",
default_headers={
"Databricks-Model-Provider-Service": "<catalog>.<schema>.<model-provider-service>"
},
)
response = client.chat.completions.create(
model="<provider-model-name>",
messages=[...],
)
For more query options, see Query model services and Query external model providers (model provider services).
Authentification : Unity Gateway prend en charge l’authentification par OAuth et par PAT. La portée PAT dont vous avez besoin dépend de l’URL :
- Route
/ai-gateway/du workspace : utilisez la portéeai-gatewayrecommandée et au moindre privilège. - Hôte
*.ai-gateway.*régional hérité : utilisez le périmètreall-apisplus large.
L’appel de l’ancienne URL régionale avec un jeton PAT étendu à ai-gatewayrenvoie 403: required scopes: all-apis. Déplacez le client vers l’URL du workspace /ai-gateway/, utilisez un jeton PAT étendu à ai-gateway, puis réessayez.
ai_query : remplacez le nom de l’Endpoint obsolète par le service de modèle correspondant fourni par Databricks dans system.ai. L’appelant doit disposer de EXECUTE sur ce service de modèle.
-- Legacy
SELECT ai_query('<legacy-endpoint-name>', 'Summarize: ' || text)
FROM my_table;
-- Unity Gateway
SELECT ai_query('system.ai.<model-name>', 'Summarize: ' || text)
FROM my_table;
ai_query prend en charge les services de modèles fournis par le système, et non les services de modèles personnalisés. Seul le suivi de l’utilisation s’applique. Les politiques de service, les tables d’inférence, les limites de débit et les fallbacks ne s’appliquent pas aux appels ai_query. Voir la fonctionai_query.
Coding agents : configurez un agent de codage pris en charge pour acheminer le trafic via Unity Gateway au lieu de vous connecter directement au fournisseur de modèles. Databricks fournit la CLI Unity Gateway (ug) pour cette configuration. Son installation nécessite Python 3.12 ou version ultérieure et uv.
uv tool install git+https://github.com/databricks/unity-gateway
Lancez un agent de codage pris en charge via Unity Gateway :
ug claude
ug codex
ug gemini
ug opencode
ug copilot
Si vous utilisez vos propres identifiants de fournisseur, créez d'abord un fournisseur de modèles externe, puis pointez l'agent de codage vers celui-ci. L'option --provider est prise en charge pour ug claude et ug codex.
ug claude --provider <catalog>.<schema>.<provider-service>
Consultez les rubriques Prise en main des agents de codage et Configurer la capacité du modèle.
Étape 4 : Valider le trafic migré
Vérifiez que le trafic hérité a cessé avant d'activer l'application. Interrogez la table system.serving.endpoint_usage pour chaque endpoint hérité et vérifiez que son nombre de requêtes est tombé à zéro et que l'heure de sa dernière requête est antérieure à votre migration.
Étape 5 : (Optionnel) Limiter le débit des anciens Endpoint lors d'une migration progressive
Pour migrer progressivement, définissez la limite de débit d’un endpoint hérité individuel sur 0 afin d’interdire le nouveau trafic tout en maintenant les autres endpoints hérités actifs. Répétez les étapes 2 à 5 pour chaque charge de travail restante.
Étape 6 : Activer Enforce Unity Gateway
Une fois que tout le trafic requis a été migré avec succès, activez le paramètre Enforce Unity Gateway pour désactiver les anciens endpoints pour le workspace. Consultez la section Étape 2 : Activer l'application de Unity Gateway pour connaître les modifications, la procédure d'activation du paramètre et ses limitations.