Elementy webhook rejestru modeli MLflow w usłudze Azure Databricks
Ważne
Ta funkcja jest dostępna w publicznej wersji zapoznawczej.
Elementy webhook umożliwiają nasłuchiwanie zdarzeń rejestru modeli, dzięki czemu integracje mogą 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_namepole 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
textuł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 nie są uwzględniane w obiekcie elementu webhook zwracanym przez interfejsy API.
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"
}}]}
Notesy
Przykładowy notes interfejsu API REST rejestru modeli MLflow
Przykładowy notes klienta języka Python rejestru modeli MLflow
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla