MLflow Model Registry Webhooks på Azure Databricks

  • Artikel

Viktigt!

Den här funktionen finns som allmänt tillgänglig förhandsversion.

Med webhooks kan du lyssna efter Model Registry-händelser så att dina integreringar automatiskt kan utlösa åtgärder. Du kan använda webhooks för att automatisera och integrera din maskininlärningspipeline med befintliga CI/CD-verktyg och arbetsflöden. Du kan till exempel utlösa CI-versioner när en ny modellversion skapas eller meddela dina teammedlemmar via Slack varje gång en modellövergång till produktion begärs.

Webhooks är tillgängliga via Databricks REST API eller Python-klienten databricks-registry-webhooks i PyPI.

Kommentar

Webhooks är inte tillgängliga när du använder modeller i Unity Catalog. Ett alternativ finns i Kan jag använda scenövergångsbegäranden eller utlösa webhooks på händelser?.

Webhook-händelser

Du kan ange en webhook som ska utlösas vid en eller flera av dessa händelser:

  • MODEL_VERSION_CREATED: En ny modellversion skapades för den associerade modellen.
  • MODEL_VERSION_TRANSITIONED_STAGE: En modellversionssteg ändrades.
  • TRANSITION_REQUEST_CREATED: En användare begärde att en modellversionssteg skulle överföras.
  • COMMENT_CREATED: En användare skrev en kommentar till en registrerad modell.
  • REGISTERED_MODEL_CREATED: En ny registrerad modell skapades. Den här händelsetypen kan bara anges för en registeromfattande webhook, som kan skapas genom att inte ange ett modellnamn i create-begäran.
  • MODEL_VERSION_TAG_SET: En användare anger en tagg på modellversionen.
  • MODEL_VERSION_TRANSITIONED_TO_STAGING: En modellversion övergick till mellanlagring.
  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: En modellversion övergick till produktion.
  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: En modellversion arkiverades.
  • TRANSITION_REQUEST_TO_STAGING_CREATED: En användare begärde att en modellversion skulle övergå till mellanlagring.
  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: En användare begärde att en modellversion skulle övergå till produktion.
  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: En användare begärde att en modellversion skulle arkiveras.

Typer av webhooks

Det finns två typer av webhooks baserat på deras utlösarmål:

  • Webhooks med HTTP-slutpunkter (HTTP-registerwebbhooks): Skicka utlösare till en HTTP-slutpunkt.
  • Webhooks med jobbutlösare (webhooks för jobbregister): Utlösa ett jobb på en Azure Databricks-arbetsyta. Om IP-tillåtna listor är aktiverade på jobbets arbetsyta måste du tillåtalistning av arbetsytans IP-adresser för modellregistret. Mer information finns i IP-tillåtna listor för jobbregisterwebbhooks .

Det finns också två typer av webhooks baserat på deras omfång, med olika krav för åtkomstkontroll:

  • Modellspecifika webhooks: Webhooken gäller för en specifik registrerad modell. Du måste ha CAN MANAGE-behörigheter för den registrerade modellen för att skapa, ändra, ta bort eller testa modellspecifika webhooks.
  • Webhooks för hela registret: Webhooken utlöses av händelser på alla registrerade modeller på arbetsytan, inklusive skapandet av en ny registrerad modell. Om du vill skapa en registeromfattande webhook utelämnar du fältet när det model_name skapas. Du måste ha administratörsbehörighet för arbetsytan för att kunna skapa, ändra, ta bort eller testa webhooks för hela registret.

Webhook-nyttolast

Varje händelseutlösare har minimala fält som ingår i nyttolasten för den utgående begäran till webhooksslutpunkten.

Nyttolast för jobbregisterwebbhook

Nyttolasten för en jobbregisterwebbhook beror på typen av jobb och skickas till jobs/run-now slutpunkten på målarbetsytan.

Jobb med en uppgift

Jobb med en uppgift har en av tre nyttolaster baserat på aktivitetstypen.

Notebook- och Python-hjuljobb

Notebook- och Python-hjuljobb har en JSON-nyttolast med en parameterordlista som innehåller ett fält event_message.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}
Python-, JAR- och Spark-skicka-jobb

Python-, JAR- och Spark-skicka-jobb har en JSON-nyttolast med en parameterlista.

