メインコンテンツまでスキップ

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

備考

プレビュー

この機能は パブリック プレビュー段階です。

important

この記事では、 カスタム モデルの推論テーブルに適用されるトピックについて説明します。 外部モデルまたはプロビジョニングされたスループット ワークロードの場合は、 AI Gateway 対応の推論テーブルを使用します。

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

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

注記

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

警告

次のいずれかをすると、推論テーブルが壊れる可能性があります。

  • テーブル スキーマを変更します。
  • テーブル名を変更します。
  • テーブルを削除します。
  • Unity Catalogカタログまたはスキーマに対する権限を失います。

この場合、エンドポイントステータスの auto_capture_config は、ペイロードテーブルの FAILED 状態を示します。 これが発生した場合、推論テーブルを引き続き使用するには、新しいエンドポイントを作成する必要があります。

次の例は、エンドポイントの作成時に推論テーブルを有効にする方法を示しています。

Bash
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"
    }
  }
}

応答は次のようになります。

JSON
{
  "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を指定しない場合、デフォルトでは、以前の設定バージョンの設定設定が再利用されます。たとえば、推論テーブルがすでに有効になっている場合は、次回のエンドポイント更新で同じ設定が使用され、推論テーブルが無効になっている場合は引き続き無効になります。

JSON
{
  "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 本文を引き続き指定します。

注記

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

Bash
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です。

Bash
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 レイクハウスモニタリングを使用して、モデルサービングエンドポイントで提供されたモデルをモニタリングできます。 詳細については、「 ワークフロー: 推論テーブルを使用したモデルのパフォーマンスのモニタリング」を参照してください。

に最終更新