MLflow模型注册表Webhooks在Databricks

预览

此功能已在公共预览．

webhook允许您监听Model Registry事件，这样您的集成就可以自动触发操作。您可以使用webhooks自动化并将您的机器学习管道与现有的CI/CD工具和工作流集成在一起。例如，您可以在创建新模型版本时触发CI构建，或者在每次请求模型转换到生产时通过Slack通知您的团队成员。

webhook可通过数据库REST API或Python客户端databricks-registry-webhooks在PyPI．

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:

  • 带有HTTP端点的webhook (HTTP注册表webhook):向HTTP端点发送触发器。

  • 带作业触发器的网络钩子(作业注册表网络钩子):在Databricks工作区中触发一个作业。如果在作业的工作空间中启用了IP allowlisting，则必须列出模型注册中心的工作空间IP。看到作业注册网络钩子的IP allowlisting获取更多信息。

也有两种类型的webhook基于他们的作用域，有不同的访问控制要求:

  • 模型相关的人: webhook应用于特定的注册模型。你一定有可以管理注册模型上创建、修改、删除或测试模型特定webhook的权限。

  • Registry-wide人: webhook由工作区中任何注册模型上的事件触发，包括创建一个新的注册模型。要创建注册表范围的webhook，请省略model_name创建时的字段。您必须具有工作区管理权限才能创建、修改、删除或测试注册中心范围内的webhook。

Webhook载荷

每个事件触发器在发送到webhook端点的外发请求的有效负载中包含最小的字段。

  • 敏感信息如工件路径位置被排除在外。具有适当acl的用户和主体可以使用客户机或REST api查询Model Registry以获得此信息。

  • 有效载荷不加密。看到安全有关如何验证Databricks是webhook的来源的信息。

  • 的文本字段有助于Slack的集成。要发送Slack消息，提供一个Slack webhook端点作为webhook URL。

作业注册表webhook有效负载

作业注册webhook的有效负载取决于作业的类型，并被发送到工作/运行目标工作区中的端点。

单一任务的工作

单任务作业根据任务类型有三种有效负载之一。

笔记本和Python轮毂工作

Notebook和Python轮式作业有一个带有包含字段的参数字典的JSON有效负载event_message．

｛“job_id”：1234567890，“notebook_params”：｛“event_message”：“< Webhook载荷>”｝｝
Python、JAR和Spark Submit任务

Python、JAR和Spark提交作业都有一个带有参数列表的JSON有效负载。

｛“job_id”：1234567890，“python_params”：［“< Webhook载荷>”］｝
所有其他工作

所有其他类型的作业都有一个不带参数的JSON有效负载。

｛“job_id”：1234567890｝

多任务工作

多任务作业有一个JSON有效负载，其中填充了所有参数，以考虑不同的任务类型。

｛“job_id”：1234567890，“notebook_params”：｛“event_message”：“< Webhook载荷>”}，“python_named_params”：｛“event_message”：“< Webhook载荷>”}，“jar_params”：［“< Webhook载荷>”]，“python_params”：［“< Webhook载荷>”]，“spark_submit_params”：［“< Webhook载荷>”］｝

例子有效载荷

事件:MODEL_VERSION_TRANSITIONED_STAGE

响应

帖子/你的/端点/为/事件/模型-版本/阶段-过渡--数据｛“事件”：“MODEL_VERSION_TRANSITIONED_STAGE”，“webhook_id”：“c5596721253c4b429368cf6f4341b88a”，“event_timestamp”：1589859029343，“model_name”：“Airline_Delay_SparkML”，“版本”：“8”，“to_stage”：“生产”，“from_stage”：“没有”，“文本”：“注册模型‘someModel’版本8从None过渡到Production。”｝

事件:MODEL_VERSION_TAG_SET

响应

帖子/你的/端点/为/事件/模型-版本/标签-集--数据｛“事件”：“MODEL_VERSION_TAG_SET”，“webhook_id”：“8 d7fc634e624474f9bbfde960fdf354c”，“event_timestamp”：1589859029343，“model_name”：“Airline_Delay_SparkML”，“版本”：“8”，“标签”：[{“关键”：“key1”，“价值”：“value1”},{“关键”：“key2”，“价值”：“value2”}),“文本”："example@yourdomain.com设置版本标签'key1' => 'value1'， 'key2' => 'value2'用于注册型号'someModel' version 8。"｝

事件:COMMENT_CREATED

响应

帖子/你的/端点/为/事件/评论/创建--数据｛“事件”：“COMMENT_CREATED”，“webhook_id”：“8 d7fc634e624474f9bbfde960fdf354c”，“event_timestamp”：1589859029343，“model_name”：“Airline_Delay_SparkML”，“版本”：“8”，“评论”：“评论的原始文本内容”，“文本”：“一名用户评论了注册型号someModel 8。”｝

