Unity AI Gateway

Unity AI Gateway est la couche de gouvernance Databricks pour les endpoints LLM et les serveurs MCP. Elle impose des limites de débit, applique des garde-fous et assure le suivi de l'utilisation et des coûts. Consultez la présentation d'Unity AI Gateway pour une introduction complète au produit. Depuis votre application AppKit, vous appelez un endpoint gouverné à l'aide du plugin Model Serving. Cette page décrit l'intégration dans AppKit ainsi que la CLI permettant d'inspecter et de provisionner les endpoints.

Prérequis

• Databricks CLI v1.0.0+ avec un profil authentifié.
• Une application AppKit en cours d'exécution. Voir Démarrage rapide avec les Apps.
• Un endpoint de serving que votre application peut interroger. La plupart des workspaces disposent de foundation models hébergés par Databricks (préfixés databricks-, par exemple databricks-claude-sonnet-4-6) déjà configurés avec AI Gateway. Les identifiants de modèles changent au fil du temps : consultez la liste des modèles pris en charge pour connaître les noms actuels, ou exécutez Lister les endpoints disponibles pour voir ceux que votre workspace expose.

Appeler un endpoint gouverné depuis AppKit

Le plugin Model Serving prend en charge la plomberie HTTP, l'authentification et le streaming. Les noms des endpoints sont fournis par des variables d'environnement au runtime : le même code s'exécute donc en local comme en production.

Enregistrer le plugin

import { createApp, server, serving } from "@databricks/appkit";

const AppKit = await createApp({
  plugins: [
    server(),
    serving({
      endpoints: {
        chat: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" },
      },
    }),
  ],
});

chat est un alias que vous choisissez. Le plugin le résout au moment de la requête en lisant DATABRICKS_SERVING_ENDPOINT_NAME. Définissez cette variable d'environnement dans app.yaml :

env:
  - name: DATABRICKS_SERVING_ENDPOINT_NAME
    valueFrom: serving-endpoint

Lors du déploiement, Databricks Apps injecte le nom de l'endpoint dans le conteneur. En développement local, définissez la variable d'environnement dans .env.

Diffuser un flux depuis un composant React

import { useState } from "react";
import { useServingStream } from "@databricks/appkit-ui/react";

export function ChatPanel() {
  const [prompt, setPrompt] = useState("");
  const { stream, chunks, streaming, error, reset } = useServingStream(
    { messages: [{ role: "user", content: prompt }], max_tokens: 500 },
    { alias: "chat" },
  );

  return (
    <>
      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
      <button onClick={() => stream()} disabled={streaming || !prompt}>
        Send
      </button>
      <button onClick={reset}>Clear</button>
      {chunks.map((chunk, i) => (
        <pre key={i}>{JSON.stringify(chunk)}</pre>
      ))}
      {error && <p>{error}</p>}
    </>
  );
}

Le premier argument correspond au corps de la requête. Le second contient les options, dont l'alias. Le hook gère la connexion SSE, l'interrompt au démontage et accumule les chunks analysés dans l'état. Pour un appel sans streaming, utilisez useServingInvoke avec la même structure.

Pour les modèles de chat, extrayez le texte de chaque chunk (généralement chunk.choices?.[0]?.delta?.content) et concaténez-le pour l'affichage. Pendant le développement, afficher les chunks bruts au format JSON permet d'en confirmer la structure avant d'écrire votre logique d'affichage.

L'appeler depuis un gestionnaire de route

Pour l'orchestration d'agents, le pré/post-traitement ou la journalisation côté backend, appelez directement le plugin. Par défaut, les routes HTTP intégrées du plugin s'exécutent avec l'identité de l'utilisateur authentifié. Dans un gestionnaire de route personnalisé comme celui-ci, appelez explicitement .asUser(req) pour obtenir le même comportement par utilisateur.

AppKit.server.extend((app) => {
  app.post("/api/summarize", async (req, res) => {
    const { text } = req.body;
    const result = await AppKit.serving("chat")
      .asUser(req)
      .invoke({
        messages: [
          { role: "system", content: "Summarize the text in two sentences." },
          { role: "user", content: text },
        ],
      });
    res.json(result);
  });
});

Mode nommé ou mode par défaut

Les exemples ci-dessus utilisent le mode nommé avec un alias explicite. Omettez la configuration pour enregistrer un alias default adossé à DATABRICKS_SERVING_ENDPOINT_NAME. Le mode nommé permet de gérer plusieurs endpoints (chat, classificateur, embeddings) au sein d'une même application.

Gouvernance et Unity AI Gateway

