自訂模型服務

模型服務是一個端點，將推理請求轉換並路由到一個或多個模型，具備流量分割與備援功能。它支援即時請求，以及批次推論。

為以下使用情境建立自訂模型服務：

一個與模型無關的應用程式端點。 給一位客服助理一個名為 production.ai.support-assistant的服務。在不更改應用程式呼叫名稱的情況下，改變底層模型。
自訂路由與備援。 使用流量分割功能，先將 10% 流量傳送到新模型，然後再大規模部署，或設定備用目的地以應對失敗的請求。
單一工作負載的預算。 使用 project=support-assistant 為服務加上標籤，並將每月預算套用至該標籤，在支出達到 1,000 美元時發出警示。
團隊的存取控制。 授權法律團隊及其應用服務負責人使用某項 legal-review 服務，並為其他團隊使用獨立服務。
工作負載的速率限制。 將測試服務設定為每分鐘 100 個請求，生產服務則設定為每分鐘 1,000 個請求，並使用服務速率限制。
分開監控和記錄。 將支援助理的請求和回應傳送到專用的推論資料表，以便將其流量與程式碼代理的流量分開檢查。

若要查詢由 Azure Databricks 服務的基礎模型而不建立服務，請使用系統提供的模型服務。system.ai

服務可透過按代幣付費或配置吞吐量路由至 Azure Databricks 所服務的模型，或透過模型提供者導向外部模型。你可以將這些目的地混合在同一項服務中。

自訂模型服務是 Unity Catalog 可保護的服務。呼叫端會透過其完整限定名稱 catalog.schema.name，跨工作區或從 Azure Databricks 外部叫用它們。參見治理與特權。

Requirements

注意

Unity Gateway 在 Azure Government 上不支援。

一個位於 Unity Gateway 支援區域的 Azure Databricks workspace。
已為您的工作區啟用了 Unity Catalog。請參閱為 Unity Catalog 啟用工作區。
要建立模型服務，您必須具備：
- USE CATALOG、USE SCHEMA 和 CREATE SERVICE，位於你建立模型服務所在的目錄和結構描述中。
- EXECUTE 在模型服務參考為目標的每個模型上。
- EXECUTE、USE CATALOG及USE SCHEMA（位於該模型服務參考作為目標的每個模型提供者上）。
- 如果您啟用推論記錄功能，則需要在建立推論資料表的目錄和結構描述上具備 USE CATALOG、USE SCHEMA 和 CREATE TABLE。

建立自訂模型服務

在 Unity Gateway 介面或目錄檔案總管中建立模型服務。若要程式化建立，請使用 REST API、Azure Databricks SDK、Azure Databricks CLI、Terraform 或宣告式自動化套件（DABs）。

模型服務與模型提供者在 Unity 目錄架構中共用單一命名空間。如果模型提供者在結構中已經使用該名稱，你就不能用該名稱來稱呼模型服務，反之亦然。

UI

執行下列其中一個動作：
- 在工作區的側邊欄中，按一下 AI Gateway，然後按一下建立。
- 在 Catalog Explorer 中，前往您要建立模型服務的結構描述，然後按一下建立>服務>模型服務。
輸入模型服務的名稱，並選取要在其中建立該服務的目錄和結構描述。如果你是從目錄瀏覽器開始，目錄瀏覽器會預先填入目錄和綱要。
選擇主要服務目的地。此目的地可以是你已在其上設定EXECUTE，且可由 Unity Gateway 提供服務的 Azure Databricks 模型，或是你已在其上進行、USE CATALOG和USE SCHEMA的EXECUTE。
點擊建立。

建立模型服務後，Azure Databricks 會開啟總覽頁面，您可以開始或設定推論日誌等額外功能。

REST API

將 a POST 傳送到 /api/2.1/unity-catalog/model-services，並傳遞 parent 和 model_service_id 作為查詢參數。路由設定必須至少有一個目的地：

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 提供設定。路由設定必須至少有一個目的地。要安裝 CLI，請參見「安裝或更新 Databricks CLI」。

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 資源建立並管理模型服務：

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

DABs（測試版）

在套件中定義模型服務，並使用databricks bundle deploy部署它。路由設定必須至少有一個目的地：

resources:
  model_services:
    my_model_service:
      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 建立並管理模型服務：

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 建立並管理模型服務：

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

Go Modular SDK

使用 Databricks AI Gateway SDK for Go 建立並管理模型服務。可選欄位是指標，因此範例中使用一個單行輔助函式 func ptr[T any](v T) *T { return &v }。

modelService, err := c.CreateModelService(ctx, aigateway.CreateModelServiceRequest{
	Parent:         ptr("schemas/main.default"),
	ModelServiceId: ptr("my_model_service"),
	ModelService: &aigateway.ModelService{
		Comment: ptr("Routes chat traffic to a foundation model"),
		Config: &aigateway.ModelServiceConfig{
			Routing: &aigateway.ModelServiceConfig_RoutingConfig{
				Destinations: []aigateway.ModelServiceConfig_DestinationConfig{{
					Name:              ptr("primary"),
					DestinationType:   aigateway.ModelServiceConfig_DestinationConfig_DestinationType_DestinationTypePayPerTokenFoundationModel,
					TrafficPercentage: ptr(100),
					TypeConfig: &aigateway.ModelServiceConfig_DestinationConfig_TypeConfig_PayPerTokenConfig{
						PayPerTokenConfig: aigateway.ModelServiceConfig_PayPerTokenConfig{
							Model: ptr("models/system.ai.databricks-gpt-5"),
						},
					},
				}},
			},
		},
	},
})

