外部モデルプロバイダー（モデルプロバイダーサービス）の作成と管理

外部モデルプロバイダーをモデルプロバイダーサービスとして登録し、アクセス権を付与し、Unity AIゲートウェイ機能を設定し、削除します。

要件

• CREATE SERVICE モデルプロバイダーサービスを作成するスキーマ上、そのカタログとスキーマに対するUSE CATALOGとUSE SCHEMAの権限。
• 登録する外部プロバイダーの認証情報（例：OpenAI API キーまたはAWSアクセスキーペア）。
• APIキーの代わりにサービス認証情報を使用してGoogle Gemini Enterpriseを認証するには、既存のサービス認証情報と、それに対するACCESSが必要です。サービス認証情報を使用してGoogle Gemini Enterpriseを認証するを参照してください。

モデルプロバイダーサービスを作成

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

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

UI

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

   • ワークスペースのサイドバーで [ AI Gateway ] をクリックし、[ Providers tab] を開いて [ Provider ] をクリックします。
   • カタログエクスプローラーで、モデルプロバイダーサービスを作成したいスキーマに移動し、 作成 > サービス をクリックしてから、 サービスの作成 ダイアログで モデルプロバイダーサービス を選択します。

2. モデルプロバイダーサービスの名前を入力し、作成するカタログとスキーマを選択します。Catalog Explorerから起動すると、Catalog Explorerがカタログとスキーマを事前に設定します。

3. プロバイダータイプを選択し、プロバイダーの接続の詳細と資格情報を入力します。

4. 作成 をクリックします。Databricksは資格情報を暗号化して保存します。この時点以降はUIに表示しません。

REST API

/api/2.1/unity-catalog/model-provider-services に POST を送信します。parent および model_provider_service_id をクエリーパラメーターとして渡します。provider_type と、それに対応するプロバイダーブロックを1つだけ設定します。targets は到達可能なアップストリームモデルを許可リストに登録し、シークレットはプレーンテキストとしてインラインで提供されます：

Bash

databricks api post \
  "/api/2.1/unity-catalog/model-provider-services?parent=schemas/main.default&model_provider_service_id=my_provider" \
  --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

CLI

親スキーマとリーフ名を渡し、--json を設定に指定します。provider_typeと、それに対応するプロバイダーブロックを1つだけ設定します。targetsは到達可能なアップストリームモデルを許可リストに登録し、シークレットはプレーンテキストとしてインラインで提供されます。CLIをインストールするには、「Databricks CLIのインストールまたは更新」を参照してください。

Bash

databricks ai-gateway create-model-provider-service schemas/main.default my_provider --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

Terraform

Databricks Terraformプロバイダーと databricks_ai_gateway_model_provider_service リソースを使用して、モデルプロバイダーサービスを作成および管理します。APIキーを sensitive = true 変数経由で渡すことで、実際のキーをソース管理に含めないようにします（-var または TF_VAR_provider_api_key 環境変数で設定します）：

Hcl

variable "provider_api_key" {
  type      = string
  sensitive = true
}

resource "databricks_ai_gateway_model_provider_service" "example" {
  parent                    = "schemas/main.default"
  model_provider_service_id = "my_provider"
  comment                   = "Routes to a custom OpenAI-compatible provider"

  config = {
    provider_type = "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM"

    targets = [{
      model            = "gpt-4o"
      native_api_types = ["openai/v1/chat/completions"]
    }]

    custom = {
      direct = {
        base_url = "https://api.example.com/v1"
        api_key  = { plaintext = var.provider_api_key }
      }
    }
  }
}

Python SDK

Databricks SDK for Pythonを使用して、モデルプロバイダーサービスを作成および管理します:

Python

from databricks.sdk.service import catalog as c