{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Alla andra jobb

Alla andra typer av jobb har en JSON-nyttolast utan parametrar.

{
  "job_id": 1234567890
}

Jobb med flera aktiviteter

Jobb med flera aktiviteter har en JSON-nyttolast med alla parametrar ifyllda för att ta hänsyn till olika aktivitetstyper.

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

Exempel på nyttolaster

Händelse: MODEL_VERSION_TRANSITIONED_STAGE

Response

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

Händelse: MODEL_VERSION_TAG_SET

Response

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

Händelse: COMMENT_CREATED

Response

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

Säkerhet

För säkerhet inkluderar Azure Databricks X-Databricks-Signature i huvudet som beräknas från nyttolasten och den delade hemliga nyckeln som är associerad med webhooken med hjälp av HMAC med SHA-256-algoritmen.

Dessutom kan du inkludera ett standardauktoriseringshuvud i den utgående begäran genom att ange en i HttpUrlSpec webhooken.

Klientverifiering

Om en delad hemlighet har angetts bör nyttolastmottagaren verifiera källan till HTTP-begäran med hjälp av den delade hemligheten till HMAC-koda nyttolasten och sedan jämföra det kodade värdet med X-Databricks-Signature från huvudet. Detta är särskilt viktigt om SSL-certifikatverifiering är inaktiverat (det vill: om fältet enable_ssl_verification är inställt på false).

Kommentar

enable_ssl_verification är true som standard. För självsignerade certifikat måste det här fältet vara false, och målservern måste inaktivera certifikatverifiering.

Av säkerhetsskäl rekommenderar Databricks att du utför hemlig validering med den HMAC-kodade delen av nyttolasten. Om du inaktiverar validering av värdnamn ökar risken för att en begäran dirigeras till en oavsiktlig värd.

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.')

Auktoriseringshuvud för HTTP-registerwebbhooks

Om ett auktoriseringshuvud har angetts bör klienterna verifiera källan till HTTP-begäran genom att verifiera ägartoken eller autentiseringsuppgifterna för auktorisering i auktoriseringshuvudet.

IP-tillåtna listor för jobbregisterwebbhooks

Om du vill använda en webhook som utlöser jobbkörningar på en annan arbetsyta som har AKTIVERAT IP-tillåtna listor, måste du tillåtalistning av regionens NAT IP där webhooken finns för att acceptera inkommande begäranden.

Om webhooken och jobbet finns på samma arbetsyta behöver du inte lägga till ip-adresser i listan över tillåtna adresser.

Om ditt jobb finns i en Azure-region med flera klientorganisationer kan du läsa Mer information om Azure Databricks-kontrollplansadresser. För alla andra regioner kontaktar du ditt kontoteam för att identifiera de IP-adresser som du behöver för att tillåta listan.

Granskningsloggning

Om granskningsloggning är aktiverat för din arbetsyta inkluderas följande händelser i granskningsloggarna:

  • Skapa webhook
  • Uppdatera webhook
  • Lista webhook
  • Ta bort webhook
  • Testa webhook
  • Webhook-utlösare

Webhook-utlösargranskningsloggning

För webhooks med HTTP-slutpunkter loggas HTTP-begäran som skickas till den URL som angetts för webhooken tillsammans med URL:en och enable_ssl_verification värdena.

För webhooks med jobbutlösare job_id loggas värdena och workspace_url .

Exempel

Det här avsnittet innehåller:

EXEMPELarbetsflöde för HTTP-register webhook

1. Skapa en webhook

När en HTTPS-slutpunkt är redo att ta emot webhook-händelsebegäran kan du skapa en webhook med hjälp av webhooks Databricks REST API. Webhookens URL kan till exempel peka på Slack för att skicka meddelanden till en kanal.

$ 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"
)

Response

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

Du kan också skapa en HTTP-registerwebbhook med Databricks Terraform-providern och databricks_mlflow_webhook.

2. Testa webhooken

Den tidigare webhooken skapades i TEST_MODE, så en falsk händelse kan utlösas för att skicka en begäran till den angivna URL:en. Webhooken utlöses dock inte vid en verklig händelse. Testslutpunkten returnerar den mottagna statuskoden och brödtexten från den angivna URL:en.

$ 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"
)

Response

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

3. Uppdatera webhooken till aktiv status

Om du vill aktivera webhooken för verkliga händelser anger du dess status till ACTIVE via ett uppdateringsanrop, som också kan användas för att ändra någon av dess andra egenskaper.

$ 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"
)

Response

{"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. Ta bort webhooken

Om du vill inaktivera webhooken anger du dess status till DISABLED (med ett liknande uppdateringskommando som ovan) eller tar bort den.

$ 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"
)

Response

{}

Arbetsflöde för webhookexempel för jobbregister

Arbetsflödet för att hantera webhooks för jobbregister liknar HTTP-registrets webhooks, där den enda skillnaden är det job_spec fält som ersätter http_url_spec fältet.

Med webhooks kan du utlösa jobb på samma arbetsyta eller på en annan arbetsyta. Arbetsytan anges med den valfria parametern workspace_url. Om nej workspace_url finns är standardbeteendet att utlösa ett jobb på samma arbetsyta som webhooken.

Krav

  • Ett befintligt jobb.
  • En personlig åtkomsttoken. Observera att åtkomsttoken inte ingår i webhook-objektet som returneras av API:erna.

Kommentar

När du autentiserar med automatiserade verktyg, system, skript och appar rekommenderar Databricks att du använder personliga åtkomsttoken som tillhör tjänstens huvudnamn i stället för arbetsyteanvändare. Information om hur du skapar token för tjänstens huvudnamn finns i Hantera token för tjänstens huvudnamn.

Skapa en webhook för jobbregister

$ 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"
)

Response

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

Du kan också skapa en webhook för jobbregister med Databricks Terraform-providern och databricks_mlflow_webhook.

Exempel på listregisterwebbhooks

$ 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>")

Response

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

Notebook-filer

MLflow Model Registry webhooks REST API-exempel notebook-fil

Hämta notebook-fil

MLflow Model Registry webhooks Python-klientexempel notebook

Hämta notebook-fil