Azure Databricks의 MLflow 모델 레지스트리 웹후크

아티클
05/06/2024

Important

이 기능은 공개 미리 보기 상태입니다.

Webhook를 사용하면 통합에서 작업을 자동으로 트리거할 수 있도록 Model Registry 이벤트를 수신 대기할 수 있습니다. 웹후크를 사용하여 기계 학습 파이프라인을 자동화하고 기존 CI/CD 도구 및 워크플로와 통합할 수 있습니다. 예를 들어 새 모델 버전을 만들 때 CI 빌드를 트리거하거나 프로덕션으로의 모델 전환을 요청할 때마다 Slack을 통해 팀 구성원에게 알릴 수 있습니다.

웹후크는 Databricks REST API 또는 PyPI의 Python 클라이언트 databricks-registry-webhooks를 통해 사용할 수 있습니다.

참고 항목

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이 있는 사용자 및 보안 주체는 클라이언트 또는 REST API를 사용하여 모델 레지스트리에서 이 정보를 쿼리할 수 있습니다.
페이로드는 암호화되지 않습니다. Azure Databricks가 웹후크의 원본인지 확인하는 방법에 대한 자세한 내용은 보안을 참조하세요.
이 text 필드는 Slack 통합을 용이하게 합니다. Slack 메시지를 보내려면 Slack 웹후크 엔드포인트를 웹후크 URL로 제공합니다.

작업 레지스트리 웹후크 페이로드

작업 레지스트리 웹후크에 대한 페이로드는 작업 유형에 따라 달라지고 대상 작업 영역의 jobs/run-now 엔드포인트로 전송됩니다.

싱글태스킹 작업

싱글태스킹 작업에는 작업 유형에 따라 세 가지 페이로드 중 하나가 있습니다.

