Webové hooky pro registr modelů pracovního prostoru

Článek
12/27/2024

Důležité

Tato funkce je ve verzi Public Preview.

Webhooky umožňují naslouchat událostem registru modelů pracovního prostoru, aby integrace mohly automaticky aktivovat akce. Webhooky můžete použít k automatizaci a integraci kanálu strojového učení s existujícími nástroji a pracovními postupy CI/CD. Můžete například aktivovat sestavení CI při vytvoření nové verze modelu nebo upozorňovat členy týmu prostřednictvím Slacku při každém přechodu modelu do produkčního prostředí.

Webhooky jsou k dispozici prostřednictvím rozhraní REST API Databricks nebo klienta databricks-registry-webhooks Pythonu v PyPI.

Poznámka:

Webhooky nejsou k dispozici při použití modelů v Unity Catalog. Alternativu najdete v tématu Můžu použít žádosti o přechod fáze nebo aktivovat webhooky u událostí?. Odesílání webhooků do privátních koncových bodů (koncové body, které nejsou přístupné z veřejného internetu), se nepodporuje.

Události webhooku

Můžete zadat webhook, který se má aktivovat při jedné nebo několika z těchto událostí:

MODEL_VERSION_CREATED: Pro přidružený model byla vytvořena nová verze modelu.
MODEL_VERSION_TRANSITIONED_STAGE: Fáze verze modelu byla změněna.
TRANSITION_REQUEST_CREATED: Uživatel požádal o přechod fáze verze modelu.
COMMENT_CREATED: Uživatel napsal komentář k registrovanému modelu.
REGISTERED_MODEL_CREATED: Byl vytvořen nový zaregistrovaný model. Tento typ události lze zadat pouze pro webhook na úrovni registru, který lze vytvořit tak, že v požadavku vytvoření nezadáte název modelu.
MODEL_VERSION_TAG_SET: Uživatel set značku verze modelu.
MODEL_VERSION_TRANSITIONED_TO_STAGING: Verze modelu byla převedena do přípravného prostředí.
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Verze modelu byla převedena do produkčního prostředí.
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Byla archivována verze modelu.
TRANSITION_REQUEST_TO_STAGING_CREATED: Uživatel požádal o přechod na verzi modelu do přípravného prostředí.
TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Uživatel požádal o přechod na verzi modelu do produkčního prostředí.
TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Uživatel požádal o archivaci verze modelu.

Typy webhooků

Na základě cílů triggeru existují dva typy webhooků:

Webhooky s koncovými body HTTP (webhooky registru HTTP):: Odesílat triggery do koncového bodu HTTP.
Webhooky s triggery úloh (webhooky registru úloh): Aktivují úlohu v pracovním prostoru Azure Databricks. Pokud je v pracovním prostoru úlohy povolená seznam povolených IP adres, musíte povolit IP adresy pracovního prostoru registru modelu. Další informace najdete v tématu Povolení IP adres pro webhooky registru úloh.

Existují také dva typy webhooků založených na jejich oboru s různými požadavky na řízení přístupu:

Webhooky specifické pro konkrétní model: Webhook se vztahuje na konkrétní registrovaný model. Abyste mohli vytvářet, upravovat, odstraňovat nebo testovat webhooky specifické pro model, musíte mít oprávnění CAN MANAGE u registrovaného modelu.
Webhooky pro celý registr: Webhook se aktivuje událostmi u libovolného registrovaného modelu v pracovním prostoru, včetně vytvoření nového registrovaného modelu. Pokud chcete vytvořit webhook pro celý registr, vymiřte model_name pole při vytváření. Abyste mohli vytvářet, upravovat, odstraňovat nebo testovat webhooky pro celý registr, musíte mít oprávnění správce pracovního prostoru.

Datová část Webhooku

Každý trigger události obsahuje minimální pole zahrnutá v datové části odchozího požadavku do koncového bodu webhooku.

Citlivé informace, jako je umístění cesty k artefaktu, jsou vyloučeny. Uživatelé a objekty zabezpečení s příslušnými seznamy ACL můžou k dotazování registru modelů na tyto informace použít klient nebo rozhraní REST API.
Datové části nejsou šifrované. Informace o tom, jak ověřit, jestli je Azure Databricks zdrojem webhooku, najdete v tématu Zabezpečení .
Pole text usnadňuje integraci Slacku. Pokud chcete odeslat zprávu Slack, zadejte koncový bod Webhooku Slack jako adresu URL webhooku.

Datová část webhooku registru úloh

Datová část webhooku registru úloh závisí na typu úlohy a odesílá se do koncového jobs/run-now bodu v cílovém pracovním prostoru.

Úlohy s jedním úkolem

Úlohy s jedním úkolem mají jednu ze tří datových částí na základě typu úkolu.

Úlohy poznámkového bloku a kolečka Pythonu

Úlohy poznámkového bloku a kola Pythonu mají datovou část JSON se slovníkem parametrů, který obsahuje pole event_message.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}

Úlohy pythonu, JAR a Sparku pro odesílání

Úlohy Python, JAR a Spark pro odesílání mají datovou část JSON s parametrem list.

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

Všechny ostatní úlohy

Všechny ostatní typy úloh mají datovou část JSON bez parameters.

{
  "job_id": 1234567890
}

Úlohy s více úlohami

Víceúlohové úlohy mají datovou část JSON se všemi parameters připravenými pro různé druhy úloh.

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

Ukázkové datové části

událost: `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."
}

událost: `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."
}

událost: `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."
}

Zabezpečení

Pro zabezpečení azure Databricks zahrnuje X-Databricks-Signature v hlavičce vypočítané z datové části a sdílený tajný klíč přidružený k webhooku pomocí HMAC s algoritmem SHA-256.

Kromě toho můžete do odchozího požadavku zahrnout standardní autorizační hlavičku tak, že zadáte jednu v HttpUrlSpec webhooku.

Ověření klienta

Pokud je sdílený tajný klíč set, příjemce datové části by měl ověřit zdroj požadavku HTTP tak, že pomocí sdíleného tajného klíče zakóduje datovou část pomocí HMAC a poté porovná zakódovanou hodnotu s X-Databricks-Signature z hlavičky. To je zvlášť důležité, pokud je ověření certifikátu SSL zakázáno (to znamená, že pokud je pole enable_ssl_verification nastaveno na setfalse).

Poznámka:

enable_ssl_verification je true ve výchozím nastavení. U certifikátů podepsaných svým držitelem musí být falsetoto pole a cílový server musí zakázat ověření certifikátu.

Pro účely zabezpečení doporučuje Databricks provést ověření tajného kódu pomocí části datové části zakódované pomocí HMAC. Pokud zakážete ověření názvu hostitele, zvýšíte riziko, že požadavek může být záměrně směrován na nezamýšleného hostitele.

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

Autorizační hlavička pro webhooky registru HTTP

Pokud je autorizační hlavička set, klienti by měli ověřit zdroj požadavku HTTP ověřením nosného tokenu nebo autorizačního credentials v autorizační hlavičce.

Seznam povolených IP adres pro webhooky registru úloh

Pokud chcete použít webhook, který aktivuje spuštění úlohy v jiném pracovním prostoru, který má povolený seznam povolených IP adres, musíte seznam povolených IP adresa překladu adres (NAT) oblasti, where webhook se nachází pro příjem příchozích požadavků.

Pokud je webhook a úloha ve stejném pracovním prostoru, nemusíte do seznamu povolených přidávat žádné IP adresy.

Pokud se vaše úloha nachází v oblasti Azure s více tenanty, prohlédněte si adresy řídicí roviny Azure Databricks. Ve všech ostatních oblastech se obraťte na tým účtu a identifikujte IP adresy, které potřebujete povolit.

Protokolování auditu

Pokud je pro váš pracovní prostor povolené protokolování auditu, jsou do protokolů auditu zahrnuty následující události:

Vytvořit webhook
Update webhook
webhook List
Odstranění webhooku
Test webhooku
Trigger Webhooku

Protokolování auditu triggeru Webhooku

U webhooků s koncovými body HTTP se zaprotokoluje požadavek HTTP odeslaný na adresu URL zadanou pro webhook spolu s enable_ssl_verificationavalues.

U webhooků s triggery úloh se protokolují job_id a workspace_urlvalues.

Příklady

Tato část obsahuje:

Příklad pracovního postupu webhooku registru HTTP
Příklad pracovního postupu webhooku registru úloh
list příklad webhooků.
Dva ukázkové poznámkové bloky: jeden ilustrující rozhraní REST API a jeden ilustrující klienta Pythonu.

Ukázkový pracovní postup webhooku registru HTTP

1. Vytvoření webhooku

Když je koncový bod HTTPS připravený k přijetí požadavku na událost webhooku, můžete vytvořit webhook pomocí webhooků Databricks REST API. Například adresa URL webhooku může odkazovat na Slack a publikovat zprávy do kanálu.

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

Webhook registru HTTP můžete vytvořit také s poskytovatelem Databricks Terraform a databricks_mlflow_webhook.

2. Otestování webhooku

Předchozí webhook byl vytvořen v TEST_MODE, takže je možné aktivovat napodobenou událost odeslat požadavek na zadanou adresu URL. Webhook se ale neaktivuje u skutečné události. Testovací koncový bod vrátí přijatý stavový kód a text ze zadané adresy 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"
)

Response

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

3. Update webhook do aktivního stavu

Pokud chcete webhook povolit u reálných událostí, set jeho stav na ACTIVE prostřednictvím update volání, které lze také použít ke změně kterékoli z jeho dalších vlastností.

$ 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. Odstraňte webhook.

Pokud chcete webhook zakázat, set stav DISABLED (pomocí podobného příkazu update jako výše) nebo ho odstraňte.

$ 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

{}

Ukázkový pracovní postup webhooku registru úloh

Pracovní postup správy webhooků registru úloh je podobný webhookům registru HTTP, přičemž jediným rozdílem je job_spec pole, které nahrazuje http_url_spec toto pole.

Pomocí webhooků můžete aktivovat úlohy ve stejném pracovním prostoru nebo v jiném pracovním prostoru. Pracovní prostor je zadán pomocí volitelného parametru workspace_url. Pokud není k dispozici, workspace_url výchozím chováním je aktivovat úlohu ve stejném pracovním prostoru jako webhook.

Požadavky

Existující úloha.
Osobní přístupový token. Upozorňujeme, že přístupové tokeny můžou číst jenom služba MLflow a uživatelé Azure Databricks je nevrátí v rozhraní API registru modelů.

Poznámka:

Osvědčeným postupem při ověřování pomocí automatizovaných nástrojů, systémů, skriptů a aplikací doporučuje Databricks místo uživatelů pracovního prostoru používat tokeny patního přístupu, které patří instančním objektům . Pokud chcete vytvořit tokeny pro instanční objekty, přečtěte si téma Správa tokenů instančního objektu.

Vytvoření webhooku registru úloh

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

Webhook registru úloh můžete vytvořit také s poskytovatelem Databricks Terraform a databricks_mlflow_webhook.

Příklad webhooků registru List

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

Poznámkové bloky

Ukázkový poznámkový blok rozhraní REST API registru modelů MLflow

poznámkového bloku

Ukázkový poznámkový blok klienta Registru modelů MLflow v registru pythonových modelů

Get poznámkový blok

Sdílet prostřednictvím

Webové hooky pro registr modelů pracovního prostoru

Události webhooku

Typy webhooků

Datová část Webhooku

Datová část webhooku registru úloh

Úlohy s jedním úkolem

Úlohy poznámkového bloku a kolečka Pythonu

Úlohy pythonu, JAR a Sparku pro odesílání

Všechny ostatní úlohy

Úlohy s více úlohami

Ukázkové datové části

událost: `MODEL_VERSION_TRANSITIONED_STAGE`

událost: `MODEL_VERSION_TAG_SET`

událost: `COMMENT_CREATED`

Zabezpečení

Ověření klienta

Autorizační hlavička pro webhooky registru HTTP

Seznam povolených IP adres pro webhooky registru úloh

Protokolování auditu

Protokolování auditu triggeru Webhooku

Příklady

Ukázkový pracovní postup webhooku registru HTTP

1. Vytvoření webhooku

2. Otestování webhooku

3. Update webhook do aktivního stavu

4. Odstraňte webhook.

Ukázkový pracovní postup webhooku registru úloh

Požadavky

Vytvoření webhooku registru úloh

Příklad webhooků registru List

Poznámkové bloky

Ukázkový poznámkový blok rozhraní REST API registru modelů MLflow

Ukázkový poznámkový blok klienta Registru modelů MLflow v registru pythonových modelů

Váš názor

Další materiály

Sdílet prostřednictvím

Webové hooky pro registr modelů pracovního prostoru

Události webhooku

Typy webhooků

Datová část Webhooku

Datová část webhooku registru úloh

Úlohy s jedním úkolem

Úlohy poznámkového bloku a kolečka Pythonu

Úlohy pythonu, JAR a Sparku pro odesílání

Všechny ostatní úlohy

Úlohy s více úlohami

Ukázkové datové části

událost: MODEL_VERSION_TRANSITIONED_STAGE

událost: MODEL_VERSION_TAG_SET

událost: COMMENT_CREATED

Zabezpečení

Ověření klienta

Autorizační hlavička pro webhooky registru HTTP

Seznam povolených IP adres pro webhooky registru úloh

Protokolování auditu

Protokolování auditu triggeru Webhooku

Příklady

Ukázkový pracovní postup webhooku registru HTTP

1. Vytvoření webhooku

2. Otestování webhooku

3. Update webhook do aktivního stavu

4. Odstraňte webhook.

Ukázkový pracovní postup webhooku registru úloh

Požadavky

Vytvoření webhooku registru úloh

Příklad webhooků registru List

Poznámkové bloky

Ukázkový poznámkový blok rozhraní REST API registru modelů MLflow

Ukázkový poznámkový blok klienta Registru modelů MLflow v registru pythonových modelů

Váš názor

Další materiály

událost: `MODEL_VERSION_TRANSITIONED_STAGE`

událost: `MODEL_VERSION_TAG_SET`

událost: `COMMENT_CREATED`