Поделиться через

Веб-перехватчики реестра моделей MLflow в Azure Databricks

  • Статья

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии.

Веб-перехватчики позволяют прослушивать события реестра моделей, чтобы интеграции могли автоматически активировать действия. Веб-перехватчики можно использовать для автоматизации и интеграции конвейера машинного обучения с существующими средствами и рабочими процессами CI/CD. Например, можно активировать сборки CI при создании новой версии модели или уведомлять участников вашей команды с помощью Slack при каждом запросе на перенос модели в рабочую среду.

Веб-перехватчики доступны в REST API Databricks или на клиенте Python databricks-registry-webhooks в PyPI.

Примечание.

Веб-перехватчики недоступны при использовании моделей в каталоге Unity. Дополнительные сведения см. в статье "Можно ли использовать запросы на переход этапов" или "триггеры веб-перехватчиков" для событий?. Отправка веб-перехватчиков в частные конечные точки (конечные точки, недоступные из общедоступного Интернета), не поддерживается.

События веб-перехватчика

Можно указать веб-перехватчик, который будет запускаться при выполнении одного или нескольких следующих событий:

  • MODEL_VERSION_CREATED: для связанной модели была создана новая версия модели.
  • MODEL_VERSION_TRANSITIONED_STAGE: этап версии модели был изменен.
  • TRANSITION_REQUEST_CREATED: пользователь запросил перенос этапа версии модели.
  • COMMENT_CREATED: пользователь написал комментарий к зарегистрированной модели.
  • REGISTERED_MODEL_CREATED: создана новая зарегистрированная модель. Этот тип событий можно указать только для веб-перехватчика уровня реестра, который можно создать без указания имени модели в запросе на создание.
  • 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: пользователь запросил помещение версии модели в архив.

Типы веб-перехватчиков

Существует два типа веб-перехватчиков, на основе целевых объектов триггера.

  • Веб-перехватчики с конечными точками HTTP (веб-перехватчики реестра HTTP) отправляют триггеры в конечную точку HTTP.
  • Веб-перехватчики с триггерами заданий (веб-перехватчики реестра заданий) активируют задания в рабочей области Azure Databricks. Если включено создание списка разрешенных IP-адресов в рабочей области задания, необходимо включить в список IP-адреса рабочей области реестре модели. Дополнительные сведения см. в разделе Создание списка разрешенных IP-адресов для веб-перехватчиков реестра заданий.

Веб-перехватчики делятся на два типа по области действия, и для каждого типа предъявляются различные требования к контролю доступа:

  • Веб-перехватчики, зависимые от модели: веб-перехватчик применяется к конкретным зарегистрированным моделям. Необходимо иметь разрешения CAN MANAGE для зарегистрированной модели для создания, изменения, удаления или тестирования веб-перехватчиков для конкретной модели.
  • Веб-перехватчики уровня реестра: веб-перехватчик активируется событиями в любой зарегистрированной модели в рабочей области, включая создание новой зарегистрированной модели. Чтобы создать веб-перехватчик уровня реестра, не указывайте поле model_name при создании. Для создания, изменения, удаления и тестирования веб-перехватчиков уровня реестра необходимо иметь разрешения администратора рабочей области.

Полезные данные веб-перехватчика

Каждый триггер события имеет минимальное количество полей, включаемых в полезные данные для исходящего запроса к конечной точке веб-перехватчика.

  • Конфиденциальные сведения, например расположение пути артефакта, исключаются. Пользователи и участники с соответствующими списками ACL могут использовать клиентский API-интерфейс или REST API для запроса этих сведений в реестре моделей.
  • Полезные данные не шифруются. Сведения о том, как можно проверить, является ли Azure Databricks источником веб-перехватчика, см. в разделе Безопасность.
  • Поле text упрощает интеграцию Slack. Чтобы отправить сообщение Slack, укажите конечную точку веб-перехватчика Slack в качестве URL-адреса веб-перехватчика.

Полезные данные веб-перехватчика реестра заданий

Полезные данные для веб-перехватчика реестра заданий зависят от типа задания и отправляются в конечную точку jobs/run-now в целевой рабочей области.

Задания с одной задачей

Задания с одной задачей содержат один из трех видов полезных данных, определяемый типом задачи.

Задания записных книжек и Python Wheel

Задания записной книжки и Python Wheel содержат полезные данные JSON со словарем параметров, в котором присутствует поле event_message.

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

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

событие: 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."
}

событие: 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."
}

Безопасность

В целях безопасности Azure Databricks включает подпись X-Databricks-Signature в заголовок, вычисленный на основе полезных данных, и общий секретный ключ, связанный с веб-перехватчиком, с помощью HMAC с алгоритмом SHA-256.

Кроме того, можно включить стандартный заголовок авторизации в исходящий запрос, указав его в HttpUrlSpec веб-перехватчика.

Проверка клиента

Если задан общий секрет, получатель полезных данных должен проверить источник HTTP-запроса, используя общий секрет для кодирования полезных данных кодом HMAC, а затем сравнив закодированное значение с X-Databricks-Signature из заголовка. Это особенно важно, если проверка SSL-сертификата отключена (то есть, если поле enable_ssl_verification имеет значение false).

Примечание.

enable_ssl_verification по умолчанию равен true. Для самозаверяющих сертификатов это поле должно иметь значение false, а целевой сервер должен отключить проверку сертификата.

В целях безопасности модуль данных рекомендует выполнять проверку секрета, используя часть полезной нагрузки, закодированной кодом 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

Если задан заголовок авторизации, клиенты должны проверить источник HTTP-запроса, проверив токен носителя или учетные данные авторизации в заголовке авторизации.

Создание списка разрешенных IP-адресов для веб-перехватчиков реестра заданий

Для использования веб-перехватчика, запускающего задание, в другой рабочей области с включенной функцией создания списков разрешенных IP-адресов, необходимо включить в список разрешенных разрешений IP-адрес региона NAT, где веб-перехватчик будет принимать входящие запросы.

Если веб-перехватчик и задание находятся в одной рабочей области, добавлять IP-адреса в список разрешений не требуется.

Если задание находится в мультитенантном регионе Azure, ознакомьтесь с адресами плоскости управления Azure Databricks. Для всех остальных регионов обратитесь к группе учетных записей, чтобы определить IP-адреса, необходимые для списка разрешений.

Ведение журнала аудита

Если ведение журнала аудита включено для рабочей области, в журналы аудита включаются следующие события.

  • Создание веб-перехватчика
  • Обновление веб-перехватчика
  • Включение веб-перехватчика в список
  • Удаление веб-перехватчика
  • Проверка веб-перехватчика
  • Триггер веб-перехватчика

Ведение журнала аудита триггеров веб-перехватчика

Для веб-перехватчиков с конечными точками HTTP в журнале регистрируется HTTP-запрос, отправленный на URL-адрес, указанный для веб-перехватчика наряду с URL-адресом и значениями enable_ssl_verification.

Для веб-перехватчиков с триггерами заданий в журнале регистрируются значения job_id и workspace_url.

Примеры

В этом разделе:

Пример рабочего процесса веб-перехватчика в реестре HTTP

1. Создание веб-перехватчика

Когда конечная точка HTTPS готова к получению запроса события веб-перехватчика, его можно создать с помощью REST API Databricks веб-перехватчиков. Например, 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"
)

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

Вы также можете создать веб-перехватчик реестра HTTP с помощью поставщика Databricks Terraform и databricks_mlflow_webhook.

2. Тестирование веб-перехватчика

Предыдущий веб-перехватчик был создан в TEST_MODE, поэтому можно запустить макет события, чтобы отправить запрос по указанному URL-адресу. Однако веб-перехватчик не срабатывает для реального события. Тестовая конечная точка возвращает полученный код состояния и текстовую область из указанного 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. Изменение состояния веб-перехватчика на «Активно»

Чтобы включить веб-перехватчик для реальных событий, задайте для него состояние 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"
)

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. Удаление веб-перехватчика

Чтобы отключить веб-перехватчик, задайте для него состояние 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"
)

Response

{}

Пример рабочего процесса веб-перехватчика в реестре заданий

Рабочий процесс для управления веб-перехватчиками реестра заданий похож на процесс для веб-перехватчиков реестра HTTP. Единственным отличием является job_spec поле, заменяющее поле http_url_spec.

С помощью веб-перехватчиков можно запускать задания в той же или в другой рабочей области. Рабочая область указывается с помощью необязательного параметра workspace_url. Если workspace_url отсутствует, поведение по умолчанию предполагает запуск задания в той же рабочей области, где запущен веб-перехватчик.

Требования

  • Существующее задание.
  • Личный маркер доступа. Обратите внимание, что маркеры доступа могут считываться только службой MLflow и не могут быть возвращены пользователями Azure Databricks в API реестра моделей.

Примечание.

В качестве рекомендации по обеспечению безопасности при проверке подлинности с помощью автоматизированных средств, систем, сценариев и приложений Databricks рекомендуется использовать личные маркеры доступа, принадлежащие субъектам-службам, а не пользователям рабочей области. Сведения о создании маркеров для субъектов-служб см. в разделе "Управление маркерами" для субъекта-службы.

Создание веб-перехватчика реестра заданий

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

Вы также можете создать веб-перехватчик реестра заданий с помощью поставщика Databricks Terraform и databricks_mlflow_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>")

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

Записные книжки

Записная книжка с примером REST API веб-перехватчиков в реестре моделей MLflow

Получить записную книжку

Записная книжка с примером клиента Python для перехватчиков реестра моделей MLflow пример записной книжки клиента Python

Получить записную книжку