model_provider_service = w.ai_gateway.create_model_provider_service(
    parent="schemas/main.default",
    model_provider_service_id="my_provider",
    model_provider_service=c.ModelProviderService(
        comment="Routes to a custom OpenAI-compatible provider",
        config=c.ModelProviderServiceConfig(
            provider_type=(
                c.ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
            ),
            targets=[
                c.ModelProviderServiceConfigModelTargetConfig(
                    model="gpt-4o",
                    native_api_types=["openai/v1/chat/completions"],
                )
            ],
            custom=c.ModelProviderServiceConfigCustomProviderConfig(
                direct=c.ModelProviderServiceConfigCustomProviderDirectConfig(
                    base_url="https://api.example.com/v1",
                    api_key=c.ModelProviderServiceConfigProviderSecret(
                        plaintext="dummy-api-key"
                    ),
                )
            ),
        ),
    ),
)

Go SDK

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

Go

modelProviderService, err := w.AiGateway.CreateModelProviderService(ctx,
	catalog.CreateModelProviderServiceRequest{
		Parent:                 "schemas/main.default",
		ModelProviderServiceId: "my_provider",
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Routes to a custom OpenAI-compatible provider",
			Config: &catalog.ModelProviderServiceConfig{
				ProviderType: catalog.ModelProviderServiceConfigExternalModelProviderTypeExternalModelProviderTypeCustom,
				Targets: []catalog.ModelProviderServiceConfigModelTargetConfig{{
					Model:          "gpt-4o",
					NativeApiTypes: []string{"openai/v1/chat/completions"},
				}},
				Custom: &catalog.ModelProviderServiceConfigCustomProviderConfig{
					Direct: &catalog.ModelProviderServiceConfigCustomProviderDirectConfig{
						BaseUrl: "https://api.example.com/v1",
						ApiKey: &catalog.ModelProviderServiceConfigProviderSecret{
							Plaintext: "dummy-api-key",
						},
					},
				},
			},
		},
	})

Java SDK

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

Java

ModelProviderServiceConfig config =
    new ModelProviderServiceConfig()
        .setProviderType(
            ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM)
        .setTargets(
            Collections.singletonList(
                new ModelProviderServiceConfigModelTargetConfig()
                    .setModel("gpt-4o")
                    .setNativeApiTypes(
                        Collections.singletonList("openai/v1/chat/completions"))))
        .setCustom(
            new ModelProviderServiceConfigCustomProviderConfig()
                .setDirect(
                    new ModelProviderServiceConfigCustomProviderDirectConfig()
                        .setBaseUrl("https://api.example.com/v1")
                        .setApiKey(
                            new ModelProviderServiceConfigProviderSecret()
                                .setPlaintext("dummy-api-key"))));

ModelProviderService modelProviderService =
    w.aiGateway()
        .createModelProviderService(
            new CreateModelProviderServiceRequest()
                .setParent("schemas/main.default")
                .setModelProviderServiceId("my_provider")
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Routes to a custom OpenAI-compatible provider")
                        .setConfig(config)));

JS SDK

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

TypeScript