Notebook 및 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`

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 및 SHA-256 알고리즘과 HMAC를 사용하여 웹후크와 연결된 공유 비밀 키를 포함합니다.

또한 웹후크의 HttpUrlSpec에 표준 권한 부여 헤더를 지정하여 보내는 요청에 포함할 수 있습니다.

클라이언트 확인

공유 비밀이 설정된 경우 페이로드 수신자는 공유 비밀로 페이로드를 HMAC로 인코딩한 다음, 인코딩된 값을 헤더의 X-Databricks-Signature와 비교하여 HTTP 요청의 원본을 확인해야 합니다. 이는 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 허용 목록이 사용하도록 설정된 다른 작업 영역에서 작업 실행을 트리거하는 웹후크를 사용하려면 웹후크가 있는 지역 NAT IP를 허용 목록에 추가하여 들어오는 요청을 수락해야 합니다.

웹후크와 작업이 동일한 작업 영역에 있는 경우 허용 목록에 IP를 추가할 필요가 없습니다.

작업이 Azure 다중 테넌트 지역에 있는 경우 Azure Databricks 컨트롤 플레인 주소를 참조 하세요. 다른 모든 지역의 경우 계정 팀에 문의하여 허용 목록에 필요한 IP를 식별합니다.

감사 로깅

작업 영역에 감사 로깅을 사용하도록 설정하면 감사 로그에 다음 이벤트가 포함됩니다.

웹후크 만들기
웹후크 업데이트
웹후크 나열
웹후크 삭제
웹후크 테스트
웹후크 트리거

웹후크 트리거 감사 로깅

HTTP 엔드포인트가 있는 웹후크의 경우 URL 및 enable_ssl_verification 값과 함께 웹후크에 지정된 URL로 전송되는 HTTP 요청이 로그됩니다.

작업 트리거가 있는 웹후크의 경우 job_id 및 workspace_url 값이 로그됩니다.

예제

이 단원에는 다음이 포함됩니다.

HTTP 레지스트리 웹후크 워크플로 예제.
작업 레지스트리 웹후크 워크플로 예제.
목록 웹후크 예제.
두 개의 예제 Notebook: 하나는 REST API를 보여주고 하나는 Python 클라이언트를 보여줍니다.

HTTP 레지스트리 웹후크 예제 워크플로

1. 웹후크 만들기

HTTPS 엔드포인트가 웹후크 이벤트 요청을 받을 준비가 되면 웹후크 Databricks REST API를 사용하여 웹후크를 만들 수 있습니다. 예를 들어 웹후크의 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
}}}

Databricks Terraform 공급자 및 databricks_mlflow_webhook를 사용하여 HTTP 레지스트리 웹후크를 만들 수도 있습니다.

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 레지스트리 웹후크와 유사하며, 유일한 차이점은 http_url_spec 필드를 대체하는 job_spec 필드입니다.

웹후크를 사용하면 동일한 작업 영역 또는 다른 작업 영역에서 작업을 트리거할 수 있습니다. 작업 영역은 선택적 매개 변수 workspace_url을 사용하여 지정됩니다. workspace_url이 없는 경우 기본 동작은 웹후크와 동일한 작업 영역에서 작업을 트리거하는 것입니다.

요구 사항

기존 작업.
개인용 액세스 토큰. 액세스 토큰은 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"
}}]}

Share via

Azure Databricks의 MLflow 모델 레지스트리 웹후크

웹후크 이벤트

웹후크 유형

웹후크 페이로드

작업 레지스트리 웹후크 페이로드

싱글태스킹 작업

Notebook 및 Python 휠 작업

Python, JAR 및 Spark 제출 작업

기타 모든 작업

멀티태스킹 작업

예제 페이로드

이벤트: `MODEL_VERSION_TRANSITIONED_STAGE`

이벤트: `MODEL_VERSION_TAG_SET`

이벤트: `COMMENT_CREATED`

보안

클라이언트 확인

HTTP 레지스트리 웹후크에 대한 인증 헤더

작업 레지스트리 웹후크에 대한 IP 허용 목록

감사 로깅

웹후크 트리거 감사 로깅

예제

HTTP 레지스트리 웹후크 예제 워크플로

1. 웹후크 만들기

2. 웹후크 테스트

3. 웹후크를 활성 상태로 업데이트

4. 웹후크 삭제

작업 레지스트리 웹후크 예제 워크플로

요구 사항

작업 레지스트리 웹후크 만들기

레지스트리 웹후크 나열 예제

Notebooks

MLflow 모델 레지스트리 웹후크 REST API 예제 Notebook

MLflow 모델 레지스트리 웹후크 Python 클라이언트 예제 Notebook

피드백

피드백

추가 리소스

Share via

Azure Databricks의 MLflow 모델 레지스트리 웹후크

웹후크 이벤트

웹후크 유형

웹후크 페이로드

작업 레지스트리 웹후크 페이로드

싱글태스킹 작업

Notebook 및 Python 휠 작업

Python, JAR 및 Spark 제출 작업

기타 모든 작업

멀티태스킹 작업

예제 페이로드

이벤트: MODEL_VERSION_TRANSITIONED_STAGE

이벤트: MODEL_VERSION_TAG_SET

이벤트: COMMENT_CREATED

보안

클라이언트 확인

HTTP 레지스트리 웹후크에 대한 인증 헤더

작업 레지스트리 웹후크에 대한 IP 허용 목록

감사 로깅

웹후크 트리거 감사 로깅

예제

HTTP 레지스트리 웹후크 예제 워크플로

1. 웹후크 만들기

2. 웹후크 테스트

3. 웹후크를 활성 상태로 업데이트

4. 웹후크 삭제

작업 레지스트리 웹후크 예제 워크플로

요구 사항

작업 레지스트리 웹후크 만들기

레지스트리 웹후크 나열 예제

Notebooks

MLflow 모델 레지스트리 웹후크 REST API 예제 Notebook

MLflow 모델 레지스트리 웹후크 Python 클라이언트 예제 Notebook

피드백

피드백

추가 리소스

이벤트: `MODEL_VERSION_TRANSITIONED_STAGE`

이벤트: `MODEL_VERSION_TAG_SET`

이벤트: `COMMENT_CREATED`