共用方式為

使用 API 在提供端點的模型上啟用推斷數據表

  • 發行項

重要

這項功能處於公開預覽狀態。

本文說明如何使用 Databricks API 來啟用模型服務端點的推斷數據表。 如需使用推斷數據表的一般資訊，包括如何使用 Databricks UI 加以啟用，請參閱 用於監視和偵錯模型的推斷數據表。

您可以在建立新的端點或現有端點時啟用推斷數據表。 Databricks 建議您使用服務主體建立端點，以便在建立端點的使用者從工作區移除時，不會影響推斷數據表。

推斷資料表的擁有者是建立端點的使用者。 資料表的所有存取控制清單 (ACL) 都遵循標準 Unity Catalog 權限，並且可由資料表擁有者修改。

需求

  • 工作區必須啟用 Unity Catalog。
  • 端點和修飾元的建立者都必須擁有端點的 Can Manage 權限。 請參閱存取控制清單。
  • 端點和修飾元的建立者都必須在 Unity Catalog 擁有下列權限：
    • 指定目錄的 USE CATALOG 權限。
    • 指定結構描述的 USE SCHEMA 權限。
    • 結構描述的 CREATE TABLE 權限。

使用 API 在端點建立時啟用推斷數據表

您可以在使用 API 建立端點期間啟用端點的推斷資料表。 如需建立端點的指示，請參閱 建立提供端點的自定義模型。

在 API 中，要求主體必須 auto_capture_config 指定：

  • Unity 目錄目錄：字串，代表要儲存數據表的目錄
  • Unity 目錄架構：字串，表示要儲存數據表的架構
  • （選擇性） 數據表前置詞：做為推斷數據表名稱前置詞的字串。 如果未指定此專案，則會使用端點名稱。
  • 已啟用 （選擇性） ：用來啟用或停用推斷數據表的布爾值。 根據預設，這是 true。

指定目錄、架構和選擇性數據表前置詞之後，會在 建立 <catalog>.<schema>.<table_prefix>_payload數據表。 此數據表會自動建立 Unity 目錄受控數據表。 數據表的擁有者是建立端點的使用者。

注意

不支援指定現有的數據表，因為推斷數據表一律會在端點建立或端點更新時自動建立。

警告

如果您執行下列任何動作，推斷資料表可能會損毀：

  • 變更資料表結構描述。
  • 變更資料表的名稱。
  • 刪除資料表。
  • 喪失 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 Lakehouse Monitoring 來監視模型服務端點中的服務模型。 如需詳細資訊，請參閱 工作流程：使用推斷數據表監視模型效能。