使用 API 在模型服务终结点上启用推理表

项目
07/11/2024

重要

此功能目前以公共预览版提供。

本文介绍如何使用 Databricks API 为模型服务终结点启用推理表。有关如何使用推理表的常规信息（包括如何使用 Databricks UI 启用推理表），请参阅用于监视和调试模型的推理表。

可以在创建新终结点时或在现有终结点上启用推理表。 Databricks 建议使用服务主体创建终结点，以便在从工作区中移除创建终结点的用户时，推理表不会受到影响。

推理表的所有者是创建终结点的用户。表上的所有访问控制列表 (ACL) 都遵循标准 Unity Catalog 权限，并可由表所有者修改。

要求

工作区必须已启用 Unity Catalog。
终结点创建者和修改者都必须对终结点具有“可管理”权限。请参阅访问控制列表。
终结点创建者和修改者都必须在 Unity Catalog 中具有以下权限：
- 对指定目录的 USE CATALOG 权限。
- 对指定架构的 USE SCHEMA 权限。
- 架构中的 CREATE TABLE 权限。

使用 API 在创建终结点时启用推理表

可以使用 API 在终结点创建期间为终结点启用推理表。有关创建终结点的说明，请参阅创建自定义模型服务终结点。

在 API 中，请求正文具有 auto_capture_config，用于指定：

Unity Catalog 目录：表示表存储目录的字符串
Unity Catalog 架构：表示表存储架构的字符串
（可选）表前缀：用作推理表名称前缀的字符串。如果未指定此项，则使用终结点名称。
（可选）已启用：用于启用或禁用推理表的布尔值。默认值为 true。

指定目录、架构和可选表前缀后，将在 <catalog>.<schema>.<table_prefix>_payload 处创建表。此表会自动创建一个 Unity Catalog 托管表。表的所有者是创建终结点的用户。

注意

不支持指定现有表，因为推理表始终在终结点创建或终结点更新时自动创建。

警告

如果执行以下任一操作，推理表可能会损坏：

更改表架构。
更改表名称。
删除表。
失去对 Unity Catalog 目录或架构的权限。

在本例中，终结点状态 auto_capture_config 显示了有效负载表的 FAILED 状态。如果发生这种情况，则必须创建新的终结点才能继续使用推理表。

以下示例演示如何在终结点创建期间启用推理表。

POST /api/2.0/serving-endpoints

{
  "name": "feed-ads",
  "config":{
    "served_entities": [
      {
       "entity_name": "ads1",
       "entity_version": "1",
       "workload_size": "Small",
       "scale_to_zero_enabled": true
      }
    ],
    "auto_capture_config":{
       "catalog_name": "ml",
       "schema_name": "ads",
       "table_name_prefix": "feed-ads-prod"
    }
  }
}

响应如下所示：

{
  "name": "feed-ads",
  "creator": "customer@example.com",
  "creation_timestamp": 1666829055000,
  "last_updated_timestamp": 1666829055000,
  "state": {
    "ready": "NOT_READY",
    "config_update": "IN_PROGRESS"
  },
  "pending_config": {
    "start_time": 1666718879000,
    "served_entities": [
      {
        "name": "ads1-1",
        "entity_name": "ads1",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": true,
        "state": {
          "deployment": "DEPLOYMENT_CREATING",
          "deployment_state_message": "Creating"
        },
        "creator": "customer@example.com",
        "creation_timestamp": 1666829055000
    }
   ],
   "config_version": 1,
   "traffic_config": {
     "routes": [
       {
         "served_model_name": "ads1-1",
         "traffic_percentage": 100
       }
      ]
   },
   "auto_capture_config": {
     "catalog_name": "ml",
     "schema_name": "ads",
     "table_name_prefix": "feed-ads-prod",
     "state": {
       "payload_table": {
         "name": "feed-ads-prod_payload"
       }
     },
     "enabled": true
   }
  },
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permission_level": "CAN_MANAGE"
}

启用记录到推理表后，请等待终结点准备就绪。然后，你便可以开始调用它。

创建推理表后，架构演变和数据添加应由系统来处理。

以下操作不会影响表的完整性：

针对表运行 OPTIMIZE、ANALYZE 和 VACUUM。
删除未使用的旧数据。

如果未指定 auto_capture_config，则默认使用前一配置版本的设置配置。例如，如果推理表已经启用，则在下一次终结点更新时使用相同的设置；如果推理表处于禁用状态，则它将继续被禁用。

{
  "served_entities": [
    {
      "name":"current",
      "entity_name":"model-A",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    }
  ],
  "auto_capture_config": {
    "enabled": false
  }
}

使用 API 在现有终结点上启用推理表

也可以使用 API 在现有终结点上启用推理表。启用推理表后，在将来的更新终结点 API 调用中继续指定相同的 auto_capture_config 正文，以继续使用推理表。

注意

不支持在启用推理表后更改表位置。

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

{
  "served_entities": [
    {
      "name":"current",
      "entity_name":"model-A",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    },
    {
      "name":"challenger",
      "entity_name":"model-B",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    }
  ],
  "traffic_config":{
    "routes": [
      {
        "served_model_name":"current",
        "traffic_percentage":"50"
      },
      {
        "served_model_name":"challenger",
        "traffic_percentage":"50"
      }
    ]
  },
  "auto_capture_config":{
   "catalog_name": "catalog",
   "schema_name": "schema",
   "table_name_prefix": "my-endpoint"
  }
}

禁用推理表

禁用推理表时，无需指定目录、架构或表前缀。唯一的必填字段是 enabled: false。

POST /api/2.0/serving-endpoints

{
  "name": "feed-ads",
  "config":{
    "served_entities": [
      {
       "entity_name": "ads1",
       "entity_version": "1",
       "workload_size": "Small",
       "scale_to_zero_enabled": true
      }
    ],
    "auto_capture_config":{
       "enabled": false
    }
  }
}

若要重新启用已禁用的推理表，请按照在现有终结点上启用推理表中的说明操作。可以使用同一个表或指定一个新表。

后续步骤

启用推理表后，可以使用 Databricks 湖屋监视来监视此模型服务终结点中提供的模型。有关详细信息，请参阅工作流：使用推理表监视模型性能。

通过

使用 API 在模型服务终结点上启用推理表

要求

使用 API 在创建终结点时启用推理表

使用 API 在现有终结点上启用推理表

禁用推理表

后续步骤

反馈

其他资源