モデルAPI（モデルサービス）の作成と管理

Unity Catalogで独自のモデル APIs（モデルサービス）を作成、共有、管理します。

ヒント

system.ai スキーマ内のシステム提供モデルAPIは、セットアップなしでクエリーを実行できます。追加のモデルを管理する場合や、カスタムEndpointを公開する場合にのみ、独自のモデルAPIを作成してください。

要件

• Unity AI GatewayでサポートされているリージョンにあるDatabricksワークスペース。
• ワークスペースでUnity Catalog有効化されていること。 Unity Catalog のワークスペースを有効にする方法をご覧ください。
• モデルサービスを作成するには、以下が必要です:
  • USE CATALOG、モデルサービスを作成するカタログとスキーマで、USE SCHEMA および CREATE SERVICE。
  • EXECUTE モデルサービスが宛先として参照する各モデルで。
  • EXECUTE、USE CATALOG、およびUSE SCHEMAを、モデルサービスが宛先として参照する各モデルプロバイダーサービス上で設定します。
  • USE CATALOG推論ログを有効にする場合、推論テーブルが作成されるカタログとスキーマにUSE SCHEMAとCREATE TABLEが設定されます。

モデルサービスを作成

Unity AI Gateway UI または Catalog Explorer でモデルサービスを作成できるほか、REST API、Databricks SDK、Databricks CLI、または Terraform を使用してプログラムで作成することもできます。

モデルサービスとモデルプロバイダーサービスは、Unity Catalogスキーマ内で単一の名前空間を共有します。スキーマ内のモデルプロバイダーサービスがすでに使用している場合、モデルサービスにその名前を使用することはできません。その逆も同様です。

UI

1. 以下のいずれかを実行します。

   • ワークスペースサイドバーで、 AI Gateway をクリックし、次に 作成 をクリックします。
   • カタログエクスプローラーで、モデルサービスを作成するスキーマに移動し、 作成 > サービス > モデルサービス をクリックします。

2. モデルサービスの名前を入力し、作成するカタログとスキーマを選択します。カタログエクスプローラーから開始すると、カタログエクスプローラーがカタログとスキーマを事前に設定します。

3. 提供するプライマリ送信先を選択します。この送信先は、ユーザーが EXECUTE を持ち、Unity AI Gateway が提供可能な Databricks ホスト型モデルか、またはユーザーが EXECUTE、USE CATALOG、および USE SCHEMA を持つ モデルプロバイダーサービス のいずれかになります。

4. 作成 をクリックします。

モデルサービスを作成すると、Databricks はその概要ページを開き、そこで開始したり、推論ログなどの追加機能を構成したりできます。

REST API

POSTを/api/2.1/unity-catalog/model-servicesに送信します、parentおよびmodel_service_idをクエリーパラメーターとして渡します。ルーティング構成には少なくとも1つの宛先が必要です：

Bash

databricks api post \
  "/api/2.1/unity-catalog/model-services?parent=schemas/main.default&model_service_id=my_model_service" \
  --json '{
  "comment": "Routes chat traffic to a foundation model",
  "config": {
    "routing": {
      "destinations": [
        {
          "name": "primary",
          "destination_type": "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL",
          "pay_per_token_config": { "model": "models/system.ai.databricks-gpt-5" },
          "traffic_percentage": 100
        }
      ]
    }
  }
}'

CLI

親スキーマとリーフ名を渡し、--json を設定に指定します。ルーティング設定には少なくとも1つの宛先が必要です。CLI をインストールするには、Databricks CLI のインストールまたは更新を参照してください。

Bash

databricks ai-gateway create-model-service schemas/main.default my_model_service --json '{
  "comment": "Routes chat traffic to a foundation model",
  "config": {
    "routing": {
      "destinations": [
        {
          "name": "primary",
          "destination_type": "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL",
          "pay_per_token_config": { "model": "models/system.ai.databricks-gpt-5" },
          "traffic_percentage": 100
        }
      ]
    }
  }
}'

Terraform

Databricks Terraform プロバイダーと databricks_ai_gateway_model_service リソースを使用して、モデルサービスを作成および管理します：

Hcl

resource "databricks_ai_gateway_model_service" "example" {
  parent           = "schemas/main.default"
  model_service_id = "my_model_service"
  comment          = "Routes chat traffic to a foundation model"

  config = {
    routing = {
      destinations = [{
        name                 = "primary"
        destination_type     = "DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL"
        pay_per_token_config = { model = "models/system.ai.databricks-gpt-5" }
        traffic_percentage   = 100
      }]
    }
  }
}