安全

为了安全起见，Databricks将x - databicks - signature包含在从有效负载计算的报头中，并使用共享密钥与webhook关联HMAC与SHA-256算法．

方法中指定标准授权标头，可以在传出请求中包含标准授权标头HttpUrlSpec网络钩子的。

客户端验证

如果设置了共享密钥，有效负载接收方应该使用共享密钥对有效负载进行hmac编码，然后将编码后的值与X-Databricks-Signature从头部。如果禁用SSL证书验证，这一点尤其重要enable_ssl_verification字段设置为假）.

请注意

enable_ssl_verification是真正的默认情况下。对于自签名证书，此字段必须为假，且目标服务器必须禁用证书验证。

出于安全考虑，Databricks建议对有效负载的hmac编码部分执行秘密验证。如果禁用主机名验证，则会增加请求被恶意路由到非预期主机的风险。

进口hmac进口hashlib进口json秘密＝shared_secret．编码（“utf - 8”）signature_key＝“X-Databricks-Signature”defvalidate_signature（请求)：如果不请求．头．has_key（signature_key)：提高异常（“没有X-Signature。Webhook不可信。”）x_sig＝请求．头．得到（signature_key）身体＝请求．身体．编码（“utf - 8”）h＝hmac．新（秘密，身体，hashlib．sha256）computed_sig＝h．hexdigest（）如果不hmac．compare_digest（computed_sig，x_sig．编码()):提高异常（“X-Signature不匹配。Webhook不可信。”）

HTTP注册表webhook的授权头

如果设置了授权报头，客户端应该通过验证授权报头中的承载令牌或授权凭据来验证HTTP请求的来源。

作业注册网络钩子的IP allowlisting

要使用webhook在启用了IP allowlisting的不同工作空间中触发作业运行，必须allowlistwebhook所在的区域NAT IP，用于接受传入的请求。

如果webhook和作业在同一个工作空间中，则不需要向allowlist中添加任何ip。

与您的帐户团队联系，以确定您需要允许列表的ip。

审计日志记录

如果您的工作空间启用了审计日志记录，则审计日志中将包括以下事件:

  • 创建webhook

  • 更新webhook

  • webhook列表

  • 删除webhook

  • 测试webhook

  • Webhook触发

Webhook触发审计日志

对于带有HTTP端点的webhook, HTTP请求发送到为webhook指定的URL以及URL和enable_ssl_verification值被记录下来。

对于带作业触发器的webhook，使用job_id和workspace_url值被记录下来。

例子

本节包括:

HTTP注册表webhook示例工作流

1.创建一个webhook

当HTTPS端点准备好接收webhook事件请求时，您可以使用webhooks Databricks REST API创建一个webhook。例如，webhook的URL可以指向Slack，以便向一个频道发布消息。

$ curl -X POST -H"授权:持有人"- d＼”{model_name”:“<模型名称>”,“事件”(“MODEL_VERSION_CREATED”):,"description": "Slack notifications"，“状态”:“TEST_MODE”," http_url_spec ": {“url”:“https://hooks.slack.com/services/..”。“秘密”:“anyRandomString”"authorization": " holder AbcdEfg1294"}}'https:// < databricks-instance > / api / 2.0 / mlflow / registry-webhooks /创建
从databricks_registry_webhooks进口RegistryWebhooksClient，HttpUrlSpechttp_url_spec＝HttpUrlSpec（url＝“https://hooks.slack.com/services/..”。，秘密＝“secret_string”，授权＝“不记名AbcdEfg1294”）http_webhook＝RegistryWebhooksClient（）．create_webhook（model_name＝“<模型名称>”，事件＝［“MODEL_VERSION_CREATED”]，http_url_spec＝http_url_spec，描述＝“松弛的通知”，状态＝“TEST_MODE”）

响应

｛“webhook”：｛“id”：“1234567890”，“creation_timestamp”：1571440826026，“last_updated_timestamp”：1582768296651，“状态”：“TEST_MODE”，“事件”:【“MODEL_VERSION_CREATED”]，“http_url_spec”：｛“url”：“https://hooks.slack.com/services/..”。，“enable_ssl_verification”：真正的}}}

方法创建一个HTTP注册表webhookDatabricks Terraform提供商和databricks_mlflow_webhook．

2.测试网钩

之前的webhook是在TEST_MODE，因此可以触发模拟事件向指定的URL发送请求。然而，webhook不会在真实事件中触发。测试端点从指定的URL返回接收到的状态代码和主体。

$ curl -X POST -H"授权:持有人"- d＼”{" id ":“1234567890”}’＼https:// < databricks-instance > / api / 2.0 / mlflow / registry-webhooks /测试
从databricks_registry_webhooks进口RegistryWebhooksClienthttp_webhook＝RegistryWebhooksClient（）．test_webhook（id＝“1234567890”）

响应

｛“状态”：200，“身体”：“OK”｝

3.将webhook更新为active状态

启用webhook的真实事件，设置其状态为活跃的通过一个更新调用，它也可以用来改变它的任何其他属性。

$ curl -X PATCH -H"授权:持有人"- d＼'{"id": "1234567890"， "status": "ACTIVE"}'＼https:// < databricks-instance > / api / 2.0 / mlflow / registry-webhooks /更新
从databricks_registry_webhooks进口RegistryWebhooksClienthttp_webhook＝RegistryWebhooksClient（）．update_webhook（id＝“1234567890”，状态＝“活跃”）

响应

｛“webhook”：｛“id”：“1234567890”，“creation_timestamp”：1571440826026，“last_updated_timestamp”：1582768296651，“状态”：“活跃”，“事件”:【“MODEL_VERSION_CREATED”]，“http_url_spec”：｛“url”：“https://hooks.slack.com/services/..”。，“enable_ssl_verification”：真正的}}}

