Unity Gateway へ移行する
Unity Gatewayは、エンタープライズAI向けのDatabricksコントロールプレーンです。Unity Catalogを基盤としており、データに使用しているのと同じ権限、コスト管理、ガードレール、オブザーバビリティを用いて、モデルサービス、外部モデルプロバイダー、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 | 既存のワークロードを移行し、モデルサービスの権限を確認します。個々のモデルに対して設定された権限は、対応するモデルサービスへのアクセス権を自動的には付与しません。 |
Unityゲートウェイで新しく始める
Unity Gatewayを初めて使用する場合や、新しいアカウントまたはワークスペースを設定する場合は、Unity Gatewayで直接起動します。
ステップ 1: Databricksでホストされるモデルサービスへのアクセスを確認する
Unity Gatewayは、system.ai スキーマですぐに使用できるDatabricksホスト型モデルサービスを提供します。アクセスできるユーザーを確認し、必要に応じてアクセスを制限します。
defaultでは、すべてのアカウントユーザーがシステム提供のモデルサービス上で EXECUTE を持っています。すべてのモデルサービスでも、system 上での USE CATALOG と、system.ai 上での USE SCHEMA が必要です。最小特権を適用するには、広範なスキーマアクセスを削除し、個別のモデルサービスに EXECUTE を付与します。基盤となるモデルの権限では、モデルサービスへのアクセスは付与されません。
操作 | 必要な権限 |
|---|---|
モデルサービスのクエリー |
|
モデルサービスを作成する |
|
外部モデルプロバイダーをクエリーする |
|
外部モデルプロバイダーを作成する |
|
管理タグおよび属性ベースのアクセスについては、GRANT ポリシーを参照してください。
If you were enrolled in the 基盤モデル Unity Catalog Permissions preview, permissions set on individual models don't automatically apply to the corresponding modelサービス.モデルサービスに対する最小特権の権限付与を確認し、再適用します。
ステップ 2: Unity Gateway の適用を有効にする
Enforce Unity Gateway ワークスペース設定をオンにしてレガシー AI Gateway エクスペリエンスを無効にし、すべての生成 AI トラフィックが Unity Catalog を通じてガバナンスされるようにします。有効にしない場合、既存のレガシー構成は変更されません。
強制適用を有効にすると、各製品サーフェスは次のように動作します：
サーフェス | 適用がオンの場合の動作 |
|---|---|
すべてのトークン単位の従量課金トラフィックは、モデルサービスを経由してルーティングする必要があります。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 Apps: model serving Endpoint リソース（
system.aiモデルへのアクセス権を持つ Service Principal）で構成されたアプリは動作を停止します。対応するsystem.aiモデルサービスでService PrincipalにEXECUTEを付与し、モデルサービスをクエリーするようにアプリを更新します。
既存のワークロードを移行する
アクティブなレガシーAIゲートウェイのワークロードがある場合は、適用を有効にする前に以下のステップに従ってください。
ステップ1: アクティブなレガシーの使用量を特定する
どのレガシーEndpointが引き続きトラフィックを受信しているか、どのワークスペースで受信しているか、そして誰がそれらを呼び出しているかを調べます。
- レガシーEndpointでの使用状況の追跡を有効にします。これを有効にしてもべき等であるため、安全に再実行できます。
- 最近のリクエスト、呼び出し元、および最後のリクエスト時刻について、
system.serving.endpoint_usageおよびsystem.serving.served_entitiesシステムテーブルに対してクエリーを実行します。アカウント管理者のみがこれらのテーブルに対してクエリーを実行できます。
ステップ2：モデルサービスとプロバイダーを構成する
レガシーEndpointで構成されたガバナンスは引き継がれません。既存の構成はレガシーEndpointに残ります。必要なモデルサービスまたは外部モデルプロバイダーを作成または特定し、権限、レート制限、予算、サービスポリシー、使用状況の追跡、推論テーブル、トラフィックルーティングとfallbackなどの依存している設定を再作成します。また、CI/CD または Infrastructure-as-Code ワークフローを更新して Unity Gateway APIs を使用するようにしてください。
各ワークロードタイプを次のターゲットに移行します。
既存のワークロード | 移行先 |
|---|---|
Databricksホスト型のトークン単位の従量課金モデル |
|
Databricksホスト型のプロビジョン済みthroughput | 既存のプロビジョニング スループット サービング Endpoint を維持し、それを参照する モデル サービスを作成します。モデル サービスに対する |
外部プロバイダー | 既存のプロバイダー、資格情報、公開されているモデル、および呼び出し元を使用して、外部モデルプロバイダーを作成します。直接クエリーを実行するか、モデル固有のガバナンスのためにモデルサービスを作成します。この場合、モデルサービスの設定が優先されます。 |
ステップ 3：クライアントを更新する
モデルサービスまたは外部モデルプロバイダーを設定した後、各ワークロードをUnity Gatewayに移行します。ゲートウェイURLと個人アクセストークン（PAT）のスコープを一緒に移行します。
API and SDK clients : Databricksでホストされるモデルの場合、ベースURLを /serving-endpoints から /ai-gateway/mlflow/v1 に変更し、モデルをEndpoint名から完全修飾モデルサービス名に変更します。
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=[...],
)
その他のクエリーオプションについては、モデルサービスのクエリーおよび外部モデルプロバイダーのクエリー（モデルプロバイダーサービス）を参照してください。
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 提供のモデルサービスに置き換えます。呼び出し元には、そのモデルサービスに対する 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 はシステム提供のモデルサービスをサポートしますが、カスタムモデルサービスはサポートしません。使用状況の追跡のみが適用されます。サービス ポリシー、推論テーブル、レート制限、および fallbacks は ai_query の呼び出しには適用されません。See ai_query function.
コーディングエージェント ：モデルプロバイダーに直接接続するのではなく、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 の有効化を参照してください。