Rejestr modeli w przestrzeni roboczej: webhooks

Artykuł
12/11/2024

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

Webhooki umożliwiają nasłuchiwanie zdarzeń z Rejestru modelu obszaru roboczego, co pozwala integracjom automatycznie wyzwalać akcje. Za pomocą elementów webhook można zautomatyzować i zintegrować potok uczenia maszynowego z istniejącymi narzędziami i przepływami pracy ciągłej integracji/ciągłego wdrażania. Możesz na przykład wyzwolić kompilacje ciągłej integracji po utworzeniu nowej wersji modelu lub powiadomić członków zespołu za pomocą usługi Slack za każdym razem, gdy wymagane jest przejście modelu do środowiska produkcyjnego.

Elementy webhook są dostępne za pośrednictwem interfejsu API REST usługi Databricks lub klienta databricks-registry-webhooks języka Python w interfejsie PyPI.

Uwaga

Elementy webhook nie są dostępne w przypadku korzystania z modeli w wykazie aparatu Unity. Aby uzyskać alternatywę, zobacz Czy mogę używać żądań przejścia etapu lub wyzwalać elementy webhook w zdarzeniach?. Wysyłanie elementów webhook do prywatnych punktów końcowych (punktów końcowych, które nie są dostępne z publicznego Internetu) nie jest obsługiwane.

Zdarzenia elementu webhook

Można określić element webhook, który ma być wyzwalany na co najmniej jednym z następujących zdarzeń:

MODEL_VERSION_CREATED: utworzono nową wersję modelu dla skojarzonego modelu.
MODEL_VERSION_TRANSITIONED_STAGE: Etap wersji modelu został zmieniony.
TRANSITION_REQUEST_CREATED: Użytkownik zażądał przejścia etapu wersji modelu.
COMMENT_CREATED: Użytkownik napisał komentarz do zarejestrowanego modelu.
REGISTERED_MODEL_CREATED: utworzono nowy zarejestrowany model. Ten typ zdarzenia można określić tylko dla elementu webhook dla całego rejestru, który można utworzyć, nie określając nazwy modelu w żądaniu tworzenia.
MODEL_VERSION_TAG_SET: użytkownik ustawił tag w wersji modelu.
MODEL_VERSION_TRANSITIONED_TO_STAGING: wersja modelu została przeniesiona do przemieszczania.
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: wersja modelu została przeniesiona do środowiska produkcyjnego.
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Zarchiwizowano wersję modelu.
TRANSITION_REQUEST_TO_STAGING_CREATED: Użytkownik zażądał przejścia wersji modelu do przejściowego.
TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Użytkownik zażądał przejścia wersji modelu do środowiska produkcyjnego.
TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Użytkownik zażądał zarchiwizowanej wersji modelu.

Typy elementów webhook

Istnieją dwa typy elementów webhook na podstawie ich elementów docelowych wyzwalacza:

Elementy webhook z punktami końcowymi HTTP (elementy webhook rejestru HTTP): wysyłanie wyzwalaczy do punktu końcowego HTTP.
Elementy webhook z wyzwalaczami zadań (elementy webhook rejestru zadań): wyzwalanie zadania w obszarze roboczym usługi Azure Databricks. Jeśli lista dozwolonych adresów IP jest włączona w obszarze roboczym zadania, musisz dodać adresy IP obszaru roboczego rejestru modeli. Aby uzyskać więcej informacji, zobacz temat Allowlisting for job registry webhooks (Lista dozwolonych adresów IP dla elementów webhook rejestru zadań).

Istnieją również dwa typy elementów webhook na podstawie ich zakresu, z różnymi wymaganiami dotyczącymi kontroli dostępu:

Elementy webhook specyficzne dla modelu: element webhook ma zastosowanie do określonego zarejestrowanego modelu. Aby tworzyć, modyfikować, usuwać lub testować elementy webhook specyficzne dla modelu, musisz mieć uprawnienia CAN MANAGE.
Elementy webhook obejmujące rejestr: element webhook jest wyzwalany przez zdarzenia w dowolnym zarejestrowanym modelu w obszarze roboczym, w tym tworzenie nowego zarejestrowanego modelu. Aby utworzyć element webhook obejmujący rejestr, pomiń model_name pole podczas tworzenia. Musisz mieć uprawnienia administratora obszaru roboczego do tworzenia, modyfikowania, usuwania lub testowania elementów webhook obejmujących rejestr.

