Share via

MLflow-modellregisztrációs adatbázis webhookjai az Azure Databricksben

  • Cikk

Fontos

Ez a funkció a nyilvános előzetes verzióban érhető el.

A webhookok lehetővé teszik a Modellregisztrációs adatbázis eseményeinek figyelést, hogy az integrációk automatikusan aktiválhassák a műveleteket. Webhookokkal automatizálhatja és integrálhatja a gépi tanulási folyamatot a meglévő CI-/CD-eszközökkel és munkafolyamatokkal. Például aktiválhat CI-buildeket új modellverzió létrehozásakor, vagy értesítheti a csapattagokat a Slacken keresztül minden alkalommal, amikor modellváltást kérnek az éles környezetbe.

A webhookok a Databricks REST API-n vagy a Python-ügyfélen databricks-registry-webhooks keresztül érhetők el a PyPI-n.

Feljegyzés

A Webhookok nem érhetők el, ha modelleket használ a Unity Katalógusban. Másik lehetőségként lásd: Használhatok szakaszáttraszt-kérelmeket, vagy aktiválhatok webhookokat az eseményeken?. A webhookok privát végpontokra (a nyilvános internetről nem elérhető végpontokra) való küldése nem támogatott.

Webhookesemények

Megadhatja, hogy egy webhook aktiválódjon egy vagy több ilyen esemény esetén:

  • MODEL_VERSION_CREATED: Új modellverzió lett létrehozva a társított modellhez.
  • MODEL_VERSION_TRANSITIONED_STAGE: A modellverzió szakasza megváltozott.
  • TRANSITION_REQUEST_CREATED: A felhasználó kérte a modellverzió fázisának áttűnést.
  • COMMENT_CREATED: Egy felhasználó megjegyzést írt egy regisztrált modellhez.
  • REGISTERED_MODEL_CREATED: Létre lett hozva egy új regisztrált modell. Ez az eseménytípus csak beállításjegyzék-szintű webhookokhoz adható meg, amely úgy hozható létre, hogy nem ad meg modellnevet a létrehozási kérelemben.
  • MODEL_VERSION_TAG_Standard kiadás T: A felhasználó beállít egy címkét a modellverzióra.
  • MODEL_VERSION_TRANSITIONED_TO_STAGING: A modellverzió átmeneti állapotba került.
  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: A modellverziót éles környezetbe helyezték át.
  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: A modellverzió archiválva lett.
  • TRANSITION_REQUEST_TO_STAGING_CREATED: A felhasználó azt kérte, hogy a modellverziót átmeneti állapotba váltsa át.
  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: A felhasználó azt kérte, hogy a modellverziót éles környezetbe váltsa át.
  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Egy felhasználó kérte, hogy a modellverzió archiválva legyen.

Webhookok típusai

A webhookok kétféleképpen használhatók triggercéljaik alapján:

  • HTTP-végpontokkal rendelkező webhookok (HTTP-beállításjegyzék-webhookok):Eseményindítók küldése HTTP-végpontra.
  • Webhookok feladat-eseményindítókkal (feladatregisztrációs adatbázis webhookok):Feladat aktiválása egy Azure Databricks-munkaterületen. Ha az IP-engedélyezési lista engedélyezve van a feladat munkaterületén, engedélyeznie kell a modellregisztrációs adatbázis munkaterületi IP-címeit. További információt a feladatregisztrációs webhookok IP-engedélyezési listájában talál.

A webhookok hatóköre alapján kétféle webhook létezik, különböző hozzáférés-vezérlési követelményekkel:

  • Modellspecifikus webhookok: A webhook egy adott regisztrált modellre vonatkozik. A modellspecifikus webhookok létrehozásához, módosításához, törléséhez vagy teszteléséhez rendelkeznie kell a regisztrált modellRE vonatkozó MANAGE engedélyekkel.
  • Beállításjegyzék-szintű webhookok: A webhookot a munkaterületen található bármely regisztrált modell eseményei aktiválják, beleértve egy új regisztrált modell létrehozását is. Beállításjegyzék-szintű webhook létrehozásához hagyja ki a mezőt a model_name létrehozáskor. A beállításjegyzék-szintű webhookok létrehozásához, módosításához, törléséhez vagy teszteléséhez munkaterület-rendszergazdai engedélyekkel kell rendelkeznie.

Webhook hasznos adatai

Minden eseményindító minimális mezőket tartalmaz a webhook végpont felé irányuló kimenő kérés hasznos adataiban.

  • Az olyan bizalmas információk, mint az összetevő elérési útja, ki vannak zárva. A megfelelő ACL-ekkel rendelkező felhasználók és tagok ügyfél- vagy REST API-k használatával kérdezhetik le a modellregisztrációs adatbázist ezekről az információkról.
  • A hasznos adatok nincsenek titkosítva. A webhook forrásának az Azure Databricks forrásának ellenőrzéséről a Security (Biztonság ) című témakörben olvashat.
  • A text mező megkönnyíti a Slack integrációját. Slack-üzenet küldéséhez adjon meg egy Slack webhook-végpontot webhook URL-címként.

Feladatregisztrációs adatbázis webhook hasznos adatai

A feladatregisztrációs adatbázis webhookjának hasznos adatai a feladat típusától függenek, és a jobs/run-now cél-munkaterület végpontjára kerülnek.

Egyfeladatos feladatok

Az egyfeladatos feladatok a tevékenységtípus alapján három hasznos adat egyikével rendelkeznek.

Notebook- és Python-kerékfeladatok

A jegyzetfüzet- és Python-kerékfeladatok JSON hasznos adattal rendelkeznek, amely egy mezőt event_messagetartalmazó paraméterszótárral rendelkezik.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}
Python-, JAR- és Spark-küldési feladatok

A Python-, JAR- és Spark-küldési feladatok JSON-hasznos adatokkal és paraméterlistával rendelkeznek.

{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Minden más feladat

Minden más típusú feladat JSON hasznos adattal rendelkezik paraméterek nélkül.

{
  "job_id": 1234567890
}

Többfeladatos feladatok

A többfeladatos feladatok JSON-hasznos adatokkal rendelkeznek, és az összes paraméter fel van töltve, hogy figyelembe vegyék a különböző tevékenységtípusokat.

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

Példa hasznos adatokra

Esemény: MODEL_VERSION_TRANSITIONED_STAGE

Válasz

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

Esemény: MODEL_VERSION_TAG_SET

Válasz

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

Esemény: COMMENT_CREATED

Válasz

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

Biztonság

A biztonság érdekében az Azure Databricks tartalmazza az X-Databricks-Signature azonosítót a fejlécben, amely a hasznos adatokból számítható ki, valamint a webhookhoz társított megosztott titkos kulcsot az SHA-256 algoritmussal rendelkező HMAC használatával.

Emellett egy szabványos engedélyezési fejlécet is megadhat a kimenő kérelemben, ha a HttpUrlSpec webhook egyikét adja meg.

Ügyfél-ellenőrzés

Ha egy megosztott titkos kód van beállítva, a hasznos adatok címzettjének ellenőriznie kell a HTTP-kérés forrását a megosztott titkos kód használatával a hasznos adatok HMAC-kódolásához, majd a kódolt értéknek a X-Databricks-Signature fejlécből származó értékkel való összehasonlításával. Ez különösen akkor fontos, ha az SSL-tanúsítvány érvényesítése le van tiltva (vagyis ha a enable_ssl_verification mező értéke false).

Feljegyzés

enable_ssl_verification alapértelmezés true szerint. Az önaláírt tanúsítványok esetében ennek a mezőnek kell lennie false, és a célkiszolgálónak le kell tiltania a tanúsítványérvényesítést.

Biztonsági okokból a Databricks azt javasolja, hogy végezzen titkos ellenőrzést a hasznos adat HMAC által kódolt részével. Ha letiltja a gazdagép nevének érvényesítését, növeli annak kockázatát, hogy a kérések rosszindulatúan átirányíthatók egy nem kívánt gazdagépre.

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

HTTP-beállításjegyzék-webhookok engedélyezési fejléce

Ha az engedélyezési fejléc be van állítva, az ügyfeleknek ellenőriznie kell a HTTP-kérés forrását a tulajdonosi jogkivonat vagy az engedélyezési hitelesítő adatok hitelesítésével az Engedélyezési fejlécben.

IP-engedélyezési lista a feladatregisztrációs adatbázis webhookjaihoz

Ha olyan webhookot szeretne használni, amely egy másik munkaterületen indítja el a feladatot, amelyen engedélyezve van az IP-engedélyezési lista, engedélyeznie kell a régió NAT IP-címét, ahol a webhook található, hogy fogadja a bejövő kéréseket.

Ha a webhook és a feladat ugyanabban a munkaterületen található, nem kell IP-címeket hozzáadnia az engedélyezési listához.

Ha a feladat egy több-bérlős Azure-régióban található, tekintse meg az Azure Databricks vezérlősík-címeit. Minden más régióban lépjen kapcsolatba a fiókcsapatával az engedélyezési listához szükséges IP-címek azonosításához.

Naplózás naplózása

Ha a naplózás engedélyezve van a munkaterületen, az alábbi események szerepelnek a naplókban:

  • Webhook létrehozása
  • Webhook frissítése
  • Webhookok listázása
  • Webhook törlése
  • Webhook tesztelése
  • Webhook-eseményindító

Webhook eseményindító naplózása

HTTP-végpontokkal rendelkező webhookok esetén a rendszer naplózza a webhookhoz megadott URL-címre küldött HTTP-kérést, valamint az URL-címet és enable_ssl_verification az értékeket.

A feladat-eseményindítókkal rendelkező webhookok esetében a rendszer naplózza az értékeket és workspace_url az job_id értékeket.

Példák

A szakasz a következőket ismerteti:

PÉLDA a HTTP-beállításjegyzék webhook-munkafolyamatára

1. Webhook létrehozása

Ha egy HTTPS-végpont készen áll a webhook eseménykérelem fogadására, létrehozhat egy webhookot a webhooks Databricks REST API használatával. A webhook URL-címe például a Slackre mutathat, hogy üzeneteket tegyen közzé egy csatornán.

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

Válasz

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

Http-beállításjegyzék-webhookot is létrehozhat a Databricks Terraform szolgáltatójával és databricks_mlflow_webhook.

2. A webhook tesztelése

Az előző webhook itt lett létrehozva TEST_MODE, így egy szimulált esemény aktiválható, hogy kérést küldjön a megadott URL-címre. A webhook azonban nem aktiválódik valós eseményen. A tesztvégpont a kapott állapotkódot és törzset adja vissza a megadott URL-címről.

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

Válasz

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

3. A webhook frissítése aktív állapotra

A webhook valós eseményekhez való engedélyezéséhez állítsa az állapotát ACTIVE frissítési hívással, amely bármely más tulajdonságának módosítására is használható.

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

Válasz

{"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. A webhook törlése

A webhook letiltásához állítsa az állapotát DISABLED (a fentihez hasonló frissítési paranccsal), vagy törölje azt.

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

Válasz

{}

Feladatregisztrációs adatbázis webhook-példa munkafolyamata

A feladatregisztrációs adatbázis webhookainak kezelésére szolgáló munkafolyamat hasonló a HTTP-beállításjegyzék-webhookokhoz, és az egyetlen különbség a job_spec mező helyébe lépő http_url_spec mező.

A webhookok használatával feladatokat indíthat el ugyanabban a munkaterületen vagy egy másik munkaterületen. A munkaterület az opcionális paraméterrel workspace_urlvan megadva. Ha nincs workspace_url jelen, az alapértelmezett viselkedés az, hogy a webhooktal azonos munkaterületen aktivál egy feladatot.

Követelmények

  • Egy meglévő feladat.
  • Személyes hozzáférési jogkivonat. Vegye figyelembe, hogy a hozzáférési jogkivonatok nem szerepelnek az API-k által visszaadott webhook-objektumban.

Feljegyzés

Ajánlott biztonsági eljárásként, ha automatizált eszközökkel, rendszerekkel, szkriptekkel és alkalmazásokkal hitelesít, a Databricks azt javasolja, hogy munkaterület-felhasználók helyett a szolgáltatásnevekhez tartozó személyes hozzáférési jogkivonatokat használja. A szolgáltatásnevek jogkivonatainak létrehozásáról a szolgáltatásnév jogkivonatainak kezelése című témakörben olvashat.

Feladatregisztrációs adatbázis webhook létrehozása

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

Válasz

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

A Databricks Terraform-szolgáltatóval és databricks_mlflow_webhook is létrehozhat egy feladatregisztrációs adatbázis-webhookot.

Példa beállításjegyzék-webhookok listázására

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

Válasz

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

Jegyzetfüzetek

MLflow Modellregisztrációs adatbázis webhookok REST API-példajegyzetfüzete

Jegyzetfüzet beszerzése

MLflow Model Registry webhooks Python-ügyfél-példajegyzetfüzet

Jegyzetfüzet beszerzése