4.删除webhook

禁用webhook，将其状态设置为禁用(使用类似于上面的更新命令)，或删除它。

$ curl -X DELETE -H"授权:持有人"- d＼”{" id ":“1234567890”}’＼https:// < databricks-instance > / api / 2.0 / mlflow / registry-webhooks /删除
从databricks_registry_webhooks进口RegistryWebhooksClienthttp_webhook＝RegistryWebhooksClient（）．delete_webhook（id＝“1234567890”）

响应

{}

作业注册webhook示例工作流

管理作业注册表webhook的工作流类似于HTTP注册表webhook，唯一的区别是job_spec字段，该字段替换http_url_spec字段。

使用webhooks，您可以在相同的工作空间或不同的工作空间中触发作业。工作区是使用可选参数指定的workspace_url．如果没有workspace_url存在时，默认行为是在与webhook相同的工作区中触发一个作业。

需求

请注意

作为安全最佳实践，当使用自动化工具、系统、脚本和应用程序进行身份验证时，Databricks建议您使用属于的访问令牌服务主体而不是工作区用户。要为服务主体创建访问令牌，请参见管理服务主体的访问令牌．

创建一个工作注册表webhook

$ curl -X POST -H"授权:持有人"- d＼”{model_name”:“<模型名称>”,“事件”(“TRANSITION_REQUEST_CREATED”):,"description": "Job webhook trigger"，“状态”:“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 /创建
从databricks_registry_webhooks进口RegistryWebhooksClient，JobSpecjob_spec＝JobSpec（job_id＝“1”，workspace_url＝“https://my-databricks-workspace.com”，access_token＝“dapi12345……”）job_webhook＝RegistryWebhooksClient（）．create_webhook（model_name＝“<模型名称>”，事件＝［“TRANSITION_REQUEST_CREATED”]，job_spec＝job_spec，描述＝“工作网络挂钩触发器”，状态＝“TEST_MODE”）

响应

｛“webhook”：｛“id”：“1234567891”，“creation_timestamp”：1591440826026，“last_updated_timestamp”：1591440826026，“状态”：“TEST_MODE”，“事件”:【“TRANSITION_REQUEST_CREATED”]，“job_spec”：｛“job_id”：“1”，“workspace_url”：“https://my-databricks-workspace.com”}}}

方法创建作业注册表webhookDatabricks Terraform提供商和databricks_mlflow_webhook．

列出注册表网络钩子的例子

$ curl -X GET -H"授权:持有人"- d＼”{model_name”:“<模型名称>“}”https:// < databricks-instance > / api / 2.0 / mlflow / registry-webhooks /列表
从databricks_registry_webhooks进口RegistryWebhooksClientwebhooks_list＝RegistryWebhooksClient（）．list_webhooks（model_name＝“<模型名称>”）

响应

｛“人”：[{“id”：“1234567890”，“creation_timestamp”：1571440826026，“last_updated_timestamp”：1582768296651，“状态”：“活跃”，“事件”:【“MODEL_VERSION_CREATED”]，“http_url_spec”：｛“url”：“https://hooks.slack.com/services/..”。，“enable_ssl_verification”：真正的}},｛“id”：“1234567891”，“creation_timestamp”：1591440826026，“last_updated_timestamp”：1591440826026，“状态”：“TEST_MODE”，“事件”:【“TRANSITION_REQUEST_CREATED”]，“job_spec”：｛“job_id”：“1”，“workspace_url”：“https://my-databricks-workspace.com”}})}

笔记本电脑

MLflow模型注册表webhooks REST API示例笔记本

在新标签页打开笔记本

MLflow模型注册表webhooks Python客户端示例笔记本

在新标签页打开笔记本