MLflow Model Registry-webhooks in Azure Databricks

  • Artikel

Belangrijk

Deze functie is beschikbaar als openbare preview.

Met Webhooks kunt u luisteren naar modelregister-gebeurtenissen, zodat uw integraties automatisch acties kunnen activeren. U kunt webhooks gebruiken om uw machine learning-pijplijn te automatiseren en te integreren met bestaande CI/CD-hulpprogramma's en werkstromen. U kunt bijvoorbeeld CI-builds activeren wanneer er een nieuwe modelversie wordt gemaakt of uw teamleden op de hoogte stellen via Slack telkens wanneer een modelovergang naar productie wordt aangevraagd.

Webhooks zijn beschikbaar via de Databricks REST API of de Python-client databricks-registry-webhooks op PyPI.

Notitie

Webhooks zijn niet beschikbaar wanneer u Modellen in Unity Catalog gebruikt. Zie Voor een alternatief kan ik faseovergangsaanvragen gebruiken of webhooks activeren op gebeurtenissen?. Het verzenden van webhooks naar privé-eindpunten (eindpunten die niet toegankelijk zijn vanaf het openbare internet) wordt niet ondersteund.

Webhook-gebeurtenissen

U kunt een webhook opgeven die moet worden geactiveerd op een of meer van deze gebeurtenissen:

  • MODEL_VERSION_CREATED: er is een nieuwe modelversie gemaakt voor het bijbehorende model.
  • MODEL_VERSION_TRANSITIONED_STAGE: de fase van een modelversie is gewijzigd.
  • TRANSITION_REQUEST_CREATED: Een gebruiker heeft gevraagd om de fase van een modelversie over te schakelen.
  • COMMENT_CREATED: Een gebruiker heeft een opmerking over een geregistreerd model geschreven.
  • REGISTERED_MODEL_CREATED: Er is een nieuw geregistreerd model gemaakt. Dit gebeurtenistype kan alleen worden opgegeven voor een webhook voor het hele register, dat kan worden gemaakt door geen modelnaam op te geven in de aanvraag voor maken.
  • MODEL_VERSION_TAG_SET: Een gebruiker stelt een tag in voor de modelversie.
  • MODEL_VERSION_TRANSITIONED_TO_STAGING: er is een modelversie overgezet naar fasering.
  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Er is een modelversie overgezet naar productie.
  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Er is een modelversie gearchiveerd.
  • TRANSITION_REQUEST_TO_STAGING_CREATED: Een gebruiker heeft gevraagd om een modelversie over te schakelen naar fasering.
  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Een gebruiker heeft gevraagd om een modelversie over te schakelen naar productie.
  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Een gebruiker heeft gevraagd om een modelversie te archiveren.

Typen webhooks

Er zijn twee soorten webhooks op basis van hun triggerdoelen:

  • Webhooks met HTTP-eindpunten (HTTP-registerwebhooks): triggers verzenden naar een HTTP-eindpunt.
  • Webhooks met taaktriggers (taakregisterwebhooks): een taak activeren in een Azure Databricks-werkruimte. Als IP-acceptatielijst is ingeschakeld in de werkruimte van de taak, moet u de ip-adressen van de werkruimte van het modelregister toestaan. Zie ip-acceptatielijst voor webhooks voor taakregisters voor meer informatie.

Er zijn ook twee soorten webhooks op basis van hun bereik, met verschillende vereisten voor toegangsbeheer:

  • Modelspecifieke webhooks: De webhook is van toepassing op een specifiek geregistreerd model. U moet over CAN MANAGE-machtigingen voor het geregistreerde model beschikken om webhooks te maken, te wijzigen, te verwijderen of te testen.
  • Registerbrede webhooks: de webhook wordt geactiveerd door gebeurtenissen op elk geregistreerd model in de werkruimte, inclusief het maken van een nieuw geregistreerd model. Als u een webhook voor het hele register wilt maken, laat u het veld weg bij het model_name maken. U moet beschikken over beheerdersmachtigingen voor werkruimten om webhooks voor het hele register te maken, te wijzigen, te verwijderen of te testen.

Nettolading van webhook

Elke gebeurtenistrigger bevat minimale velden in de nettolading voor de uitgaande aanvraag naar het eindpunt van de webhook.

  • Gevoelige informatie, zoals de locatie van het artefactpad, wordt uitgesloten. Gebruikers en principals met de juiste ACL's kunnen client- of REST API's gebruiken om een query uit te voeren op het modelregister voor deze informatie.
  • Nettoladingen worden niet versleuteld. Zie Beveiliging voor informatie over hoe u kunt valideren dat Azure Databricks de bron van de webhook is.
  • Het text veld vereenvoudigt slack-integratie. Als u een Slack-bericht wilt verzenden, geeft u een Slack-webhookeindpunt op als de URL van de webhook.

