Webhooky registru modelů MLflow v Azure Databricks

  • Článek

Důležité

Tato funkce je ve verzi Public Preview.

Webhooky umožňují naslouchat událostem registru modelů, 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 při použití modelů v katalogu Unity k dispozici. 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 nastavil značku na verzi 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 pro odesílání Pythonu, JAR a Sparku mají datovou část JSON se seznamem parametrů.

{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Všechny ostatní úlohy

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

{
  "job_id": 1234567890
}

Úlohy s více úlohami

Úlohy s více úlohami mají datovou část JSON se všemi parametry naplněnými k účtu pro různé typy ú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 nastavený sdílený tajný klíč, příjemce datové části by měl ověřit zdroj požadavku HTTP pomocí sdíleného tajného kódu pro kódování HMAC datovou část a pak porovnat zakódovanou hodnotu s hlavičkou X-Databricks-Signature . To je zvlášť důležité, pokud je ověření certifikátu SSL zakázané (to znamená, že pokud enable_ssl_verification je pole nastavené na false).

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 nastavená, klienti by měli ověřit zdroj požadavku HTTP ověřením nosného tokenu nebo autorizačních přihlašovacích údajů v hlavičce Autorizace.

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 povolit IP adresu překladu adres (NAT) oblasti, ve které se webhook 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
  • Aktualizace webhooku
  • Vypsat webhook
  • 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 adresou URL a enable_ssl_verification hodnotami.

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

Příklady

Tato část obsahuje:

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. Aktualizace webhooku na aktivní stav

Chcete-li povolit webhook pro skutečné události, nastavte jeho stav ACTIVE prostřednictvím volání aktualizace, které lze použít také ke změně některé z jejích 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, nastavte jeho stav DISABLED na (pomocí podobného příkazu update, jak je uvedeno 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

$ 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

Získat poznámkový blok

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

Získat poznámkový blok