Azure Databricks 上的 MLflow 模型登錄 Webhook

發行項
05/06/2024

重要

Webhook 可讓您接聽模型登錄事件，讓您的整合可以自動觸發動作。您可以使用 Webhook，將機器學習管線與現有的 CI/CD 工具和工作流程自動化並整合。例如，您可以在建立新的模型版本時觸發 CI 組建，或每次要求模型轉換至生產環境時，透過 Slack 通知您的小組成員。

Webhook 可透過 Databricks REST API 或 PyPI 上的 Python 用戶端databricks-registry-webhooks取得。

注意

當您在 Unity 目錄中使用模型時，無法使用 Webhook。如需替代方案，請參閱我是否可以在事件上使用階段轉換要求或觸發 Webhook？。不支援將 Webhook 傳送至私人端點（無法從公用因特網存取的端點）。

Webhook 事件

您可以指定要在一或多個這些事件時觸發的 Webhook：

MODEL_VERSION_CREATED：已為相關聯的模型建立新的模型版本。
MODEL_VERSION_TRANSITIONED_STAGE：模型版本的階段已變更。
TRANSITION_REQUEST_CREATED：使用者要求轉換模型版本的階段。
COMMENT_CREATED：使用者已對已註冊的模型撰寫批注。
REGISTERED_MODEL_CREATED：已建立新的已註冊模型。這個事件類型只能針對整個登錄的 Webhook 指定，這可以藉由在建立要求中指定模型名稱來建立。
MODEL_VERSION_TAG_SET：用戶設定模型版本的標記。
MODEL_VERSION_TRANSITIONED_TO_STAGING：模型版本已轉換為預備版本。
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION：模型版本已轉換為生產環境。
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED：已封存模型版本。
TRANSITION_REQUEST_TO_STAGING_CREATED：使用者要求將模型版本轉換為預備版本。
TRANSITION_REQUEST_TO_PRODUCTION_CREATED：使用者要求將模型版本轉換為生產環境。
TRANSITION_REQUEST_TO_ARCHIVED_CREATED：使用者要求封存模型版本。

Webhook 的類型

根據 Webhook 的觸發目標有兩種類型：

具有 HTTP 端點的 Webhook （HTTP 登錄 Webhooks）：將觸發程式傳送至 HTTP 端點。
具有作業觸發程式的 Webhook （作業登錄 Webhooks）：在 Azure Databricks 工作區中觸發作業。如果在作業的工作區中啟用IP允許清單，您必須允許列出模型登錄的工作區IP。如需詳細資訊，請參閱作業登錄 Webhook 的 IP 允許清單。

另外還有兩種類型的 Webhook 根據其範圍，具有不同的訪問控制需求：

模型特定的 Webhook：Webhook 會套用至特定的已註冊模型。您必須擁有已註冊模型的 CAN MANAGE 許可權，才能建立、修改、刪除或測試模型特定的 Webhook。
全登錄 Webhook：Webhook 是由工作區中任何已註冊模型上的事件所觸發，包括建立新的已註冊模型。若要建立全登錄的 Webhook，請省略 model_name 建立時字段。您必須擁有工作區管理員許可權，才能建立、修改、刪除或測試全登錄的 Webhook。

Webhook 承載

每個事件觸發程式在 Webhook 端點的傳出要求承載中包含最少欄位。

排除成品路徑位置等敏感性資訊。具有適當 ACL 的使用者和主體可以使用用戶端或 REST API 來查詢模型登錄以取得這項資訊。
承載不會加密。如需如何驗證 Azure Databricks 是否為 Webhook 來源的資訊，請參閱安全性。
欄位 text 有助於 Slack 整合。若要傳送 Slack 訊息，請提供 Slack Webhook 端點作為 Webhook URL。

作業登錄 Webhook 承載

作業登錄 Webhook 的承載取決於作業類型，並傳送至 jobs/run-now 目標工作區中的端點。

單一工作作業

單一工作作業根據工作類型，有三個承載之一。

筆記本和 Python 滾輪作業