Nettolading taakregisterwebhook

De nettolading voor een webhook voor het taakregister is afhankelijk van het type taak en wordt verzonden naar het jobs/run-now eindpunt in de doelwerkruimte.

Taken met één taak

Taken met één taak hebben een van de drie nettoladingen op basis van het taaktype.

Notebook- en Python-wieltaken

Notebook- en Python-wieltaken hebben een JSON-nettolading met een parameterwoordenlijst die een veld event_messagebevat.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}
Python-, JAR- en Spark Submit-taken

Python-, JAR- en Spark-taken hebben een JSON-nettolading met een parameterlijst.

{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Alle andere taken

Alle andere typen taken hebben een JSON-nettolading zonder parameters.

{
  "job_id": 1234567890
}

Taken met meerdere taken

Taken met meerdere taken hebben een JSON-nettolading met alle parameters die zijn ingevuld om rekening te houden met verschillende taaktypen.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  },
  "python_named_params": {
    "event_message": "<Webhook Payload>"
  },
  "jar_params": ["<Webhook Payload>"],
  "python_params": ["<Webhook Payload>"],
  "spark_submit_params": ["<Webhook Payload>"]
}

Voorbeeld van nettoladingen

Gebeurtenis: MODEL_VERSION_TRANSITIONED_STAGE

Respons

POST
/your/endpoint/for/event/model-versions/stage-transition
--data {
  "event": "MODEL_VERSION_TRANSITIONED_STAGE",
  "webhook_id": "c5596721253c4b429368cf6f4341b88a",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "to_stage": "Production",
  "from_stage": "None",
  "text": "Registered model 'someModel' version 8 transitioned from None to Production."
}

Gebeurtenis: MODEL_VERSION_TAG_SET

Respons

POST
/your/endpoint/for/event/model-versions/tag-set
--data {
  "event": "MODEL_VERSION_TAG_SET",
  "webhook_id": "8d7fc634e624474f9bbfde960fdf354c",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "tags": [{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}],
  "text": "example@yourdomain.com set version tag(s) 'key1' => 'value1', 'key2' => 'value2' for registered model 'someModel' version 8."
}

Gebeurtenis: COMMENT_CREATED

Respons

POST
/your/endpoint/for/event/comments/create
--data {
  "event": "COMMENT_CREATED",
  "webhook_id": "8d7fc634e624474f9bbfde960fdf354c",
  "event_timestamp": 1589859029343,
  "model_name": "Airline_Delay_SparkML",
  "version": "8",
  "comment": "Raw text content of the comment",
  "text": "A user commented on registered model 'someModel' version 8."
}

Beveiliging

Voor beveiliging bevat Azure Databricks de X-Databricks-Signature in de header die wordt berekend op basis van de nettolading en de gedeelde geheime sleutel die is gekoppeld aan de webhook met behulp van het HMAC met sha-256-algoritme.

Daarnaast kunt u een standaardautorisatieheader opnemen in de uitgaande aanvraag door er een op te geven in de HttpUrlSpec webhook.

Clientverificatie

Als een gedeeld geheim is ingesteld, moet de ontvanger van de nettolading de bron van de HTTP-aanvraag verifiëren met behulp van het gedeelde geheim om de nettolading te coderen en vervolgens de gecodeerde waarde te vergelijken met de X-Databricks-Signature uit de header. Dit is met name belangrijk als ssl-certificaatvalidatie is uitgeschakeld (dat wil gezegd, als het enable_ssl_verification veld is ingesteld op false).

Notitie

enable_ssl_verification is true standaard. Voor zelfondertekende certificaten moet dit veld zijn falseen moet de doelserver certificaatvalidatie uitschakelen.

Voor beveiligingsdoeleinden raadt Databricks u aan om geheime validatie uit te voeren met het HMAC-gecodeerde gedeelte van de nettolading. Als u validatie van hostnamen uitschakelt, verhoogt u het risico dat een aanvraag kwaadwillend kan worden doorgestuurd naar een onbedoelde host.

import hmac
import hashlib
import json

secret = shared_secret.encode('utf-8')
signature_key = 'X-Databricks-Signature'

