Unity AI Gateway

Unity AI Gateway は、LLM endpoint と MCP サーバーを対象とした Databricks のガバナンスレイヤーです。レート制限の適用、ガードレールの適用、使用量とコストの追跡を行います。製品全体の紹介については Unity AI Gateway の概要 を参照してください。AppKit アプリからは、Model Serving プラグインを使ってガバナンス対象の endpoint を呼び出します。このページでは、AppKit での接続方法と、endpoint の確認・プロビジョニングに使う CLI について説明します。

前提条件

• 認証済みプロファイルを設定した Databricks CLI v1.0.0+。
• 実行中の AppKit アプリ。Apps クイックスタートを参照してください。
• アプリからクエリできる サービング endpoint。ほとんどのワークスペースには、AI Gateway が事前構成された Databricks ホスト型の foundation model（databricks- で始まるもの。たとえば databricks-claude-sonnet-4-6）が用意されています。モデル ID は随時変更されるため、最新の名前はサポートされているモデルの一覧で確認するか、利用可能な endpoint の一覧表示を実行して、ご利用のワークスペースで公開されているものを確認してください。

AppKit からガバナンス対象の endpoint を呼び出す

Model Serving プラグイン が HTTP 通信、認証、ストリーミングの処理を担います。endpoint 名は runtime に環境変数から取得されるため、同じコードをローカルでも本番でもそのまま動かせます。

プラグインを登録する

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

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

chat は自由に決められるエイリアスです。プラグインはリクエスト時に DATABRICKS_SERVING_ENDPOINT_NAME を読み取って解決します。app.yaml で次のように環境変数をバインドします。

env:
  - name: DATABRICKS_SERVING_ENDPOINT_NAME
    valueFrom: serving-endpoint

デプロイ時に、Databricks Apps が endpoint 名をコンテナに注入します。ローカル開発では、.env に環境変数を設定してください。

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>}
    </>
  );
}

第1引数はリクエストボディです。第2引数には、エイリアスなどのオプションを指定します。このフックはSSE接続を管理し、アンマウント時に接続を中断して、パース済みのチャンクをstateに蓄積します。ストリーミングしない呼び出しには、同じ形式で useServingInvoke を使用してください。

チャットモデルの場合は、各チャンクからテキスト (通常は chunk.choices?.[0]?.delta?.content) を抽出し、連結して表示します。開発時には、生のチャンクをJSONとして描画しておくと、表示ロジックを組み立てる前にデータ構造を確認できます。

ルートハンドラーから呼び出す

エージェントのオーケストレーション、前処理・後処理、バックエンドでのログ記録を行う場合は、プラグインを直接呼び出します。プラグインに組み込まれた HTTP ルートは、デフォルトで認証済みユーザーとして実行されます。以下のようなカスタムルートハンドラーでは、.asUser(req) を明示的に呼び出すことで、同じユーザー単位の動作になります。

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);
  });
});

名前付きモードとデフォルトモード

上記の例では、明示的なエイリアスを指定する名前付きモードを使用しています。設定を省略すると、DATABRICKS_SERVING_ENDPOINT_NAME を参照する default エイリアスが登録されます。名前付きモードなら、同じアプリ内で複数の endpoint（チャット、分類器、埋め込み）へ拡張できます。

ガバナンスと Unity AI Gateway

ガバナンスは AppKit ではなく Databricks 側で適用されます。アプリが endpoint を呼び出すと、ゲートウェイがポリシーを適用します。Unity AI Gateway は AI トラフィックのコントロールプレーンであり、モデルおよび MCP のリクエストをルーティングし、レート制限、コスト管理、サービスポリシー、使用状況の追跡を適用します。その背後にあるモデル、MCP サーバー、関数は Unity Catalog が管理します。現在の機能とセットアップ方法（アカウントコンソールの Previews ページから有効化できるベータ機能を含む）については、AI governance with Unity AI Gateway を参照してください。

AppKit では、Model Serving プラグインがサービング endpoint を名前で呼び出します。対象となるのは foundation model（databricks- プレフィックス）、Knowledge Assistant、Supervisor Agent、カスタム Python エージェントです。このプラグインは Unity AI Gateway のモデルサービスは呼び出しません。モデルサービスは Unity Catalog オブジェクトであり、ゲートウェイの OpenAI 互換 API を通じて完全修飾名でクエリします。利用方法については Query model services を参照してください。

それぞれの詳細は以下を参照してください。

• モデルサービス: overview と governance。
• モデルプロバイダーサービス: overview と governance。
• MCP サーバーのガバナンス: register an MCP service と govern it。これは、呼び出し先のエージェント endpoint（Supervisor Agent やカスタム Python エージェントなど）が内部で MCP サーバーにルーティングする場合に該当します。AppKit アプリ側で直接設定するものではありません。
• 以前のバージョン: AI Gateway on serving endpoints。endpoint ごとに機能を切り替え、使用状況ログは system.serving.endpoint_usage に記録されます。

利用可能な endpoint の一覧表示

CLI を使うと、ワークスペースが公開している endpoint と、そのうち AI Gateway 機能がすでに構成済みのものを確認できます。以下の各コマンドでは、代表的な実行例と利用可能なフラグの一覧を示します。フラグの最新の挙動は databricks serving-endpoints <command> --help で確認してください。CLI が信頼できる情報源です。

databricks serving-endpoints list -o json

foundation model API の endpoint (接頭辞 databricks-) は、AI Gateway が組み込まれたほとんどのワークスペースで利用できます。たとえば databricks-claude-sonnet-4-6 などです。利用できるかどうかはワークスペースによって異なります。

[
  {
    "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"
  }
]

endpoint を確認する

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

レスポンスに ai_gateway が含まれているかを確認し、endpoint に AI Gateway が設定されていることを確かめます。get にはグローバルフラグ以外にコマンド固有のフラグはないため、必要に応じて databricks serving-endpoints get --help を実行してください。

ターミナルからクエリを実行する

アプリに組み込む前に、endpoint の動作を手軽に確認したい場合に便利です。

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

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

クエリを実行する前に、endpoint が READY 状態になるまで待ちます。手順の詳細については、Create a Model Serving Endpoint template を参照してください。

コーディングエージェントとの統合

Unity AI Gateway は、Cursor、Codex CLI、Gemini CLI といった AI コーディングツールもガバナンスの対象にできます。これにより、これらのツールからのリクエストを単一の請求、使用状況ダッシュボード、レート制限で一元的に管理できます。Databricks では、このセットアップに ucode を使用することを推奨しています。セットアップ手順と現在サポートされているツールの一覧については、コーディングエージェントとの統合を参照してください。

次のステップ

AI Chat App を試して、ガバナンス対象の endpoint をアプリに組み込んでみましょう。他のエージェント機能もあわせてご覧ください。Genie Agents や Custom agent endpoints もおすすめです。