Python SDK

Databricks SDK for Python を使用してモデルサービスを作成および管理します：

Python

from databricks.sdk.service import catalog as c

model_service = w.ai_gateway.create_model_service(
    parent="schemas/main.default",
    model_service_id="my_model_service",
    model_service=c.ModelService(
        comment="Routes chat traffic to a foundation model",
        config=c.ModelServiceConfig(
            routing=c.ModelServiceConfigRoutingConfig(
                destinations=[
                    c.ModelServiceConfigDestinationConfig(
                        name="primary",
                        destination_type=(
                            c.ModelServiceConfigDestinationConfigDestinationType
                            .DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL
                        ),
                        pay_per_token_config=c.ModelServiceConfigPayPerTokenConfig(
                            model="models/system.ai.databricks-gpt-5"
                        ),
                        traffic_percentage=100,
                    )
                ]
            )
        ),
    ),
)

Go SDK

Databricks SDK for Goを使用してモデルサービスを作成および管理します：

Go

modelService, err := w.AiGateway.CreateModelService(ctx, catalog.CreateModelServiceRequest{
	Parent:         "schemas/main.default",
	ModelServiceId: "my_model_service",
	ModelService: catalog.ModelService{
		Comment: "Routes chat traffic to a foundation model",
		Config: &catalog.ModelServiceConfig{
			Routing: &catalog.ModelServiceConfigRoutingConfig{
				Destinations: []catalog.ModelServiceConfigDestinationConfig{{
					Name:            "primary",
					DestinationType: catalog.ModelServiceConfigDestinationConfigDestinationTypeDestinationTypePayPerTokenFoundationModel,
					PayPerTokenConfig: &catalog.ModelServiceConfigPayPerTokenConfig{
						Model: "models/system.ai.databricks-gpt-5",
					},
					TrafficPercentage: 100,
				}},
			},
		},
	},
})

Java SDK

Databricks SDK for Javaを使用してモデルサービスを作成および管理します：

Java

ModelServiceConfig config =
    new ModelServiceConfig()
        .setRouting(
            new ModelServiceConfigRoutingConfig()
                .setDestinations(
                    Collections.singletonList(
                        new ModelServiceConfigDestinationConfig()
                            .setName("primary")
                            .setDestinationType(
                                ModelServiceConfigDestinationConfigDestinationType
                                    .DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL)
                            .setPayPerTokenConfig(
                                new ModelServiceConfigPayPerTokenConfig()
                                    .setModel("models/system.ai.databricks-gpt-5"))
                            .setTrafficPercentage(100L))));

ModelService modelService =
    w.aiGateway()
        .createModelService(
            new CreateModelServiceRequest()
                .setParent("schemas/main.default")
                .setModelServiceId("my_model_service")
                .setModelService(
                    new ModelService()
                        .setComment("Routes chat traffic to a foundation model")
                        .setConfig(config)));

JS SDK

Databricks AI Gateway SDK for JavaScript を使用してモデルサービスを作成および管理します：

TypeScript

