创建自定义模型服务端点

本文介绍如何使用 Databricks 模型服务来创建为自定义模型提供服务的模型服务终结点。

该模型服务提供了下列用于为终结点创建提供服务的选项：

服务界面
REST API
MLflow 部署 SDK

要求

工作区必须位于受支持的区域。
如果将自定义库或来自专用镜像服务器的库与模型配合使用，请在创建模型终结点之前，参阅将自定义 Python 库与模型服务配合使用。
若要使用 MLflow 部署 SDK 创建这些终结点，必须安装 MLflow 部署客户端。要安装它，请运行：

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")

身份和访问

若要创建或更新提供终结点的模型，调用方和终结点的记录创建者都必须：

成为工作区的成员。
拥有 workspace-access 许可。

创作者身份

创建终结点时，Databricks 会将调用标识记录为终结点的 创建者。此标识（通常是服务主体）用于代表终结点访问 Unity 目录资源，创建后无法更改。

如果记录中的创建者缺少所需的 Unity Catalog 授权，或已从工作区中移除，则必须删除该终结点，并使用具有所需权限且当前属于该工作区成员的服务主体重新创建它。

配置和服务实体更新会重新评估记录在案的创建者的工作区成员身份和权限。如果记录的创建者不再是工作区成员，即使调用方具有有效权限，更新也会因 PERMISSION_DENIED 而失败。

服务实体授权

已记录的创建者必须在每个所服务的实体上拥有以下授权。在创建或更新终结点时会验证授权；如果缺少，请求将失败，并出现 PERMISSION_DENIED。查询执行时所需的权限不会预先校验——当端点开始处理流量时，缺失的权限会导致运行时错误。

资源类型	需要授权	验证后
Unity 目录模型	`USE CATALOG` 在目录上、`USE SCHEMA` 在架构上、`EXECUTE` 在模型上	终结点创建或更新

注释

如果 Unity Catalog 模型声明了传递性函数依赖关系，则已记录的创建者还需要具有对这些上游函数的 EXECUTE。

管理端点访问

若要了解模型服务终结点的访问控制选项，请参阅管理模型服务终结点的权限。

创建终结点

服务 UI

可以使用服务 UI 为模型服务创建终结点。

单击边栏中的“服务”以显示服务 UI。
单击“创建服务终结点”。

对于 Unity 目录（建议）或旧工作区模型注册表中的模型：

在“名称”字段中，提供终结点的名称。
- 终结点名称不能使用 databricks- 前缀。此前缀是为 Databricks 预配置终结点保留的。
在“服务的实体”部分中
1. 单击“实体”字段以打开“选择服务的实体”窗体。
2. 根据模型注册位置选择 “我的模型-Unity 目录 ”或 “我的模型-模型注册表 ”。窗体会根据您的选择动态更新。
  - 并非所有模型都是自定义模型。模型可以是基础模型或用于特征服务的功能。
3. 选择要服务的模型和模型版本。
4. 选择要路由到服务的模型的流量百分比。
5. 选择要使用的计算大小。可以将 CPU 或 GPU 计算资源用于任务。请参阅计算类型，了解可用的工作负载类型，其中包括适用于所需内存高于标准CPU_MEDIUM类型的模型的CPU_LARGE和CPU选项。有关 GPU 代码示例，请参阅 GPU 工作负荷类型。
6. 在 “计算横向扩展”下，选择与此服务模型可以同时处理的请求数相对应的计算横向扩展的大小。此数字应大致等于 QPS x 模型运行时。有关客户定义的计算设置，请参阅模型服务限制。
  1. 可用大小包括：小（适用于 0-4 个请求）、中（适用于 8-16 个请求）、大（适用于 16-64 个请求）。
7. 指明终结点是否应在不使用时缩放为零。不建议将生产端点缩放到零，因为一旦缩放到零，容量无法得到保证。当终结点缩放到零时，当终结点纵向扩展以处理请求时，还会有额外的延迟（也称为冷启动）。
8. 在 “高级配置”下，可以：
  - 重命名服务实体以自定义它在终结点中的显示方式。
  - 添加环境变量以从终结点连接到资源，或将你的功能查找 DataFrame 记录到终结点的推理表。要记录特征查找数据帧，需要 MLflow 2.14.0 或更高版本。