Notebook 和 Python 滾輪作業具有包含字段 event_message的參數位典的 JSON 承載。

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

Python、JAR 和 Spark 提交作業

Python、JAR 和 Spark 提交作業具有具有參數列表的 JSON 承載。

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

所有其他作業

所有其他類型的作業都有沒有參數的 JSON 承載。

{
  "job_id": 1234567890
}

多任務作業

多任務作業具有 JSON 承載，其中包含填入所有參數以考慮不同的工作類型。

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

範例承載

事件：`MODEL_VERSION_TRANSITIONED_STAGE`

回應

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

事件：`MODEL_VERSION_TAG_SET`

回應

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

事件：`COMMENT_CREATED`

回應

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

安全性

為了安全性，Azure Databricks 會在從承載計算的標頭中包含 X-Databricks-Signature，以及使用 HMAC 搭配 SHA-256 演算法與 Webhook 相關聯的共用秘密密鑰。

此外，您可以在傳出要求中包含標準授權標頭，方法是在 Webhook 的中 HttpUrlSpec 指定一個。

客戶端驗證

如果已設定共用密碼，承載收件者應該使用共用密碼來驗證 HTTP 要求的來源，以將承載編碼為 HMAC 編碼，然後將編碼的值與 X-Databricks-Signature 標頭中的比較。如果停用 SSL 憑證驗證，這特別重要（也就是說，如果 enable_ssl_verification 字段設定為 false）。

注意

enable_ssl_verification 預設為 true。對於自我簽署憑證，此字段必須是 false，而且目的地伺服器必須停用憑證驗證。

基於安全性考慮，Databricks 建議您使用承載的 HMAC 編碼部分執行秘密驗證。如果您停用主機名驗證，會增加要求可能會惡意路由傳送至非預期主機的風險。

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

HTTP 登錄 Webhook 的授權標頭

如果已設定 Authorization 標頭，客戶端應該藉由驗證 Authorization 標頭中的持有人令牌或授權認證來驗證 HTTP 要求的來源。

作業登錄 Webhook 的 IP 允許清單

若要使用觸發作業的 Webhook 會在已啟用 IP 允許清單的不同工作區中執行，您必須允許列出 Webhook 所在的區域 NAT IP，才能接受傳入要求。

如果 Webhook 和作業位於相同的工作區中，您就不需要將任何 IP 新增至允許清單。

如果您的作業位於 Azure 多租用戶區域，請參閱 Azure Databricks 控制平面位址。針對所有其他區域，請連絡您的帳戶小組，以識別您需要允許清單的IP。

稽核記錄

如果已啟用工作區的稽核記錄，稽核記錄中會包含下列事件：

建立 webhook
更新 Webhook
列出 Webhook
刪除 Webhook
測試 Webhook
Webhook 觸發程序

Webhook 觸發程式稽核記錄

對於具有 HTTP 端點的 Webhook，系統會記錄傳送至 Webhook 所指定 URL 的 HTTP 要求，以及 URL 和 enable_ssl_verification 值。

針對具有作業觸發程式的 Webhook， job_id 會記錄和 workspace_url 值。

範例

本節包含：

HTTP 登錄 Webhook 工作流程範例。
作業登錄 Webhook 工作流程範例。
列出 Webhook 範例。
兩個範例筆記本：一個說明 REST API，另一個說明 Python 用戶端。

HTTP 登錄 Webhook 範例工作流程

1.建立 Webhook

當 HTTPS 端點準備好接收 Webhook 事件要求時，您可以使用 Webhooks Databricks REST API 來建立 Webhook。例如，Webhook 的 URL 可以指向 Slack，將訊息張貼至通道。

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

回應

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

您也可以使用 Databricks Terraform 提供者和 databricks_mlflow_webhook建立 HTTP 登錄 Webhook。

2.測試 Webhook

先前的 Webhook 是在中 TEST_MODE建立，因此可以觸發模擬事件以將要求傳送至指定的 URL。不過，Webhook 不會在實際事件上觸發。測試端點會從指定的 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"
)

