API を使用してモデルサービングエンドポイントで推論テーブルを有効にするEnable inference tables on modelsaービング endpoints using the API

プレビュー

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

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

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

要件

ワークスペースで Unity Catalog が有効になっている必要があります。
エンドポイントで推論テーブルを有効にするには、エンドポイントの作成者と修飾子の両方に次のアクセス許可が必要です。
- エンドポイントに対する CAN MANAGE 権限が必要です。
- USE CATALOG 指定したカタログに対するアクセス許可。
- USE SCHEMA 指定されたスキーマに対するアクセス許可。
- CREATE TABLE スキーマのアクセス許可。

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

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

API では、要求本文に以下を指定する auto_capture_config があります。

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

カタログ、スキーマ、およびオプションで表接頭辞を指定すると、表が <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"
}

推論テーブルへのログ記録が有効になったら、エンドポイントの準備が整うまで待ちます。その後、呼び出しを開始できます。

推論テーブルを作成したら、スキーマの進化とデータの追加をシステムで処理する必要があります。

次の操作は、テーブルの整合性には影響しません。

テーブルに対して最適化、分析、および 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 を使用してモデルサービング エンドポイントで推論テーブルを有効にするEnable inference tables on modelsaービング endpoints using the API

要件