9. （可选）若要将其他服务实体添加到终结点，请单击“ 添加服务实体 ”并重复上述配置步骤。可以从单个终结点为多个模型或模型版本提供服务，并控制它们之间的流量拆分。有关详细信息，请参阅提供多个模型。
在 “路由优化 ”部分中，可以为终结点启用路由优化。建议对满足高 QPS 和吞吐量要求的终结点进行路由优化。请参阅在服务端点上进行路由优化。
在 “AI 网关 ”部分中，可以选择在终结点上启用哪些治理功能。请参阅使用 Unity AI 网关进行 AI 治理。
单击 “创建” 。此时将显示“服务终结点”页，其中“服务终结点状态”显示为“未就绪”。

REST API

可以使用 REST API 创建终结点。有关终结点配置参数，请参阅 POST /api/2.0/serving-endpoints。

以下示例创建一个终结点，该终结点为 Unity Catalog 模型注册表中注册的 my-ads-model 模型的第三个版本提供服务。若要从 Unity 目录指定模型，请提供完整的模型名称，包括父目录和架构， catalog.schema.example-model例如。此示例使用自定义的并发，min_provisioned_concurrency 和 max_provisioned_concurrency。并发值必须是 4 的倍数。


POST /api/2.0/serving-endpoints

{
  "name": "uc-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false
      }
    ]
  }
}

以下是示例响应。终结点 config_update 的状态是 NOT_UPDATING 且服务模型处于 READY 状态。

{
  "name": "uc-model-endpoint",
  "creator": "[email protected]",
  "creation_timestamp": 1700089637000,
  "last_updated_timestamp": 1700089760000,
  "state": {
    "ready": "READY",
    "config_update": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false,
        "workload_type": "CPU",
        "state": {
          "deployment": "DEPLOYMENT_READY",
          "deployment_state_message": ""
        },
        "creator": "[email protected]",
        "creation_timestamp": 1700089760000
      }
    ],
    "config_version": 1
  },
  "tags": [
    {
      "key": "team",
      "value": "data science"
    }
  ],
  "id": "e3bd3e471d6045d6b75f384279e4b6ab",
  "permission_level": "CAN_MANAGE",
  "route_optimized": false
}

MLflow 部署 SDK

MLflow 部署提供用于创建、更新和删除任务的 API。这些任务的 API 接受的参数与用于提供终结点的 REST API 相同。有关终结点配置参数，请参阅 POST /api/2.0/serving-endpoints。

以下示例创建一个终结点，该终结点为 Unity Catalog 模型注册表中注册的 my-ads-model 模型的第三个版本提供服务。必须提供完整的模型名称，包括父目录和架构，例如catalog.schema.example-model。此示例使用自定义的并发，min_provisioned_concurrency 和 max_provisioned_concurrency。并发值必须是 4 的倍数。

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity",
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "min_provisioned_concurrency": 4,
                "max_provisioned_concurrency": 12,
                "scale_to_zero_enabled": False
            }
        ]
    }
)

工作区客户端

以下示例演示如何使用 Databricks 工作区客户端 SDK 创建终结点。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

w = WorkspaceClient()

w.serving_endpoints.create(
    name="uc-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                name="ads-entity",
                entity_name="catalog.schema.my-ads-model",
                entity_version="3",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

也可执行以下操作：

启用推理表，以自动捕获传入请求和向模型提供终结点的传出响应。
如果在终结点上启用了推理表，可以将特征查找数据帧记录到推理表。

还可以添加环境变量来存储模型服务的凭据。请参阅配置从模型服务终结点对资源的访问权限

GPU 工作负载类型

GPU 部署与以下包版本兼容：

PyTorch 1.13.0 - 2.0.1
TensorFlow 2.5.0 - 2.13.0
MLflow 2.4.0 及更高版本

以下示例演示如何使用不同的方法创建 GPU 终结点。

服务 UI

若要使用服务 UI 为 GPU 工作负载配置终结点，请在创建终结点时从 “计算类型” 下拉列表中选择所需的 GPU 类型。按照“ 创建终结点”中的相同步骤作，但选择 GPU 工作负荷类型而不是 CPU。

REST API

若要使用图形处理单元(GPU)部署模型，请在终结点配置中包含workload_type字段。

POST /api/2.0/serving-endpoints

{
  "name": "gpu-model-endpoint",
  "config": {
    "served_entities": [{
      "entity_name": "catalog.schema.my-gpu-model",
      "entity_version": "1",
      "workload_type": "GPU_SMALL",
      "workload_size": "Small",
      "scale_to_zero_enabled": false
    }]
  }
}

MLflow 部署 SDK

以下示例演示如何使用 MLflow 部署 SDK 创建 GPU 终结点。

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="gpu-model-endpoint",
    config={
        "served_entities": [{
            "entity_name": "catalog.schema.my-gpu-model",
            "entity_version": "1",
            "workload_type": "GPU_SMALL",
            "workload_size": "Small",
            "scale_to_zero_enabled": False
        }]
    }
)