import { ModelProviderServiceConfig_ExternalModelProviderType as ProviderType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelProviderService({
  parent: 'schemas/main.default',
  modelProviderServiceId: 'my_provider',
  modelProviderService: {
    comment: 'Routes to a custom OpenAI-compatible provider',
    config: {
      providerType: ProviderType.EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM,
      targets: [{ model: 'gpt-4o', nativeApiTypes: ['openai/v1/chat/completions'] }],
      provider: {
        $case: 'custom',
        custom: {
          providerMode: {
            $case: 'direct',
            direct: {
              baseUrl: 'https://api.example.com/v1',
              authMode: {
                $case: 'apiKey',
                apiKey: {
                  value: { $case: 'plaintext', plaintext: 'dummy-api-key' },
                },
              },
            },
          },
        },
      },
    },
  },
});

プロバイダーの全リストとその認証方法については、外部モデルプロバイダー（モデルプロバイダーサービス）のガバナンスを参照してください。

サービス認証情報を使用してGoogle Gemini Enterpriseを認証する

API キーを保存する代わりに、サービス認証情報を使用して Google Gemini Enterprise プロバイダーを認証できます。サービス認証情報には、Unity Catalog が管理する Google Cloud サービスアカウントが保持されます。そのため、有効期間の長い API キーがモデルプロバイダーサービスにコピーされることはありません。Databricks は、そのサービスアカウントから有効期間の短いトークンを取得して、各リクエストを認証します。

モデルプロバイダーサービスを作成するで説明されているように、モデルプロバイダーサービスを作成します。プロバイダータイプとして Google Gemini Enterprise を選択し、GCPプロジェクトIDやリージョンを含む接続詳細を入力します。次に、 認証方法 を サービス認証情報 に設定し、APIキーを入力する代わりにその認証情報を選択します。サービス認証情報はシークレットのみを置き換えるため、GCPプロジェクトIDとリージョンは引き続き必要です。

次の要件を確認してください：

• モデルプロバイダーサービスの 所有者 は、サービス認証情報に対して ACCESS を持っています。Databricksはリクエストの処理時に所有者のアクセス権を再確認するため、プロバイダーの使用中は所有者がそのアクセス権を保持している必要があります。それを取り消すと、プロバイダーに対して EXECUTE を保持している呼び出し元を含め、すべてのユーザーのクエリーが停止します。所有者に認証情報へのアクセス権を付与するには：

  SQL

  GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;

• この資格情報の目的はストレージではなく、 サービス です。

• その認証情報は、リクエストの発信元であるワークスペースで使用可能です。そのワークスペースのバインドは引き続き適用されるため、モデルプロバイダーサービス自体はメタストアを共有するどのワークスペースからでも到達可能であっても、認証情報がバインドされていないワークスペースからのリクエストは失敗します。

• サービス資格情報のGoogle Cloudサービスアカウントには、クエリーを実行する予定のGeminiモデルを呼び出す権限が付与されています。サービス資格情報を作成するには、サービス資格情報の作成を参照してください。

プロバイダーに対してクエリーを実行する呼び出し元には、他のプロバイダーと同様の権限が必要です。彼らはサービス資格情報に対する権限を必要としません。これにより、資格情報自体が彼らの手の届かないところに保持されます。

モデルプロバイダーサービスは内部識別子によって資格情報を追跡するため、クエリーを失敗させることなく資格情報の名前を変更できます。

認証情報を削除するとクエリーは失敗しますが、モデルプロバイダーサービスがそれを参照しているという警告は表示されません。認証情報を削除する前に、この認証情報への参照がないことを確認してください。

既存のモデルプロバイダーサービスにおいて、サービス資格情報認証とAPIキー認証を切り替えることはできません。代わりに、新しいモデルプロバイダーサービスを作成してください。

カスタムプロバイダーの API キーをヘッダーで送信する

カスタムプロバイダーは、default で API キーをベアラートークンとして送信します。Endpoint が特定のヘッダーでキーを要求する場合は、API キーヘッダー認証を使用し、ヘッダー名を指定してください。その後、Databricks は各送信リクエストでキーを <header name>: <header value> として送信します。

モデルプロバイダーサービスを作成するで説明されているように、モデルプロバイダーサービスを作成します。プロバイダータイプとして Custom を選択し、 Auth method を API key header に設定して、Endpoint が期待する Header name (X-API-Key や Ocp-Apim-Subscription-Key など) と Header value を指定します。

これら2つのメソッドは相互に排他的です。カスタムプロバイダーは、ベアラートークンまたは名前付きヘッダーのいずれかを使用し、両方を使用することはできません。ヘッダー認証には、ヘッダーが1つ必要です。

ヘッダー名は有効なHTTPヘッダー名である必要があります（英数字および!#$%&'*+-.^_`|~の文字、最大255文字）。スペース、コロン、スラッシュ、改行など、その他の文字はすべて拒否されます。

モデルプロバイダーサービスへのアクセス権を付与する

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_provider_service/main.default.my_provider" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

CLI

Databricks CLI を使用して EXECUTE を付与します。CLI をインストールするには、Databricks CLI のインストールまたは更新を参照してください。

Bash

databricks grants update model_provider_service main.default.my_provider \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Terraform

Databricks Terraformプロバイダーと databricks_grant リソースを使用して EXECUTE を付与します：

Hcl

resource "databricks_grant" "example" {
  model_provider_service = "main.default.my_provider"
  principal              = "data-team"
  privileges             = ["EXECUTE"]
}

Python SDK

Databricks SDK for Python を使用して EXECUTE を付与します：

Python

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="model_provider_service",
    full_name="main.default.my_provider",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

Go SDK

Databricks SDK for Go を使用して EXECUTE を付与します：

Go

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "model_provider_service",
	FullName:      "main.default.my_provider",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Java SDK

Databricks SDK for Java を使用して EXECUTE を付与します：

Java

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("model_provider_service")
        .setFullName("main.default.my_provider")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

アクセス権の付与と検出の詳細については、外部モデルプロバイダー（モデルプロバイダーサービス）へのアクセスの検出と管理を参照してください。

機能の構成

モデルプロバイダーサービスはUnity Gatewayを経由するため、他のUnity Gatewayトラフィックで使用しているものと同じガバナンスおよびオブザーバビリティ機能を適用してください：

• 推論ロギング。 リクエストと応答をUnity CatalogテーブルにLogs。推論テーブルへのリクエストと応答のLogsを参照してください。
• レート制限。 1分あたりのクエリー数を制限して、容量とコストを管理します。モデルおよび MCP サービスのレート制限の適用 を参照してください。
• サービスポリシー。 サービスポリシーをアタッチすることで、安全でないコンテンツのブロックや機密データの伏せ字化など、各インタラクションのコンテンツを管理します。「AI保護対象のサービスポリシー」および「サービスポリシーの作成とアタッチ」を参照してください。

モデルプロバイダーサービスを更新

所有者であるか、MANAGEを持っている必要があります。プロバイダータイプは不変です。

UI

Unity Gateway UI またはカタログエクスプローラーから、モデルプロバイダーサービスの構成を編集します。変更はその場で適用されます。

REST API

Bash

databricks api patch \
  "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider?update_mask=comment" \
  --json '{"comment": "Updated: routes to a custom provider"}'

CLI

Bash

databricks ai-gateway update-model-provider-service model-provider-services/main.default.my_provider comment \
  --json '{"comment": "Updated: routes to a custom provider"}'

Terraform

databricks_ai_gateway_model_provider_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_provider_service(
    name="model-provider-services/main.default.my_provider",
    update_mask=FieldMask(paths=["comment"]),
    model_provider_service=c.ModelProviderService(
        comment="Updated: routes to a custom provider"
    ),
)

Go SDK

Go

updated, err := w.AiGateway.UpdateModelProviderService(ctx,
	catalog.UpdateModelProviderServiceRequest{
		Name:       "model-provider-services/main.default.my_provider",
		UpdateMask: *fieldmask.New([]string{"comment"}),
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Updated: routes to a custom provider",
		},
	})

