Aktivieren von Rückschlusstabellen für Modellbereitstellungsendpunkte mithilfe der API

Artikel
12/18/2024

Wichtig

Dieses Feature befindet sich in der Public Preview.

In diesem Artikel wird erläutert, wie Sie die Databricks-API verwenden, um Rückschlusstabellen für einen Modellbereitstellungsendpunkt zu aktivieren. Allgemeine Informationen zur Verwendung von Rückschlusstabellen, u. a. zur Aktivierung der Databricks-Benutzeroberfläche, finden Sie unter Rückschlusstabellen zum Überwachen und Debuggen von Modellen.

Sie können Rückschlusstabellen beim Erstellen eines neuen Endpunkts oder für einen vorhandenen Endpunkt aktivieren. Databricks empfiehlt das Erstellen des Endpunkts mithilfe eines Dienstprinzipals, sodass die Rückschlusstabelle nicht betroffen ist, wenn der Benutzer oder die Benutzerin, der bzw. die den Endpunkt erstellt hat, aus dem Arbeitsbereich entfernt wird.

Der Besitzer der Rückschlusstabellen ist der Benutzer, der den Endpunkt erstellt hat. Alle Zugriffssteuerungslisten (Access Control Lists, ACLs) in der Tabelle folgen den Standardberechtigungen des Unity-Catalogs und können vom Tabellenbesitzer geändert werden.

Anforderungen

Ihr Arbeitsbereich muss für Unity Catalog aktiviert sein.
Sowohl der Ersteller des Endpunkts als auch der Modifizierer müssen über die Berechtigung Kann verwalten für den Endpunkt verfügen. Siehe Zugriffssteuerungslisten.
Sowohl der Ersteller des Endpunkts als auch der Modifizierer müssen über die folgenden Berechtigungen im Unity-Katalog verfügen:
- USE CATALOG-Berechtigungen für den angegebenen Katalog.
- USE SCHEMA-Berechtigungen für das angegebene Schema.
- CREATE TABLE-Berechtigungen im Schema.

Aktivieren von Rückschlusstabellen bei der Endpunkterstellung mithilfe der API

Sie können Rückschlusstabellen für einen Endpunkt mithilfe der API während seiner Erstellung aktivieren. Anweisungen zum Erstellen eines Endpunkts finden Sie unter Erstellen von benutzerdefinierten Model Serving-Endpunkten.

In der API verfügt der Anforderungstext über eine auto_capture_config, in der Folgendes angegeben werden kann:

Der Unity Catalog: Eine Zeichenfolge, die den Katalog darstellt, in dem die Tabelle gespeichert werden soll.
Das Unity Catalog-Schema: Eine Zeichenfolge, die das Schema darstellt, in dem die Tabelle gespeichert werden soll.
Ein Tabellenpräfix (optional): Eine Zeichenfolge, die als Präfix für den Namen der Rückschlusstabelle verwendet wird. Wenn kein Präfix angegeben, wird der Endpunktname verwendet.
aktiviert (optional): Ein boolescher Wert, der zum Aktivieren oder Deaktivieren von Rückschlusstabellen verwendet wird. Der Standardwert lautet „wahr“.

Nachdem Sie einen Katalog, ein Schema und optional ein Tabellenpräfix angegeben haben, wird unter <catalog>.<schema>.<table_prefix>_payload eine Tabelle erstellt. Diese Tabelle erstellt automatisch eine verwaltete Unity Catalog-Tabelle. Der Besitzer oder die Besitzerin der Rückschlusstabellen ist der Benutzer oder die Benutzerin, der bzw. die den Endpunkt erstellt hat.

Hinweis

Das Angeben einer vorhandenen Tabelle wird nicht unterstützt, da die Rückschlusstabelle immer automatisch bei der Endpunkterstellung oder -aktualisierung erstellt wird.

Warnung

Die Rückschlusstabelle kann beschädigt werden, wenn Sie eine der folgenden Aktionen ausführen:

Ändern des Tabellenschemas.
Ändern des Tabellennamens.
Löschen der Tabelle.
die Berechtigungen für den Unity Catalog oder das Unity Catalog-Schema verlieren.

In diesem Fall zeigt die auto_capture_config des Endpunktstatus für die Nutzlasttabelle einen FAILED-Status an. Wenn dies geschieht, müssen Sie zur weiteren Verwendung von Rückschlusstabellen einen neuen Endpunkt erstellen.

Das folgende Beispiel veranschaulicht, wie Sie Rückschlusstabellen während der Endpunkterstellung aktivieren.

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

Die Antwort sieht wie folgt aus:

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

Nachdem die Protokollierung für Rückschlusstabellen aktiviert wurde, warten Sie, bis Ihr Endpunkt bereit ist. Anschließend können Sie einen Aufruf durchführen.

Nachdem Sie eine Rückschlusstabelle erstellt haben, sollten die Schemaentwicklung und das Hinzufügen von Daten vom System übernommen werden.

Die folgenden Vorgänge wirken sich nicht auf die Integrität der Tabelle aus:

Ausführen von OPTIMIZE, ANALYZE und VACUUM auf die Tabelle.
Löschen alter und nicht genutzter Daten.

Wenn Sie keine auto_capture_config angeben, wird standardmäßig erneut die Einstellungskonfiguration aus der vorherigen Konfigurationsversion verwendet. Wenn Rückschlusstabellen beispielsweise bereits aktiviert wurden, werden dieselben Einstellungen für die nächste Endpunktaktualisierung verwendet. Wurden die Rückschlusstabellen hingegen deaktiviert, bleiben sie das auch.

{
  "served_entities": [
    {
      "name":"current",
      "entity_name":"model-A",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    }
  ],
  "auto_capture_config": {
    "enabled": false
  }
}

Aktivieren von Rückschlusstabellen auf einem vorhandenen Endpunkt mithilfe der API

Sie können Rückschlusstabellen auch mithilfe der API für einen vorhandenen Endpunkt aktivieren. Nachdem Rückschlusstabellen aktiviert wurden, geben Sie in zukünftigen API-Aufrufen zur Endpunktaktualisierung weiterhin denselben auto_capture_config-Text an, um die Verwendung von Rückschlusstabellen fortzusetzen.

Hinweis

Das Ändern der Tabellenposition nach dem Aktivieren von Rückschlusstabellen wird nicht unterstützt.

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

Deaktivieren von Rückschlusstabellen

Beim Deaktivieren von Rückschlusstabellen müssen Sie kein Katalog-, Schema- oder Tabellenpräfix angeben. Das einzige Pflichtfeld ist 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
    }
  }
}

Um eine deaktivierte Rückschlusstabelle erneut zu aktivieren, folgen Sie den Anweisungen unter Aktivieren von Rückschlusstabellen auf einem vorhandenen Endpunkt. Sie können entweder dieselbe Tabelle verwenden oder eine neue Tabelle angeben.

Nächste Schritte

Nachdem Sie Rückschlusstabellen aktiviert haben, können Sie die bereitgestellten Modelle in Ihrem Modellbereitstellungsendpunkt mit Databricks Lakehouse Monitoring überwachen. Ausführliche Informationen finden Sie unter Workflow: Überwachen der Modellleistung mithilfe von Rückschlusstabellen.

Freigeben über