工作区客户端

以下示例演示如何使用 Databricks 工作区客户端 SDK 创建 GPU 终结点。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

w = WorkspaceClient()

w.serving_endpoints.create(
    name="gpu-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name="catalog.schema.my-gpu-model",
                entity_version="1",
                workload_type="GPU_SMALL",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

可用的 GPU 工作负荷类型取决于云提供商，如下表所述。

GPU 工作负载类型	GPU 实例	GPU 内存
`GPU_SMALL`	1xT4	16GB
`GPU_LARGE`	1xA100	80GB
`GPU_LARGE_2`	2xA100	160GB
`GPU_LARGE_4`	4xA100	320GB

对于 GPU 终结点，并发值确定分配给模型的副本数。副本数等于并发值除以 4。例如，将 min_provisioned_concurrency 设置为 12 会预配 3 个副本。

修改自定义模型终结点

启用自定义模型终结点后，可以根据需要更新计算配置。如果需要模型的其他资源，此配置将尤其有用。在为模型服务分配哪些资源方面，工作负载大小和计算配置起着关键作用。

注释

配置更新和服务实体更新会重新验证终结点记录的创建者的工作区成员身份以及针对各服务实体的授权。提交更新前，请确认两者仍然有效；请参阅身份和访问。

为了避免更新失败：

使用由团队拥有的长期有效的服务主体作为终结点创建者。
不要使用日后可能会被停用或从工作区中移除的个人用户账户。
已记录的创建者在端点的整个生命周期内必须始终是工作区成员。

注释

终结点配置的更新可能会失败。发生故障时，现有活动配置会保持有效状态，就像更新未发生一样。

通过查看终结点的状态来验证更新是否已成功应用。

在新配置准备就绪之前，旧配置会一直为预测流量提供服务。正在进行更新时，无法进行其他更新。但是，可以从服务 UI 取消正在进行的更新。

服务 UI

启用模型终结点后，选择 “编辑终结点 ”以修改终结点的计算配置。

“编辑终结点”按钮

可以更改终结点配置的大部分方面，但终结点名称和某些不可变属性除外。

可以通过在终结点的详细信息页上选择 “取消更新 ”来取消正在进行的配置更新。

REST API

下面是使用 REST API 的终结点配置更新示例。请参阅 PUT /api/2.0/service-endpoints/{name}/config。


PUT /api/2.0/serving-endpoints/{name}/config

{
  "name": "unity-catalog-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "5",
        "workload_size": "Small",
        "scale_to_zero_enabled": true
      }
    ],
    "traffic_config":
    {
      "routes": [
        {
          "served_model_name": "my-ads-model-5",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

MLflow 部署 SDK

MLflow 部署 SDK 使用与 REST API 相同的参数，请参阅 PUT /api/2.0/service-endpoints/{name}/config 以获取请求和响应架构详细信息。

以下代码示例使用 Unity 目录模型注册表中的模型：

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.update_endpoint_config(
  endpoint=f"{endpointname}",
  config={
    "served_entities": [
        {
            "entity_name": f"{catalog}.{schema}.{model_name}",
            "entity_version": "1",
            "workload_size": "Small",
            "scale_to_zero_enabled": True
        }
    ],
    "traffic_config": {
        "routes": [
            {
                "served_model_name": f"{model_name}-1",
                "traffic_percentage": 100
            }
        ]
    }
  }
)

为模型终结点评分

若要为模型评分，可以将请求发送到模型服务终结点。

参见自定义模型的查询服务端点。
请参阅使用基础模型。

其他资源

管理模型服务端点。
模型服务中的外部模型。
如果您更倾向于使用 Python，可以使用 Databricks 实时服务 Python SDK。

笔记本示例

以下笔记本包含可用于启动和运行模型服务终结点的不同 Databricks 注册模型。有关其他示例，请参阅教程：部署和查询自定义模型。

可以按照导入笔记本中的说明将模型示例导入工作区。从其中一个示例中选择并创建模型后，将其注册到 Unity 目录中，然后按照模型服务的 UI 工作流步骤进行作。

为模型服务笔记本训练和注册 scikit-learn 模型

获取笔记本

为模型服务笔记本训练和注册 HuggingFace 模型

获取笔记本

反馈

此页面是否有帮助？

Last updated on 2026-07-01