def validate_signature(request):
  if not request.headers.has_key(signature_key):
    raise Exception('No X-Signature. Webhook not be trusted.')

  x_sig = request.headers.get(signature_key)
  body = request.body.encode('utf-8')
  h = hmac.new(secret, body, hashlib.sha256)
  computed_sig = h.hexdigest()

  if not hmac.compare_digest(computed_sig, x_sig.encode()):
    raise Exception('X-Signature mismatch. Webhook not be trusted.')

Autorisatieheader voor HTTP-registerwebhooks

Als een autorisatie-header is ingesteld, moeten clients de bron van de HTTP-aanvraag controleren door het bearer-token of de autorisatiereferenties in de autorisatieheader te verifiëren.

IP-acceptatielijst voor webhooks voor taakregister

Als u een webhook wilt gebruiken waarmee een taak wordt geactiveerd, wordt uitgevoerd in een andere werkruimte waarvoor IP-acceptatielijst is ingeschakeld, moet u het NAT-IP-adres van de regio toestaan waar de webhook zich bevindt om binnenkomende aanvragen te accepteren.

Als de webhook en de taak zich in dezelfde werkruimte bevinden, hoeft u geen IP-adressen toe te voegen aan uw acceptatielijst.

Als uw taak zich in een Azure-regio met meerdere tenants bevindt, raadpleegt u de adressen van het besturingsvlak van Azure Databricks. Neem voor alle andere regio's contact op met uw accountteam om de IP-adressen te identificeren die u nodig hebt voor de acceptatielijst.

Controlegebeurtenissen vastleggen

Als auditlogboekregistratie is ingeschakeld voor uw werkruimte, worden de volgende gebeurtenissen opgenomen in de auditlogboeken:

  • Webhook maken
  • Webhook bijwerken
  • Webhook vermelden
  • Webhook verwijderen
  • Webhook testen
  • Webhooktrigger

Auditlogboekregistratie voor webhooktriggers

Voor webhooks met HTTP-eindpunten wordt de HTTP-aanvraag die is verzonden naar de URL die is opgegeven voor de webhook, samen met de URL en enable_ssl_verification waarden vastgelegd.

Voor webhooks met taaktriggers worden de job_id en workspace_url waarden vastgelegd.

Voorbeelden

Dit gedeelte bevat:

Voorbeeldwerkstroom voor http-registerwebhook

1. Een webhook maken

Wanneer een HTTPS-eindpunt gereed is om de aanvraag voor de webhook-gebeurtenis te ontvangen, kunt u een webhook maken met behulp van de Webhooks Databricks REST API. De URL van de webhook kan bijvoorbeeld verwijzen naar Slack om berichten naar een kanaal te posten.

$ curl -X POST -H "Authorization: Bearer <access-token>" -d \
'{"model_name": "<model-name>",
  "events": ["MODEL_VERSION_CREATED"],
  "description": "Slack notifications",
  "status": "TEST_MODE",
  "http_url_spec": {
    "url": "https://hooks.slack.com/services/...",
    "secret": "anyRandomString"
    "authorization": "Bearer AbcdEfg1294"}}' https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/create

from databricks_registry_webhooks import RegistryWebhooksClient, HttpUrlSpec

http_url_spec = HttpUrlSpec(
  url="https://hooks.slack.com/services/...",
  secret="secret_string",
  authorization="Bearer AbcdEfg1294"
)
http_webhook = RegistryWebhooksClient().create_webhook(
  model_name="<model-name>",
  events=["MODEL_VERSION_CREATED"],
  http_url_spec=http_url_spec,
  description="Slack notifications",
  status="TEST_MODE"
)

Respons

{"webhook": {
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status":"TEST_MODE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}}}

U kunt ook een HTTP-registerwebhook maken met de Databricks Terraform-provider en databricks_mlflow_webhook.

2. De webhook testen

De vorige webhook is gemaakt in TEST_MODE, zodat een mockgebeurtenis kan worden geactiveerd om een aanvraag naar de opgegeven URL te verzenden. De webhook wordt echter niet geactiveerd voor een echte gebeurtenis. Het testeindpunt retourneert de ontvangen statuscode en hoofdtekst van de opgegeven URL.

$ curl -X POST -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/test

from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().test_webhook(
  id="1234567890"
)

Respons

{
 "status":200,
 "body":"OK"
}

3. Werk de webhook bij naar de actieve status

Als u de webhook voor echte gebeurtenissen wilt inschakelen, stelt u de status ACTIVE ervan in via een updateaanroep, die ook kan worden gebruikt om een van de andere eigenschappen te wijzigen.

$ curl -X PATCH -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890", "status": "ACTIVE"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/update

