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

2025-05-10

重要

この記事では、特定のプロビジョニング済みスループットとカスタムモデルエンドポイントにのみ関連するレガシ推論テーブルエクスペリエンスについて説明します。このエクスペリエンスは推奨されません。 Databricks では、カスタムモデル、基盤モデル、およびエンドポイントにサービスを提供するエージェントで可用性を確保するために、 AI ゲートウェイ対応の推論テーブルが推奨されます。

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

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

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

要件

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

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

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

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

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

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

注

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

警告

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

テーブルスキーマを変更します。
テーブル名を変更します。
テーブルを削除します。
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 本文を指定し続けて、推論テーブルの使用を続行します。

注

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

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 を使用して既存のエンドポイントで推論テーブルを有効にする

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

次のステップ

フィードバック

その他のリソース

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