Webhook del Registro modelli MLflow in Azure Databricks

Articolo
05/06/2024

Importante

Questa funzionalità è disponibile in anteprima pubblica.

I webhook consentono di restare in ascolto degli eventi del Registro modelli in modo che le integrazioni possano attivare automaticamente le azioni. È possibile usare webhook per automatizzare e integrare la pipeline di Machine Learning con gli strumenti e i flussi di lavoro CI/CD esistenti. Ad esempio, è possibile attivare compilazioni CI quando viene creata una nuova versione del modello o inviare una notifica ai membri del team tramite Slack ogni volta che viene richiesta una transizione del modello alla produzione.

I webhook sono disponibili tramite l'API REST di Databricks o il client databricks-registry-webhooks Python in PyPI.

Nota

I webhook non sono disponibili quando si usano modelli nel catalogo unity. Per un'alternativa, vedere È possibile usare le richieste di transizione di fase o attivare webhook negli eventi? L'invio di webhook a endpoint privati (endpoint non accessibili da Internet pubblico) non è supportato.

Eventi del webhook

È possibile specificare un webhook da attivare su uno o più di questi eventi:

MODEL_VERSION_CREATED: è stata creata una nuova versione del modello per il modello associato.
MODEL_VERSION_TRANSITIONED_STAGE: la fase di una versione del modello è stata modificata.
TRANSITION_REQUEST_CREATED: un utente ha richiesto la transizione della fase di una versione del modello.
COMMENT_CREATED: un utente ha scritto un commento su un modello registrato.
REGISTERED_MODEL_CREATED: è stato creato un nuovo modello registrato. Questo tipo di evento può essere specificato solo per un webhook a livello di Registro di sistema, che può essere creato non specificando un nome di modello nella richiesta di creazione.
MODEL_VERSION_TAG_edizione Standard T: un utente imposta un tag nella versione del modello.
MODEL_VERSION_TRANSITIONED_TO_STAGING: è stata eseguita la transizione di una versione del modello alla gestione temporanea.
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: è stata eseguita la transizione di una versione del modello all'ambiente di produzione.
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: è stata archiviata una versione del modello.
TRANSITION_REQUEST_TO_STAGING_CREATED: un utente ha richiesto la transizione di una versione del modello alla gestione temporanea.
TRANSITION_REQUEST_TO_PRODUCTION_CREATED: un utente ha richiesto la transizione di una versione del modello all'ambiente di produzione.
TRANSITION_REQUEST_TO_ARCHIVED_CREATED: un utente ha richiesto l'archiviazione di una versione del modello.

Tipi di webhook

Esistono due tipi di webhook in base alle destinazioni del trigger:

Webhook con endpoint HTTP (webhook del Registro di sistema HTTP): inviare trigger a un endpoint HTTP.
Webhook con trigger di processo (webhook del registro processi): attivare un processo in un'area di lavoro di Azure Databricks. Se l'elenco di indirizzi IP consentiti è abilitato nell'area di lavoro del processo, è necessario consentire gli INDIRIZZI IP dell'area di lavoro del Registro modelli. Per altre informazioni, vedere Elenco di indirizzi IP consentiti per i webhook del Registro di sistema dei processi .

Esistono anche due tipi di webhook in base al relativo ambito, con requisiti di controllo di accesso diversi:

Webhook specifici del modello: il webhook si applica a un modello registrato specifico. È necessario disporre delle autorizzazioni CAN MANAGE per il modello registrato per creare, modificare, eliminare o testare webhook specifici del modello.
Webhook a livello di Registro di sistema: il webhook viene attivato da eventi in qualsiasi modello registrato nell'area di lavoro, inclusa la creazione di un nuovo modello registrato. Per creare un webhook a livello di Registro di sistema, omettere il campo alla model_name creazione. È necessario disporre delle autorizzazioni di amministratore dell'area di lavoro per creare, modificare, eliminare o testare webhook a livello di registro.

Payload del webhook

Ogni trigger di evento ha campi minimi inclusi nel payload per la richiesta in uscita all'endpoint del webhook.

Le informazioni riservate, ad esempio la posizione del percorso dell'artefatto, vengono escluse. Gli utenti e le entità con ACL appropriati possono usare API REST o client per eseguire query nel Registro modelli per ottenere queste informazioni.
I payload non sono crittografati. Vedere Sicurezza per informazioni su come verificare che Azure Databricks sia l'origine del webhook.
Il text campo facilita l'integrazione di Slack. Per inviare un messaggio Slack, specificare un endpoint webhook Slack come URL del webhook.

Payload del webhook del Registro di sistema dei processi

Il payload per un webhook del Registro di sistema dei processi dipende dal tipo di processo e viene inviato all'endpoint nell'area jobs/run-now di lavoro di destinazione.

Processi a singola attività

I processi a singola attività hanno uno dei tre payload in base al tipo di attività.

Processi con rotellina python e notebook

I processi del notebook e della rotellina Python hanno un payload JSON con un dizionario di parametri che contiene un campo event_message.

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

Processi Python, JAR e Spark Submit

I processi di invio python, JAR e Spark hanno un payload JSON con un elenco di parametri.

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

Tutti gli altri processi

Tutti gli altri tipi di processi hanno un payload JSON senza parametri.

{
  "job_id": 1234567890
}

Processi con più attività

I processi con più attività hanno un payload JSON con tutti i parametri popolati per tenere conto di diversi tipi di attività.

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

Payload di esempio

evento: `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."
}

evento: `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."
}

evento: `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."
}

Sicurezza

Per la sicurezza, Azure Databricks include la firma X-Databricks nell'intestazione calcolata dal payload e la chiave privata condivisa associata al webhook usando HMAC con l'algoritmo SHA-256.

Inoltre, è possibile includere un'intestazione di autorizzazione standard nella richiesta in uscita specificandone una nel HttpUrlSpec webhook.

Verifica client

Se viene impostato un segreto condiviso, il destinatario del payload deve verificare l'origine della richiesta HTTP usando il segreto condiviso per codificare HMAC il payload e quindi confrontare il valore codificato con l'intestazione X-Databricks-Signature . Ciò è particolarmente importante se la convalida del certificato SSL è disabilitata, ovvero se il enable_ssl_verification campo è impostato su false.

Nota

enable_ssl_verification è true per impostazione predefinita. Per i certificati autofirmato, questo campo deve essere falsee il server di destinazione deve disabilitare la convalida del certificato.

Per motivi di sicurezza, Databricks consiglia di eseguire la convalida dei segreti con la parte con codifica HMAC del payload. Se si disabilita la convalida del nome host, si aumenta il rischio che una richiesta possa essere indirizzata in modo dannoso a un host imprevisto.

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

Intestazione di autorizzazione per i webhook del Registro di sistema HTTP

Se è impostata un'intestazione di autorizzazione, i client devono verificare l'origine della richiesta HTTP verificando il token di connessione o le credenziali di autorizzazione nell'intestazione Autorizzazione.

Elenco indirizzi IP consentiti per i webhook del Registro di sistema dei processi

Per usare un webhook che attiva l'esecuzione del processo in un'area di lavoro diversa con ip allowlist abilitato, è necessario consentire l'elenco dell'indirizzo IP NAT dell'area in cui si trova il webhook per accettare le richieste in ingresso.

Se il webhook e il processo si trovano nella stessa area di lavoro, non è necessario aggiungere indirizzi IP all'elenco elementi consentiti.

Se il processo si trova in un'area multi-tenant di Azure, vedere Indirizzi del piano di controllo di Azure Databricks. Per tutte le altre aree, contattare il team dell'account per identificare gli indirizzi IP da consentire.

Registrazione del controllo

Se la registrazione di controllo è abilitata per l'area di lavoro, i log di controllo includono gli eventi seguenti:

Crea webhook
Aggiornare il webhook
Elencare il webhook
Eliminare un webhook
Testare un webhook
Trigger webhook

Registrazione controllo trigger webhook

Per i webhook con endpoint HTTP, viene registrata la richiesta HTTP inviata all'URL specificato per il webhook insieme all'URL e enable_ssl_verification ai valori.

Per i webhook con trigger di processo, vengono registrati i job_id valori e workspace_url .

Esempi

La sezione include:

Esempio di flusso di lavoro webhook del Registro di sistema HTTP.
Esempio di flusso di lavoro webhook del registro processi.
esempio di webhook di elenco.
due notebook di esempio: uno che illustra l'API REST e uno che illustra il client Python.

Flusso di lavoro di esempio del webhook del Registro di sistema HTTP

1. Creare un webhook

Quando un endpoint HTTPS è pronto per ricevere la richiesta di evento webhook, è possibile creare un webhook usando l'API REST databricks webhooks. Ad esempio, l'URL del webhook può puntare a Slack per pubblicare messaggi in un canale.

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

È anche possibile creare un webhook del Registro di sistema HTTP con il provider Databricks Terraform e databricks_mlflow_webhook.

2. Testare il webhook

Il webhook precedente è stato creato in TEST_MODE, quindi è possibile attivare un evento fittizio per inviare una richiesta all'URL specificato. Tuttavia, il webhook non viene attivato in un evento reale. L'endpoint di test restituisce il codice di stato ricevuto e il corpo dall'URL specificato.

$ 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. Aggiornare il webhook allo stato attivo

Per abilitare il webhook per gli eventi reali, impostarne lo stato ACTIVE su tramite una chiamata di aggiornamento, che può essere usata anche per modificare qualsiasi altra proprietà.

$ 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. Eliminare il webhook

Per disabilitare il webhook, impostarne lo stato DISABLED su (usando un comando di aggiornamento simile a quello precedente) o eliminarlo.

$ 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

{}

Flusso di lavoro di esempio del webhook del Registro di sistema dei processi

Il flusso di lavoro per la gestione dei webhook del Registro di sistema dei processi è simile ai webhook del Registro di sistema HTTP, con l'unica differenza che è il job_spec campo che sostituisce il http_url_spec campo.

Con i webhook è possibile attivare processi nella stessa area di lavoro o in un'area di lavoro diversa. L'area di lavoro viene specificata usando il parametro workspace_urlfacoltativo . Se non workspace_url è presente, il comportamento predefinito consiste nell'attivare un processo nella stessa area di lavoro del webhook.

Requisiti

Processo esistente.
Token di accesso personale. Si noti che i token di accesso non sono inclusi nell'oggetto webhook restituito dalle API.

Nota

Come procedura consigliata per la sicurezza, quando si esegue l'autenticazione con strumenti automatizzati, sistemi, script e app, Databricks consiglia di usare token di accesso personali appartenenti alle entità servizio anziché agli utenti dell'area di lavoro. Per creare token per le entità servizio, vedere Gestire i token per un'entità servizio.

Creare un webhook del Registro di sistema dei processi

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

È anche possibile creare un webhook del Registro di sistema dei processi con il provider Databricks Terraform e databricks_mlflow_webhook.

Esempio di webhook del Registro di sistema

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

Condividi tramite

Webhook del Registro modelli MLflow in Azure Databricks

Eventi del webhook

Tipi di webhook

Payload del webhook

Payload del webhook del Registro di sistema dei processi

Processi a singola attività

Processi con rotellina python e notebook

Processi Python, JAR e Spark Submit

Tutti gli altri processi

Processi con più attività

Payload di esempio

evento: `MODEL_VERSION_TRANSITIONED_STAGE`

evento: `MODEL_VERSION_TAG_SET`

evento: `COMMENT_CREATED`

Sicurezza

Verifica client

Intestazione di autorizzazione per i webhook del Registro di sistema HTTP

Elenco indirizzi IP consentiti per i webhook del Registro di sistema dei processi

Registrazione del controllo

Registrazione controllo trigger webhook

Esempi

Flusso di lavoro di esempio del webhook del Registro di sistema HTTP

1. Creare un webhook

2. Testare il webhook

3. Aggiornare il webhook allo stato attivo

4. Eliminare il webhook

Flusso di lavoro di esempio del webhook del Registro di sistema dei processi

Requisiti

Creare un webhook del Registro di sistema dei processi

Esempio di webhook del Registro di sistema

Notebook

Notebook di esempio dell'API REST del Registro modelli MLflow

Notebook di esempio del client Python per webhook del Registro modelli MLflow

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Webhook del Registro modelli MLflow in Azure Databricks

Eventi del webhook

Tipi di webhook

Payload del webhook

Payload del webhook del Registro di sistema dei processi

Processi a singola attività

Processi con rotellina python e notebook

Processi Python, JAR e Spark Submit

Tutti gli altri processi

Processi con più attività

Payload di esempio

evento: MODEL_VERSION_TRANSITIONED_STAGE

evento: MODEL_VERSION_TAG_SET

evento: COMMENT_CREATED

Sicurezza

Verifica client

Intestazione di autorizzazione per i webhook del Registro di sistema HTTP

Elenco indirizzi IP consentiti per i webhook del Registro di sistema dei processi

Registrazione del controllo

Registrazione controllo trigger webhook

Esempi

Flusso di lavoro di esempio del webhook del Registro di sistema HTTP

1. Creare un webhook

2. Testare il webhook

3. Aggiornare il webhook allo stato attivo

4. Eliminare il webhook

Flusso di lavoro di esempio del webhook del Registro di sistema dei processi

Requisiti

Creare un webhook del Registro di sistema dei processi

Esempio di webhook del Registro di sistema

Notebook

Notebook di esempio dell'API REST del Registro modelli MLflow

Notebook di esempio del client Python per webhook del Registro modelli MLflow

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

evento: `MODEL_VERSION_TRANSITIONED_STAGE`

evento: `MODEL_VERSION_TAG_SET`

evento: `COMMENT_CREATED`