Java SDK

Java

ModelProviderService updated =
    w.aiGateway()
        .updateModelProviderService(
            new UpdateModelProviderServiceRequest()
                .setName("model-provider-services/main.default.my_provider")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Updated: routes to a custom provider")));

JS SDK

TypeScript

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

const updated = await client.updateModelProviderService({
  modelProviderService: {
    name: 'model-provider-services/main.default.my_provider',
    comment: 'Updated: routes to a custom provider',
  },
  updateMask: modelProviderServiceFieldMask('comment'),
});

モデルプロバイダーサービスの削除

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

UI

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

REST API

Bash

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

CLI

Bash

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

Terraform

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

Python SDK

Python

w.ai_gateway.delete_model_provider_service(
    name="model-provider-services/main.default.my_provider"
)

Go SDK

Go

err := w.AiGateway.DeleteModelProviderService(ctx,
	catalog.DeleteModelProviderServiceRequest{
		Name: "model-provider-services/main.default.my_provider",
	})

Java SDK

Java

w.aiGateway()
    .deleteModelProviderService(
        new DeleteModelProviderServiceRequest()
            .setName("model-provider-services/main.default.my_provider"));

JS SDK

TypeScript

await client.deleteModelProviderService({
  name: 'model-provider-services/main.default.my_provider',
});

次のステップ

• 外部モデルプロバイダー (モデルプロバイダーサービス) のクエリー
• 外部モデルプロバイダー（モデルプロバイダーサービス）へのアクセスの検出と管理
• 外部モデルプロバイダー（モデルプロバイダーサービス）の管理