La gouvernance s'applique côté Databricks, et non dans AppKit. Votre application appelle l'endpoint, et la passerelle applique la politique. Unity AI Gateway constitue le plan de contrôle du trafic IA : elle achemine les requêtes vers les modèles et les serveurs MCP, et applique les limites de débit, les contrôles de coûts, les politiques de service et le suivi de l'utilisation. Unity Catalog gouverne les modèles, les serveurs MCP et les fonctions sous-jacents. Pour connaître les fonctionnalités et la configuration actuelles, y compris les fonctionnalités en bêta que vous activez depuis la page Previews de la console de compte, consultez AI governance with Unity AI Gateway.

Dans AppKit, le plugin Model Serving appelle les endpoints de serving par leur nom. Cela inclut les foundation models (préfixe databricks-), les Knowledge Assistants, les Supervisor Agents et les agents Python personnalisés. Le plugin n'appelle pas les services de modèles Unity AI Gateway, qui sont des objets Unity Catalog interrogés par nom complet via l'API compatible OpenAI de la passerelle. Pour en utiliser un, consultez Query model services.

Pour plus de détails sur chacun d'eux, consultez :

• Services de modèles : overview et governance.
• Services de fournisseurs de modèles : overview et governance.
• Gouvernance des serveurs MCP : register an MCP service et govern it. Ce cas se présente lorsqu'un endpoint d'agent que vous appelez, par exemple un Supervisor Agent ou un agent Python personnalisé, s'adresse en interne à un serveur MCP. Les applications AppKit ne le configurent pas directement.
• Version précédente : AI Gateway on serving endpoints, où vous activez les fonctionnalités endpoint par endpoint et où les journaux d'utilisation sont écrits dans system.serving.endpoint_usage.

Lister les endpoints disponibles

Utilisez la CLI pour voir quels endpoints votre workspace expose et lesquels disposent déjà de fonctionnalités AI Gateway configurées. Chaque commande ci-dessous présente une invocation courante ainsi que l'ensemble complet de ses options. Exécutez databricks serving-endpoints <command> --help pour connaître le comportement actuel des options, la CLI faisant foi.

databricks serving-endpoints list -o json

Les endpoints de l'API Foundation Model (préfixés par databricks-) sont disponibles dans la plupart des workspaces, avec AI Gateway intégré. Par exemple, databricks-claude-sonnet-4-6. La disponibilité varie d'un workspace à l'autre.

[
  {
    "ai_gateway": {
      "usage_tracking_config": { "enabled": true }
    },
    "config": {
      "served_entities": [
        {
          "foundation_model": {
            "display_name": "Claude Sonnet 4.6",
            "name": "system.ai.databricks-claude-sonnet-4-6"
          },
          "name": "databricks-claude-sonnet-4-6"
        }
      ]
    },
    "name": "databricks-claude-sonnet-4-6",
    "state": { "config_update": "NOT_UPDATING", "ready": "READY" },
    "task": "llm/v1/chat"
  }
]

Inspecter un endpoint

databricks serving-endpoints get databricks-claude-sonnet-4-6 -o json

Recherchez ai_gateway dans la réponse pour confirmer qu'AI Gateway est bien configuré sur l'endpoint. get n'accepte aucune option propre à la commande en plus des options globales ; exécutez databricks serving-endpoints get --help si vous en avez besoin.

Interroger depuis le terminal

Pratique pour effectuer un test rapide d'un endpoint avant de l'intégrer à votre application.

databricks serving-endpoints query databricks-claude-sonnet-4-6 \
  --json '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'

Provisionner un endpoint

databricks serving-endpoints create my-model-endpoint \
  --json '{
    "config": {
      "served_entities": [
        {
          "name": "my-entity",
          "entity_name": "my-registered-model",
          "workload_size": "Small",
          "scale_to_zero_enabled": true
        }
      ]
    }
  }'

Attendez que l'endpoint passe à l'état READY avant de l'interroger. Pour une procédure pas à pas, consultez le modèle Create a Model Serving Endpoint.

Intégrations avec les agents de codage

Unity AI Gateway peut également régir les outils de codage IA tels que Cursor, Codex CLI et Gemini CLI, afin que leurs requêtes partagent une même facture, un même tableau de bord d'utilisation et les mêmes limites de débit. Databricks recommande ucode pour effectuer cette configuration. Consultez Integrate with coding agents pour connaître les étapes de configuration et la liste actuelle des outils pris en charge.

Et ensuite ?

Essayez l'application AI Chat pour intégrer un endpoint gouverné à votre application, ou découvrez les autres fonctionnalités liées aux agents : Genie Agents ou Endpoints d'agents personnalisés.