from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().update_webhook(
  id="1234567890",
  status="ACTIVE"
)

Respons

{"webhook": {
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status": "ACTIVE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}}}

4. De webhook verwijderen

Als u de webhook wilt uitschakelen, stelt u de status DISABLED ervan in op (met behulp van een vergelijkbare updateopdracht als hierboven) of verwijdert u deze.

$ curl -X DELETE -H "Authorization: Bearer <access-token>" -d \
'{"id": "1234567890"}' \
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/delete

from databricks_registry_webhooks import RegistryWebhooksClient

http_webhook = RegistryWebhooksClient().delete_webhook(
  id="1234567890"
)

Respons

{}

Voorbeeldwerkstroom van webhook voor taakregister

De werkstroom voor het beheren van webhooks voor het taakregister is vergelijkbaar met webhooks voor HTTP-register, met het enige verschil dat het job_spec veld vervangt http_url_spec .

Met webhooks kunt u taken in dezelfde werkruimte of in een andere werkruimte activeren. De werkruimte wordt opgegeven met behulp van de optionele parameter workspace_url. Als er geen workspace_url aanwezig is, is het standaardgedrag het activeren van een taak in dezelfde werkruimte als de webhook.

Vereisten

  • Een bestaande taak.
  • Een persoonlijk toegangstoken. Toegangstokens zijn niet opgenomen in het webhookobject dat wordt geretourneerd door de API's.

Notitie

Als best practice voor beveiliging, wanneer u zich verifieert met geautomatiseerde hulpprogramma's, systemen, scripts en apps, raadt Databricks u aan om persoonlijke toegangstokens te gebruiken die behoren tot service-principals in plaats van werkruimtegebruikers. Zie Tokens voor een service-principal beheren om tokens voor service-principals te maken.

Een webhook voor het taakregister maken

$ curl -X POST -H "Authorization: Bearer <access-token>" -d \ '{"model_name": "<model-name>",
  "events": ["TRANSITION_REQUEST_CREATED"],
  "description": "Job webhook trigger",
  "status": "TEST_MODE",
  "job_spec": {
    "job_id": "1",
    "workspace_url": "https://my-databricks-workspace.com",
    "access_token": "dapi12345..."}}'
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/create

from databricks_registry_webhooks import RegistryWebhooksClient, JobSpec

job_spec = JobSpec(
  job_id="1",
  workspace_url="https://my-databricks-workspace.com",
  access_token="dapi12345..."
)
job_webhook = RegistryWebhooksClient().create_webhook(
  model_name="<model-name>",
  events=["TRANSITION_REQUEST_CREATED"],
  job_spec=job_spec,
  description="Job webhook trigger",
  status="TEST_MODE"
)

Respons

{"webhook": {
   "id":"1234567891",
   "creation_timestamp":1591440826026,
   "last_updated_timestamp":1591440826026,
   "status":"TEST_MODE",
   "events":["TRANSITION_REQUEST_CREATED"],
   "job_spec": {
     "job_id": "1",
     "workspace_url": "https://my-databricks-workspace.com"
}}}

U kunt ook een webhook voor het taakregister maken met de Databricks Terraform-provider en databricks_mlflow_webhook.

Voorbeeld van registerwebhooks weergeven

$ curl -X GET -H "Authorization: Bearer <access-token>" -d \ '{"model_name": "<model-name>"}'
https://<databricks-instance>/api/2.0/mlflow/registry-webhooks/list

from databricks_registry_webhooks import RegistryWebhooksClient

webhooks_list = RegistryWebhooksClient().list_webhooks(model_name="<model-name>")

Respons

{"webhooks": [{
   "id":"1234567890",
   "creation_timestamp":1571440826026,
   "last_updated_timestamp":1582768296651,
   "status": "ACTIVE",
   "events":["MODEL_VERSION_CREATED"],
   "http_url_spec": {
     "url": "https://hooks.slack.com/services/...",
     "enable_ssl_verification": True
}},
{
   "id":"1234567891",
   "creation_timestamp":1591440826026,
   "last_updated_timestamp":1591440826026,
   "status":"TEST_MODE",
   "events":["TRANSITION_REQUEST_CREATED"],
   "job_spec": {
     "job_id": "1",
     "workspace_url": "https://my-databricks-workspace.com"
}}]}

Notebooks

MLflow Model Registry-webhooks REST API-voorbeeldnotebook

Notebook downloaden

Voorbeeldnotebook voor MLflow Model Registry-webhooks python-client

Notebook downloaden