Ładunek elementu webhook

Każdy wyzwalacz zdarzenia zawiera minimalne pola zawarte w ładunku dla żądania wychodzącego do punktu końcowego elementu webhook.

Informacje poufne, takie jak lokalizacja ścieżki artefaktu, są wykluczone. Użytkownicy i podmioty z odpowiednimi listami ACL mogą używać interfejsów API KLIENTA lub REST do wykonywania zapytań dotyczących rejestru modeli w celu uzyskania tych informacji.
Ładunki nie są szyfrowane. Zobacz Zabezpieczenia , aby uzyskać informacje na temat sprawdzania, czy usługa Azure Databricks jest źródłem elementu webhook.
Pole text ułatwia integrację z usługą Slack. Aby wysłać komunikat usługi Slack, podaj punkt końcowy elementu webhook usługi Slack jako adres URL elementu webhook.

Ładunek elementu webhook rejestru zadań

Ładunek elementu webhook rejestru zadań zależy od typu zadania i jest wysyłany do jobs/run-now punktu końcowego w docelowym obszarze roboczym.

Zadania pojedynczego zadania

Zadania pojedynczego zadania mają jeden z trzech ładunków na podstawie typu zadania.

Notes i zadania kółka języka Python

Zadania notesu i koła języka Python mają ładunek JSON ze słownikiem parametrów zawierającym pole event_message.

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

Zadania Python, JAR i Spark Submit

Zadania przesyłania języków Python, JAR i Spark mają ładunek JSON z listą parametrów.

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

Wszystkie inne zadania

Wszystkie inne typy zadań mają ładunek JSON bez parametrów.

{
  "job_id": 1234567890
}

Zadania wielozdaniowe

Zadania wielozadaniowe mają ładunek JSON ze wszystkimi parametrami wypełnionymi do konta dla różnych typów zadań.

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

Przykładowe ładunki

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

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

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

Zabezpieczenia

W przypadku zabezpieczeń usługa Azure Databricks zawiera element X-Databricks-Signature w nagłówku obliczonym z ładunku oraz wspólny klucz tajny skojarzony z elementem webhook przy użyciu algorytmu HMAC z algorytmem SHA-256.

Ponadto możesz uwzględnić standardowy nagłówek autoryzacji w żądaniu wychodzącym, określając jeden w HttpUrlSpec elemecie webhook.

Weryfikacja klienta

Jeśli udostępniony wpis tajny jest ustawiony, odbiorca ładunku powinien zweryfikować źródło żądania HTTP przy użyciu wspólnego wpisu tajnego do kodowania ładunku HMAC,a następnie porównywać zakodowaną wartość z X-Databricks-Signature nagłówka. Jest to szczególnie ważne, jeśli walidacja certyfikatu SSL jest wyłączona (oznacza to, że jeśli enable_ssl_verification pole jest ustawione na falsewartość ).

Uwaga

enable_ssl_verification jest true domyślnie. W przypadku certyfikatów z podpisem własnym to pole musi mieć falsewartość , a serwer docelowy musi wyłączyć walidację certyfikatu.

Ze względów bezpieczeństwa usługa Databricks zaleca przeprowadzenie weryfikacji wpisu tajnego z zakodowaną w formacie HMAC częścią ładunku. Jeśli wyłączysz walidację nazwy hosta, zwiększysz ryzyko złośliwego przekierowania żądania do niezamierzonego hosta.

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

Nagłówek autoryzacji dla elementów webhook rejestru HTTP

Jeśli ustawiono nagłówek autoryzacji, klienci powinni zweryfikować źródło żądania HTTP, sprawdzając token elementu nośnego lub poświadczenia autoryzacji w nagłówku Autoryzacja.

Lista dozwolonych adresów IP dla elementów webhook rejestru zadań

