Migrer vers Unity Gateway
Unity Gateway est le plan de contrôle Databricks pour l’IA d’entreprise. Basé sur Unity Catalog, il gère les APIs de modèles, les fournisseurs de modèles externes, les serveurs MCP, les agents, les compétences et les outils à partir d’un même endroit, avec les mêmes privilèges, contrôles des coûts, garde-fous et 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 vos autorisations d’API de modèle. Les autorisations définies sur les modèles individuels n'accordent pas automatiquement l'accès à l'API de modèle correspondante. |
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 APIs de modèle hébergées par Databricks
Unity Gateway fournit des APIs de modèle hébergées par Databricks prêtes à l'emploi dans le schéma system.ai. Examinez qui peut y accéder et restrictez l'accès si nécessaire.
Par default, tous les utilisateurs du compte disposent de EXECUTE sur les APIs de modèle fournies par le système. Chaque API 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 APIs de modèle individuelles. Les autorisations des modèles sous-jacents n'accordent pas l'accès à l'API de modèle.
Action | Autorisations requises |
|---|---|
Interroger une API de modèle |
|
Créer une API 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 Foundation Model Unity Catalog Permissions, les autorisations définies sur les modèles individuels ne s'appliquent pas automatiquement aux model APIs correspondantes. Examinez et réappliquez vos attributions de moindre privilège sur les model APIs.
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 |
|---|---|
Tout le trafic de paiement par jeton doit transiter par une API de modèle. Les Endpoint de service de paiement par jeton fournis par Databricks (les modèles | |
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 les APIs de modèle fournies par Databricks danssystem.aiuniquement, et non les services de modèle que vous créez.- Databricks Apps : les applications configurées avec la ressource d'endpoint de mise en service du modèle (un Service Principal ayant accès aux modèles
system.ai) cessent de fonctionner. Accordez au Service PrincipalEXECUTEsur les APIs de modèlesystem.aicorrespondantes, et mettez à jour l'application pour query les APIs de modèle.
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 APIs et les fournisseurs de modèles
Governance configured on a legacy endpoint doesn't carry over. The existing configuration stays on the legacy endpoint. Create or identify the model API or external model provider you need, then re-create the settings you rely on, such as permissions, rate limits, budgets, service policies, usage tracking, inference tables, and traffic routing and fallbacks. Also update any CI/CD or Infrastructure-as-Code workflows to use 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 l’ API de modèle correspondante dans |
Throughput provisionné hébergé par Databricks | Conservez l’endpoint de service en mode throughput provisionné existant et créez une API de modèle qui y fait référence. Accordez |
Fournisseur externe | Créez un fournisseur de modèles externe avec votre fournisseur existant, vos credentials, vos modèles exposés et vos appelants. Interrogez-le directement ou créez une API de modèle pour une gouvernance spécifique au modèle. Dans ce cas, les paramètres de l’API de modèle ont la priorité. |
Étape 3 : Mettez à jour vos clients
Une fois que vous avez configuré l’API de modèle ou le fournisseur de modèles externes, déplacez chaque charge de travail vers Unity Gateway. Migrez ensemble 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 par Databricks, remplacez l’URL de base de /serving-endpoints par /ai-gateway/mlflow/v1 et modifiez le modèle en remplaçant le nom de l’endpoint par le nom complet de l’API 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=[...],
)
Pour plus d’options de requête, consultez query les APIs de modèle (services de modèle) et query les fournisseurs de modèles externes (services de fournisseur de modèles).
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 hérité par l’API de modèle fournie par Databricks correspondante dans system.ai. L’appelant a besoin de EXECUTE sur cette API 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 APIs de modèle fournies par Databricks, et non les services de modèle que vous créez. Seul le suivi de l’utilisation s’applique. Les politiques de service, les tables d’inférence, les limites de débit et les fallback ne s’appliquent pas aux appels ai_query. Voir 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.