Java 開發套件

使用 Databricks SDK for 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 建立並管理模型服務：

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

授予模型服務存取權限

預設情況下，只有模型服務擁有者能查詢它。若要讓其他人查詢模型服務，請授予他們該服務上的 EXECUTE，以及其目錄和綱要上的 USE CATALOG 和 USE SCHEMA。如果模型服務將記錄寫入推論資料表，請授予他們對該資料表的 SELECT 權限，讓他們能讀取已記錄的請求與回應。

UI

在目錄檔案總管中開啟模型服務，或前往 AI Gateway 選擇服務。
前往權限標籤。
請按一下授權。
選擇要授權存取的使用者、群組或服務主體。
選擇執行權限。
請按一下授權。

REST API

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

CLI

使用 Databricks CLI 來申請 Grant EXECUTE 。要安裝 CLI，請參見「安裝或更新 Databricks CLI」。

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

Terraform

使用 databricks_grant 和 EXECUTE 資源授予：

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

DABs（測試版）

在你的套件中新增 grants 一個區塊到模型服務資源，然後重新部署以授權存取權限。

resources:
  model_services:
    my_model_service:
      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
      grants:
        - principal: data-team
          privileges: [EXECUTE]

Python SDK

Grant EXECUTE 使用適用於 Python 的 Databricks SDK：

from databricks.sdk.service import catalog as c

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

Go 軟體開發套件 (SDK)

使用 EXECUTE 授予：

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

Java 開發套件

使用適用於 Java 的 Databricks SDK 授予 EXECUTE：

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

關於授權與發現存取權的更多資訊，請參閱「發現與治理模式服務存取」。

在模型服務上配置功能

在 Unity Gateway UI 中，於模型服務上設定速率限制、推論日誌，以及以服務原則實作的防護機制。 See:

推論日誌

啟用推論記錄時，Azure Databricks 會在你指定的位置建立一個新的空白 Unity Catalog 資料表，其結構描述為預先定義。請注意下列事項：

你必須擁有 USE CATALOG、 USE SCHEMA，以及 CREATE TABLE 在目標目錄和結構中。
模型服務的創建者是推論表的擁有者。除非你授權，否則其他使用者無法存取。
如果指定位置已有資料表，建立模型服務將失敗。
推論表的生命週期與模型服務獨立。如果你把表格放下，模型服務會繼續運作，但會停止記錄。

關於推論表的更多資訊，請參見對推論表的日誌請求與回應。

更新模型服務

您必須是擁有者或具有 MANAGE 權限。

UI

從 Unity Gateway 介面或目錄總管中編輯模型服務的設定。現地變更適用。

REST API

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

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（或任何其他可變欄位），然後重新套用。現地變更適用。

DABs（測試版）

在 bundle 資源中編輯 comment （或其他可變欄位）並執行 databricks bundle deploy。現地變更適用。

Python SDK

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)

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"},
})

Go Modular SDK

mask, err := types.NewFieldMask[aigateway.ModelService]("comment")
updated, err := c.UpdateModelService(ctx, aigateway.UpdateModelServiceRequest{
	ModelService: &aigateway.ModelService{
		Name:    ptr("model-services/main.default.my_model_service"),
		Comment: ptr("Updated: routes chat traffic"),
	},
	UpdateMask: mask,
})

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

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 Gateway 介面或目錄總管中開啟模型服務，並從烤肉串選單中選擇刪除。

REST API

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

CLI

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

Terraform

執行 terraform destroy，或移除資源區塊並重新套用。

DABs（測試版）

將資源從套件組合中移除，然後執行 databricks bundle deploy 將其刪除。 databricks bundle destroy 這也可行，但它會移除該組合包管理的所有資源，不只是這個。

Python SDK

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

Go 軟體開發套件 (SDK)

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

Go Modular SDK

err := c.DeleteModelService(ctx, aigateway.DeleteModelServiceRequest{
	Name: ptr("model-services/main.default.my_model_service"),
})

Java 開發套件

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

JS 模組化 SDK

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

治理與特權

作為 Unity 目錄可保護的物件，一個模型服務：

存在於目錄與結構中，繼承像工作區綁定等結構設定。
攜帶標準的 Unity 目錄元資料，如名稱、擁有者、註解和標籤。
它受 Unity 目錄權限管理，所以你使用與GRANTREVOKE表格、函式和模型相同的語句授權存取權限。
可在 Catalog Explorer 中找到，與你的其他 Unity Catalog 資產一起。

適用以下特權：

特權	Description
`USE CATALOG`、`USE SCHEMA`	存取包含模型服務的目錄與結構。所有操作皆需此項。
`CREATE SERVICE`	在結構描述中建立模型服務。在目錄或架構中獲得。
`EXECUTE`	查詢模型服務。
`MANAGE`	修改或刪除模型服務並管理其授權。擁有者有一個 `MANAGE` 的超集。

模型服務使用 definer 權限。 Azure Databricks 會根據查詢權主的權限來評估查詢，而非呼叫者的權限。當使用者查詢模型服務時，Azure Databricks 會檢查擁有者是否對所參照的目標具有，例如基礎模型和任何 EXECUTE。來電者不需要直接存取這些目的地。

Limitations

以下功能不支援：

使用 SQL 建立和管理模型服務。
僅使用 BROWSE 權限探索模型服務。
全域搜尋模型服務。

其他資源

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-07