import { ModelServiceConfig_DestinationConfig_DestinationType as DestType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelService({
  parent: 'schemas/main.default',
  modelServiceId: 'my_model_service',
  modelService: {
    comment: 'Routes chat traffic to a foundation model',
    config: {
      routing: {
        destinations: [
          {
            name: 'primary',
            destinationType: DestType.DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL,
            typeConfig: {
              $case: 'payPerTokenConfig',
              payPerTokenConfig: { model: 'models/system.ai.databricks-gpt-5' },
            },
            trafficPercentage: 100,
          },
        ],
      },
    },
  },
});

モデルサービスへのアクセスを許可する

By default, モデルサービスの所有者のみがそのサービスに対してクエリーを実行できます。他のユーザーがモデルサービスに対してクエリーを実行できるようにするには、そのユーザーに対してモデルサービス上のEXECUTE権限と、そのカタログおよびスキーマ上のUSE CATALOG権限とUSE SCHEMA権限を付与してください。モデルサービスが推論テーブルにLogsを出力する場合、記録されたリクエストと応答を読み取れるように、そのテーブルに対してSELECT権限を付与してください。

UI

1. カタログエクスプローラーでモデルサービスを開くか、 AI Gateway に移動してサービスを選択します。
2. 権限 タブに移動します。
3. 付与 をクリックします。
4. アクセス権を付与するユーザー、グループ、またはService Principalを選択します。
5. EXECUTE 権限を選択します。
6. 付与 をクリックします。

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_service/main.default.my_model_service" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

アクセス権の付与と検出の詳細については、モデル APIs (モデルサービス) へのアクセスを検出および管理しますを参照してください。

モデルサービスで機能を設定する

Unity AI Gateway UIから、レート制限、推論ログ記録、ガードレールなどの機能をモデルサービスで構成します。これはUnity AI Gatewayエンドポイントで構成するのと同じ方法です。以下を参照してください:

• モデルサービスおよびMCPサービスにレート制限を適用する
• 推論テーブルへのリクエストと応答のLogs

推論ロギング

推論ロギングを有効にすると、Databricksは、指定した場所に事前定義されたスキーマを持つ新しい空のUnity Catalogテーブルを作成します。次の点に注意してください:

• ターゲットカタログとスキーマに対して、USE CATALOG、USE SCHEMA、およびCREATE TABLEを持っている必要があります。
• モデルサービスの作成者が推論テーブルの所有者です。あなたが許可しない限り、他のユーザーはアクセスできません。
• 指定された場所にテーブルがすでに存在する場合、モデルサービスの作成は失敗します。
• 推論テーブルは、モデルサービスとは独立したライフサイクルを持ちます。テーブルを削除すると、モデルサービスは動作を継続しますが、ログの記録を停止します。

推論テーブルの詳細については、「Logs 推論テーブルへのリクエストと応答」を参照してください。

モデルサービスを更新する

所有者であるか、MANAGE を持っている必要があります。

UI

Unity AI Gateway UIまたはCatalog Explorerからモデルサービスの構成を編集します。変更はインプレースで適用されます。

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/model-services/main.default.my_model_service?update_mask=comment" \
  --json '{"comment": "Updated: routes chat traffic"}'

CLI

Bash

databricks ai-gateway update-model-service model-services/main.default.my_model_service comment \
  --json '{"comment": "Updated: routes chat traffic"}'

Terraform

databricks_ai_gateway_model_serviceリソース上のcomment（またはその他の変更可能なフィールド）を編集し、再適用します。変更はその場で適用されます。

Python SDK

Python

from databricks.sdk.service import catalog as c
from google.protobuf.field_mask_pb2 import FieldMask

updated = w.ai_gateway.update_model_service(
    name="model-services/main.default.my_model_service",
    update_mask=FieldMask(paths=["comment"]),
    model_service=c.ModelService(comment="Updated: routes chat traffic"),
)

Go SDK

Go

updated, err := w.AiGateway.UpdateModelService(ctx, catalog.UpdateModelServiceRequest{
	Name:         "model-services/main.default.my_model_service",
	UpdateMask:   *fieldmask.New([]string{"comment"}),
	ModelService: catalog.ModelService{Comment: "Updated: routes chat traffic"},
})

Java SDK

Java

ModelService updated =
    w.aiGateway()
        .updateModelService(
            new UpdateModelServiceRequest()
                .setName("model-services/main.default.my_model_service")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelService(
                    new ModelService().setComment("Updated: routes chat traffic")));

JS SDK

TypeScript

import { modelServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateModelService({
  modelService: {
    name: 'model-services/main.default.my_model_service',
    comment: 'Updated: routes chat traffic',
  },
  updateMask: modelServiceFieldMask('comment'),
});

モデルサービスを削除

所有者であるか、MANAGE を持っている必要があります。system.ai のシステム提供モデルサービスは削除できません。

UI

Unity AI Gateway UI または Catalog Explorer でモデルサービスを開き、ケバブメニューから [ 削除 ] を選択します。

REST API

Bash

databricks api delete "/api/2.1/unity-catalog/model-services/main.default.my_model_service"

CLI

Bash

databricks ai-gateway delete-model-service model-services/main.default.my_model_service

Terraform

terraform destroyを実行するか、リソースブロックを削除して再適用します。

Python SDK

Python

w.ai_gateway.delete_model_service(name="model-services/main.default.my_model_service")

Go SDK

Go

err := w.AiGateway.DeleteModelService(ctx, catalog.DeleteModelServiceRequest{
	Name: "model-services/main.default.my_model_service",
})

Java SDK

Java

w.aiGateway()
    .deleteModelService(
        new DeleteModelServiceRequest().setName("model-services/main.default.my_model_service"));

JS SDK

TypeScript

await client.deleteModelService({ name: 'model-services/main.default.my_model_service' });

次のステップ

• モデルサービス
• モデルサービスをクエリーします。
• モデルサービスへのアクセスを検出し、管理します
• コーディングエージェントと統合する