Unity Gateway へ移行する
Unity Gatewayは、エンタープライズAI向けのDatabricksコントロールプレーンです。Unity Catalog上に構築されており、データに使用しているのと同じ権限、コスト管理、ガードレール、および観測性により、モデルAPI、外部モデルプロバイダー、MCPサーバー、エージェント、スキル、およびツールを一箇所で管理します。従来のAI Gateway Endpointは単一のワークスペースにバインドされたままであり、このような一元的なガバナンスは提供されません。
このガイドを使用して、既存のモデルサービングおよびレガシー AI Gateway ワークロードを Unity Gateway に移行し、 Enforce Unity Gateway ワークスペース設定を有効にして、すべての生成 AI トラフィックが Unity Catalog を通じてガバナンスされるようにします。
要件
- Unity Catalogが有効化されているDatabricks ワークスペース。 Unity Catalog のワークスペースを有効にする方法をご覧ください。
- ワークスペース管理者が Unity Gateway の適用 設定を有効にするためのアクセス。
- レガシー トラフィックを特定する際に
system.serving使用状況テーブルをクエリーするためのアカウント管理者アクセス。
移行パスの選択
状況に一致するパスを選択してください。
お客様の状況 | 推奨パス |
|---|---|
AI Gateway を使用していない場合、日常的にのみ使用している場合、または新しいアカウントやワークスペースを設定している場合 | |
アクティブなレガシー AI Gateway ワークロードが存在します | |
You enrolled in the 基盤モデル Unity Catalog Permissions preview | 既存のワークロードを移行し、モデル API の権限を確認します。個々のモデルに設定された権限は、対応するモデル API へのアクセスを自動的には付与しません。 |
Unityゲートウェイで新しく始める
Unity Gatewayを初めて使用する場合や、新しいアカウントまたはワークスペースを設定する場合は、Unity Gatewayで直接起動します。
ステップ1: Databricksホスト型モデルAPIへのアクセスを確認する
Unity Gatewayは、system.aiスキーマですぐに使用できるDatabricksホスト型モデルAPIsを提供します。アクセスできるユーザーを確認し、必要に応じてアクセスを制限します。
By default, all アカウント users have EXECUTE on system-provided model APIs.また、すべてのモデル API では、system の USE CATALOG と system.ai の USE SCHEMA が必要です。最小特権を適用するには、広範なスキーマアクセスを削除し、個別のモデル APIs で EXECUTE を付与します。基盤となるモデルの権限は、モデル API アクセスを付与しません。
操作 | 必要な権限 |
|---|---|
モデルAPIのクエリー |
|
モデル API を作成する |
|
外部モデルプロバイダーをクエリーする |
|
外部モデルプロバイダーを作成する |
|
管理タグおよび属性ベースのアクセスについては、GRANT ポリシーを参照してください。
基盤モデル Unity Catalog Permissions preview に登録していた場合、個々のモデルに設定された権限は、対応するモデル APIs に自動的には適用されません。モデル API で最小権限の付与を見直し、再適用します。
ステップ 2: Unity Gateway の適用を有効にする
Enforce Unity Gateway ワークスペース設定をオンにしてレガシー AI Gateway エクスペリエンスを無効にし、すべての生成 AI トラフィックが Unity Catalog を通じてガバナンスされるようにします。有効にしない場合、既存のレガシー構成は変更されません。
強制適用を有効にすると、各製品サーフェスは次のように動作します：
サーフェス | 適用がオンの場合の動作 |
|---|---|
すべてのトークン単位の従量課金のトラフィックは、モデルAPIを経由してルーティングする必要があります。Databricks提供のトークン単位の従量課金サービングエンドポイント（ | |
Unity Gatewayなしでプロビジョニング済みthroughputのサービングEndpointを作成することはできなくなりました。既存のEndpointはそのまま維持され、クエリを実行可能です。 | |
Unity Gatewayなしで外部モデルサービングEndpointを作成することはできなくなりました。既存のEndpointはそのまま維持され、クエリを実行可能な状態に保たれます。 |
設定を有効にするには：
- ワークスペース管理者として Databricks ワークスペースにログインします。
- [設定] > [詳細設定] に移動します。
- [Enforce Unity Gateway] をオンにします。
強制が有効になった後、無効になったトークン単位の従量課金サービングEndpointへのリクエストは、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."
}
適用を有効にすると、アクティブなレガシーEndpointへのトラフィックが停止します。ワークスペースでレガシーワークロードを実行している場合は、設定を有効にする前に、既存のワークロードの移行を完了し、トラフィックが移行されたことを検証してください。
レガシーAI Gateway Endpointがあるワークスペースでは、 Enforce Unity Gateway 設定を利用できます。トラフィックがゼロに低下した後も利用可能なままであるため、移行の終了時に有効にすることができます。新しいワークスペースでは、defaultで強制が有効になっており、設定は表示されません。ワークスペースで設定を利用できない場合は、移行を完了して検証した後に、Databricksアカウントチームにお問い合わせください。
強制適用がオンの場合、レガシーサービングEndpointに依存していたすべての製品がUnity Gatewayへの移行を完了しているわけではないため、次の制限事項が適用されます：
- AI Search: Unity Gatewayを介したAI Searchエンドポイントの作成はまだサポートされていません。AI Search Endpointに依存するKnowledge AssistantおよびMulti-Agent Supervisorエージェントは機能しません。
ai_query:ai_queryは、作成したモデルサービスではなく、system.ai内のDatabricks提供のモデルAPIのみをサポートします。- Databricks Apps: model serving Endpointリソース（
system.aiモデルへのアクセス権を持つサービスプリンシパル）で構成されたアプリは機能しなくなります。対応するsystem.aiモデル APIs で Service Principal にEXECUTEを付与し、アプリを更新して モデル APIs をクエリーします。
既存のワークロードを移行する
アクティブなレガシーAIゲートウェイのワークロードがある場合は、適用を有効にする前に以下のステップに従ってください。
ステップ1: アクティブなレガシーの使用量を特定する
どのレガシーEndpointが引き続きトラフィックを受信しているか、どのワークスペースで受信しているか、そして誰がそれらを呼び出しているかを調べます。
- レガシーEndpointでの使用状況の追跡を有効にします。これを有効にしてもべき等であるため、安全に再実行できます。
- 最近のリクエスト、呼び出し元、および最後のリクエスト時刻について、
system.serving.endpoint_usageおよびsystem.serving.served_entitiesシステムテーブルに対してクエリーを実行します。アカウント管理者のみがこれらのテーブルに対してクエリーを実行できます。
ステップ2：モデルAPIとプロバイダーの構成
レガシーEndpointで構成されたガバナンスは引き継がれません。既存の構成はレガシーEndpointに残ります。必要なモデル API または外部モデルプロバイダーを作成または特定し、アクセス権、レート制限、予算、サービスポリシー、使用状況の追跡、推論テーブル、トラフィックルーティングおよび fallback などの、依存している設定を再作成します。また、Unity Gateway APIs を使用するように、CI/CD ワークフローや Infrastructure-as-Code ワークフローも更新してください。
各ワークロードタイプを次のターゲットに移行します。
既存のワークロード | 移行先 |
|---|---|
Databricksホスト型のトークン単位の従量課金モデル |
|
Databricksホスト型のプロビジョン済みthroughput | 既存のプロビジョニング済みスループットのサービングEndpointを維持し、それを参照する モデル API を作成します。モデル API に対する |
外部プロバイダー | 既存のプロバイダー、資格情報、公開モデル、呼び出し元を使用して、外部モデルプロバイダーを作成します。直接クエリーするか、モデル固有のガバナンスのためにモデル API を作成します。その場合、モデル API の設定が優先されます。 |
ステップ 3：クライアントを更新する
モデルAPIまたは外部モデルプロバイダーを設定した後、各ワークロードをUnity Gatewayに移行します。ゲートウェイURLとパーソナルアクセストークン（PAT）のスコープを一緒に移行します。
API および SDK クライアント ：Databricks でホストされるモデルの場合は、ベース URL を /serving-endpoints から /ai-gateway/mlflow/v1 に変更し、モデルをEndpoint名から完全修飾モデル API 名に変更します。
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=[...],
)
外部モデルの場合は、リクエストヘッダーに名前を渡してモデルプロバイダーサービスに対してクエリーを実行します。
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=[...],
)
その他のクエリーオプションについては、モデル APIs (モデルサービス) のクエリーおよび外部モデルプロバイダー (モデルプロバイダーサービス) のクエリーを参照してください。
Authentication : Unity GatewayはOAuthおよびPAT認証の両方をサポートしています。必要なPATのスコープはURLによって異なります。
- ワークスペース
/ai-gateway/ルート ：推奨される最小権限のai-gatewayスコープを使用します。 - レガシーリージョナル
*.ai-gateway.*ホスト : より広範なall-apisスコープを使用します。
ai-gatewayスコープのPATを使用してレガシーリージョンURLを呼び出すと、403: required scopes: all-apisが返されます。クライアントをワークスペース/ai-gateway/のURLに移動し、ai-gatewayスコープのPATを使用して、再試行してください。
ai_query : レガシーEndpoint名を、system.ai内の対応するDatabricks提供のモデル APIに置き換えます。呼び出し元には、そのモデル API に対する EXECUTE が必要です。
-- 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 Databricks提供のモデルAPIをサポートし、作成したモデルサービスはサポートしません。使用状況の追跡のみが適用されます。サービスポリシー、推論テーブル、レート制限、およびfallbackは、ai_queryの呼び出しには適用されません。ai_query関数を参照してください。
コーディングエージェント ：モデルプロバイダーに直接接続するのではなく、Unity Gateway を経由するようにサポートされているコーディングエージェントを構成します。Databricks では、このセットアップのために Unity Gateway CLI（ug）を提供しています。インストールするには、Python 3.12 以降および uv が必要です。
uv tool install git+https://github.com/databricks/unity-gateway
Unity Gateway を介して、サポートされているコーディングエージェントを起動します。
ug claude
ug codex
ug gemini
ug opencode
ug copilot
独自のプロバイダー資格情報を使用する場合は、まず外部モデルプロバイダーを作成し、そこにコーディングエージェントを指定します。ug claude および ug codex では、--provider オプションがサポートされています。
ug claude --provider <catalog>.<schema>.<provider-service>
コーディングエージェントの基本とモデル容量の設定を参照してください。
ステップ4：移行済みトラフィックを検証する
適用を有効にする前に、レガシートラフィックが停止していることを確認します。各レガシー Endpoint の system.serving.endpoint_usage テーブルをクエリーし、リクエスト数がゼロに減少し、最終リクエスト時刻が移行前であることを確認します。
ステップ 5: (オプション) 段階的な移行中にレガシーEndpointのスロットリングを行う
段階的に移行するには、個々のレガシーEndpointのレート制限を 0 に設定して、他のレガシーEndpointをアクティブにしたまま新しいトラフィックを停止します。残りの各ワークロードについて、ステップ 2～5 を繰り返します。
ステップ 6: Unityゲートウェイの適用を有効にする
必要なすべてのトラフィックの移行が正常に完了したら、 Enforce Unity Gateway 設定を有効にして、ワークスペースのレガシーEndpointを無効にします。変更内容、設定を有効にする方法、および制限事項については、ステップ 2: Enforce Unity Gateway の有効化を参照してください。