回應

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

3.將 Webhook 更新為作用中狀態

若要啟用真實事件的 Webhook，請透過更新呼叫將其狀態 ACTIVE 設定為，這也可用來變更其任何其他屬性。

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

回應

{"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.刪除 Webhook

若要停用 Webhook，請將其狀態設定為 DISABLED （如上所示使用類似的更新命令），或刪除它。

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

回應

{}

作業登錄 Webhook 範例工作流程

管理作業登錄 Webhook 的工作流程類似於 HTTP 登錄 Webhook，唯一的差異在於 job_spec 取代欄位的 http_url_spec 欄位。

使用 Webhook，您可以觸發相同工作區或不同工作區中的作業。工作區是使用選擇性參數 workspace_url來指定。 workspace_url如果沒有，默認行為就是在與 Webhook 相同的工作區中觸發作業。

需求

現有的作業。
個人存取令牌。請注意，存取令牌不會包含在 API 所傳回的 Webhook 物件中。

注意

作為安全性最佳做法，當您使用自動化工具、系統、腳本和應用程式進行驗證時，Databricks 建議您使用屬於服務主體的個人存取令牌，而不是工作區使用者。若要建立服務主體的令牌，請參閱管理服務主體的令牌。

建立作業登錄 Webhook

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

回應

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

您也可以使用 Databricks Terraform 提供者和 databricks_mlflow_webhook來建立作業登錄 Webhook。

列出登錄 Webhook 範例

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

回應

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

共用方式為

Azure Databricks 上的 MLflow 模型登錄 Webhook

Webhook 事件

Webhook 的類型

Webhook 承載

作業登錄 Webhook 承載

單一工作作業

筆記本和 Python 滾輪作業

Python、JAR 和 Spark 提交作業

所有其他作業

多任務作業

範例承載

事件：`MODEL_VERSION_TRANSITIONED_STAGE`

事件：`MODEL_VERSION_TAG_SET`

事件：`COMMENT_CREATED`

安全性

客戶端驗證

HTTP 登錄 Webhook 的授權標頭

作業登錄 Webhook 的 IP 允許清單

稽核記錄

Webhook 觸發程式稽核記錄

範例

HTTP 登錄 Webhook 範例工作流程

1.建立 Webhook

2.測試 Webhook

3.將 Webhook 更新為作用中狀態

4.刪除 Webhook

作業登錄 Webhook 範例工作流程

需求

建立作業登錄 Webhook

列出登錄 Webhook 範例

Notebooks

MLflow 模型登錄 Webhook REST API 範例筆記本

MLflow 模型登錄 Webhooks Python 用戶端範例筆記本

意見反應

意見反應

其他資源

共用方式為

Azure Databricks 上的 MLflow 模型登錄 Webhook

Webhook 事件

Webhook 的類型

Webhook 承載

作業登錄 Webhook 承載

單一工作作業

筆記本和 Python 滾輪作業

Python、JAR 和 Spark 提交作業

所有其他作業

多任務作業

範例承載

事件：MODEL_VERSION_TRANSITIONED_STAGE

事件：MODEL_VERSION_TAG_SET

事件：COMMENT_CREATED

安全性

客戶端驗證

HTTP 登錄 Webhook 的授權標頭

作業登錄 Webhook 的 IP 允許清單

稽核記錄

Webhook 觸發程式稽核記錄

範例

HTTP 登錄 Webhook 範例工作流程

1.建立 Webhook

2.測試 Webhook

3.將 Webhook 更新為作用中狀態

4.刪除 Webhook

作業登錄 Webhook 範例工作流程

需求

建立作業登錄 Webhook

列出登錄 Webhook 範例

Notebooks

MLflow 模型登錄 Webhook REST API 範例筆記本

MLflow 模型登錄 Webhooks Python 用戶端範例筆記本

意見反應

意見反應

其他資源

事件：`MODEL_VERSION_TRANSITIONED_STAGE`

事件：`MODEL_VERSION_TAG_SET`

事件：`COMMENT_CREATED`