Aby użyć elementu webhook, który wyzwala zadanie jest uruchamiane w innym obszarze roboczym z włączoną listą dozwolonych adresów IP, musisz zezwolić na listę adresów IP translatora adresów sieciowych w regionie, w którym znajduje się element webhook, aby akceptować żądania przychodzące.

Jeśli element webhook i zadanie znajdują się w tym samym obszarze roboczym, nie musisz dodawać żadnych adresów IP do listy dozwolonych.

Jeśli zadanie znajduje się w regionie wielodostępnym platformy Azure, zobacz Adresy płaszczyzny sterowania usługi Azure Databricks. W przypadku wszystkich innych regionów skontaktuj się z zespołem ds. kont, aby zidentyfikować adresy IP, które należy zezwolić na listę.

Rejestrowanie inspekcji

Jeśli rejestrowanie inspekcji jest włączone dla obszaru roboczego, w dziennikach inspekcji znajdują się następujące zdarzenia:

Utwórz element webhook
Aktualizowanie elementu webhook
Wyświetlanie listy elementów webhook
Usuwanie elementu webhook
Testowanie elementu webhook
Wyzwalacz elementu webhook

Rejestrowanie inspekcji wyzwalacza elementu webhook

W przypadku elementów webhook z punktami końcowymi HTTP żądanie HTTP wysyłane do adresu URL określonego dla elementu webhook wraz z adresem URL i enable_ssl_verification wartościami są rejestrowane.

W przypadku elementów webhook z wyzwalaczami job_id zadań wartości i workspace_url są rejestrowane.

Przykłady

Ta część zawiera:

Przykład przepływu pracy elementu webhook rejestru HTTP.
Przykład przepływu pracy elementu webhook rejestru zadań.
przykład elementów webhook listy.
dwa przykładowe notesy: jeden ilustrujący interfejs API REST i jeden ilustrujący klienta języka Python.

Przykładowy przepływ pracy elementu webhook rejestru HTTP

1. Tworzenie elementu webhook

Gdy punkt końcowy HTTPS jest gotowy do odbierania żądania zdarzenia elementu webhook, możesz utworzyć element webhook przy użyciu interfejsu API REST usługi Databricks elementów webhook. Na przykład adres URL elementu webhook może wskazywać usługę Slack, aby publikować komunikaty w kanale.

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

Możesz również utworzyć element webhook rejestru HTTP przy użyciu dostawcy narzędzia Terraform usługi Databricks i databricks_mlflow_webhook.

2. Testowanie elementu webhook

Poprzedni element webhook został utworzony w TEST_MODEelemecie , więc można wyzwolić pozorne zdarzenie w celu wysłania żądania do określonego adresu URL. Jednak element webhook nie jest wyzwalany w rzeczywistym zdarzeniu. Testowy punkt końcowy zwraca otrzymany kod stanu i treść z określonego adresu 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. Zaktualizuj element webhook do stanu aktywnego

Aby włączyć element webhook dla rzeczywistych zdarzeń, ustaw jego stan na ACTIVE za pomocą wywołania aktualizacji, którego można również użyć do zmiany dowolnej z jego innych właściwości.

$ 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. Usuwanie elementu webhook

Aby wyłączyć element webhook, ustaw jego stan na DISABLED (używając podobnego polecenia aktualizacji, jak powyżej), lub usuń go.

$ 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

{}

Przykładowy przepływ pracy elementu webhook rejestru zadań

Przepływ pracy zarządzania elementami webhook rejestru zadań jest podobny do elementów webhook rejestru HTTP, a jedyną różnicą jest job_spec pole, które zastępuje http_url_spec pole.

Za pomocą elementów webhook można wyzwalać zadania w tym samym obszarze roboczym lub w innym obszarze roboczym. Obszar roboczy jest określany przy użyciu opcjonalnego parametru workspace_url. Jeśli nie workspace_url ma, domyślne zachowanie polega na wyzwoleniu zadania w tym samym obszarze roboczym co element webhook.

Wymagania

