API を使用してモデル提供エンドポイントで推論テーブルを有効にする

[アーティクル]
07/11/2024

重要

この記事では、Databricks API を使用して、モデル提供エンドポイントで推論テーブルを有効にする方法について説明します。 Databricks UI を使用して推論テーブルを有効にする方法など、推論テーブルの使用に関する一般的な情報については、「モデルの監視とデバッグのための推論テーブル」を参照してください。

新しいエンドポイントを作成するとき、または既存のエンドポイントで推論テーブルを有効にすることができます。 Databricks では、エンドポイントを作成したユーザーがワークスペースから削除された場合に推論テーブルが影響を受けないように、サービスプリンシパルを使用してエンドポイントを作成することをお勧めします。

推論テーブルの所有者は、エンドポイントを作成したユーザーです。テーブルのすべてのアクセス制御リスト (ACL) は、標準の Unity カタログのアクセス許可に従い、テーブル所有者が変更できます。

要件

ワークスペースで Unity カタログが有効になっている必要があります。
エンドポイントの作成者と修飾子の両方に、エンドポイントに対する管理可能アクセス許可が必要です。「アクセス制御リスト」を参照してください。
エンドポイントの作成者と修飾子の両方に、Unity Catalog における次のアクセス許可が必要です:
- 指定したカタログに対する USE CATALOG アクセス許可。
- 指定したスキーマに対する USE SCHEMA アクセス許可。
- スキーマ内の CREATE TABLE アクセス許可。

API を使用してエンドポイントの作成時に推論テーブルを有効にする

API を使用して、エンドポイントの作成時にエンドポイントの推論テーブルを有効にすることができます。エンドポイントを作成する手順については、「カスタムモデル提供エンドポイントを作成する」を参照してください。

API の要求本文には次を指定する auto_capture_config があります。

Unity カタログカタログ: テーブルを格納するカタログを表す文字列
Unity カタログスキーマ: テーブルを格納するスキーマを表す文字列
(省略可能) テーブルプレフィックス: 推論テーブル名のプレフィックスとして使用される文字列。これを指定しないと、エンドポイント名が使用されます。
(省略可能) 有効: 推論テーブルを有効または無効にするために使用されるブール値。これは既定では true です。

カタログ、スキーマ、および必要に応じてテーブルプレフィックスを指定すると、<catalog>.<schema>.<table_prefix>_payload にテーブルが作成されます。このテーブルは、Unity カタログのマネージドテーブルを自動的に作成します。テーブルの所有者は、エンドポイントを作成するユーザーです。

Note

推論テーブルは常にエンドポイントの作成時や更新時に自動的に作成されるため、既存のテーブルの指定はサポートされていません。

警告

次のいずれかの操作を行うと、推論テーブルが破損する可能性があります。

テーブルスキーマを変更する。
テーブル名を変更する。
テーブルを削除する。
Unity カタログカタログやスキーマへのアクセス許可が失われます。

この場合、エンドポイントステータスの 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 本文を指定し、推論テーブルを使用じ続けます。

Note

推論テーブルを有効にした後のテーブルの場所の変更はサポートされていません。

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 で監視することができます。詳細については、「ワークフロー: 推論テーブルを使用してモデルのパフォーマンスを監視する」を参照してください。

次の方法で共有

API を使用してモデル提供エンドポイントで推論テーブルを有効にする

要件

API を使用してエンドポイントの作成時に推論テーブルを有効にする

API を使用して既存のエンドポイントで推論テーブルを有効にする

推論テーブルを無効にする

次のステップ

フィードバック

その他のリソース