Istniejące zadanie.
Osobisty token dostępu. Należy pamiętać, że tokeny dostępu mogą być odczytywane tylko przez usługę MLflow i nie mogą być zwracane przez użytkowników usługi Azure Databricks w interfejsie API rejestru modeli.

Uwaga

Najlepszym rozwiązaniem w zakresie zabezpieczeń w przypadku uwierzytelniania za pomocą zautomatyzowanych narzędzi, systemów, skryptów i aplikacji usługa Databricks zaleca używanie osobistych tokenów dostępu należących do jednostek usługi zamiast użytkowników obszaru roboczego. Aby utworzyć tokeny dla jednostek usługi, zobacz Zarządzanie tokenami dla jednostki usługi.

Tworzenie elementu webhook rejestru zadań

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

Możesz również utworzyć element webhook rejestru zadań za pomocą dostawcy narzędzia Terraform usługi Databricks i databricks_mlflow_webhook.

Przykład elementów webhook rejestru

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

Udostępnij za pośrednictwem

Rejestr modeli w przestrzeni roboczej: webhooks

Zdarzenia elementu webhook

Typy elementów webhook

Ładunek elementu webhook

Ładunek elementu webhook rejestru zadań

Zadania pojedynczego zadania

Notes i zadania kółka języka Python

Zadania Python, JAR i Spark Submit

Wszystkie inne zadania

Zadania wielozdaniowe

Przykładowe ładunki

zdarzenie: `MODEL_VERSION_TRANSITIONED_STAGE`

zdarzenie: `MODEL_VERSION_TAG_SET`

zdarzenie: `COMMENT_CREATED`

Zabezpieczenia

Weryfikacja klienta

Nagłówek autoryzacji dla elementów webhook rejestru HTTP

Lista dozwolonych adresów IP dla elementów webhook rejestru zadań

Rejestrowanie inspekcji

Rejestrowanie inspekcji wyzwalacza elementu webhook

Przykłady

Przykładowy przepływ pracy elementu webhook rejestru HTTP

1. Tworzenie elementu webhook

2. Testowanie elementu webhook

3. Zaktualizuj element webhook do stanu aktywnego

4. Usuwanie elementu webhook

Przykładowy przepływ pracy elementu webhook rejestru zadań

Wymagania

Tworzenie elementu webhook rejestru zadań

Przykład elementów webhook rejestru

Notesy

Przykładowy notes interfejsu API REST rejestru modeli MLflow

Przykładowy notes klienta języka Python rejestru modeli MLflow

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Rejestr modeli w przestrzeni roboczej: webhooks

Zdarzenia elementu webhook

Typy elementów webhook

Ładunek elementu webhook

Ładunek elementu webhook rejestru zadań

Zadania pojedynczego zadania

Notes i zadania kółka języka Python

Zadania Python, JAR i Spark Submit

Wszystkie inne zadania

Zadania wielozdaniowe

Przykładowe ładunki

zdarzenie: MODEL_VERSION_TRANSITIONED_STAGE

zdarzenie: MODEL_VERSION_TAG_SET

zdarzenie: COMMENT_CREATED

Zabezpieczenia

Weryfikacja klienta

Nagłówek autoryzacji dla elementów webhook rejestru HTTP

Lista dozwolonych adresów IP dla elementów webhook rejestru zadań

Rejestrowanie inspekcji

Rejestrowanie inspekcji wyzwalacza elementu webhook

Przykłady

Przykładowy przepływ pracy elementu webhook rejestru HTTP

1. Tworzenie elementu webhook

2. Testowanie elementu webhook

3. Zaktualizuj element webhook do stanu aktywnego

4. Usuwanie elementu webhook

Przykładowy przepływ pracy elementu webhook rejestru zadań

Wymagania

Tworzenie elementu webhook rejestru zadań

Przykład elementów webhook rejestru

Notesy

Przykładowy notes interfejsu API REST rejestru modeli MLflow

Przykładowy notes klienta języka Python rejestru modeli MLflow

Opinia

Dodatkowe zasoby

zdarzenie: `MODEL_VERSION_TRANSITIONED_STAGE`

zdarzenie: `MODEL_VERSION_TAG_SET`

zdarzenie: `COMMENT_CREATED`