Webhook Registri Model MLflow di Azure Databricks

Artikel
10/04/2024

Penting

Webhook memungkinkan Anda untuk mendengarkan peristiwa Registri Model sehingga integrasi Anda dapat secara otomatis memicu tindakan. Anda dapat menggunakan webhook untuk mengotomatiskan dan mengintegrasikan alur pembelajaran mesin Anda dengan alat dan alur kerja CI/CD yang ada. Misalnya, Anda dapat memicu build CI saat versi model baru dibuat atau memberi tahu anggota tim Anda melalui Slack setiap kali transisi model ke produksi diminta.

Webhooks tersedia melalui REST API Databricks atau klien Python databricks-registry-webhooks di PyPI.

Catatan

Webhook tidak tersedia saat Anda menggunakan Model di Unity Catalog. Untuk alternatif, lihat Dapatkah saya menggunakan permintaan transisi tahap atau memicu webhook pada peristiwa?. Mengirim webhook ke titik akhir privat (titik akhir yang tidak dapat diakses dari internet publik) tidak didukung.

Peristiwa webhook

Anda dapat menentukan webhook untuk memicu satu atau beberapa peristiwa ini:

MODEL_VERSION_CREATED: Versi model baru dibuat untuk model terkait.
MODEL_VERSION_TRANSITIONED_STAGE: Tahap versi model diubah.
TRANSITION_REQUEST_CREATED: Pengguna meminta tahap versi model dialihkan.
COMMENT_CREATED: Pengguna menulis komentar tentang model terdaftar.
REGISTERED_MODEL_CREATED: Model terdaftar baru dibuat. Jenis peristiwa ini hanya dapat ditentukan untuk webhook di seluruh registri, yang dapat dibuat dengan tidak menentukan nama model dalam permintaan buat.
MODEL_VERSION_TAG_SET: Pengguna menetapkan tag pada versi model.
MODEL_VERSION_TRANSITIONED_TO_STAGING: Versi model dialihkan ke penahapan.
MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Versi model dialihkan ke produksi.
MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Versi model diarsipkan.
TRANSITION_REQUEST_TO_STAGING_CREATED: Pengguna meminta versi model dialihkan ke penahapan.
TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Pengguna meminta versi model dialihkan ke produksi.
TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Pengguna meminta versi model dialihkan ke diarsipkan.

Jenis webhook

Ada dua jenis webhook berdasarkan target pemicunya:

Webhook dengan titik akhir HTTP (webhook registri HTTP): Mengirim pemicu ke titik akhir HTTP.
Webhook dengan pemicu pekerjaan (webhook registri pekerjaan): Memicu pekerjaan di ruang kerja Azure Databricks. Jika daftar IP yang diizinkan diaktifkan di ruang kerja pekerjaan, Anda harus mengizinkan daftar IP ruang kerja dari registri model. Lihat daftar IP yang diizinkan untuk webhook registri pekerjaan untuk mendapatkan informasi lebih lanjut.

Ada juga dua jenis webhook berdasarkan ruang lingkupnya, dengan persyaratan kontrol akses yang berbeda:

Webhook khusus model: Webhook berlaku untuk model terdaftar tertentu. Anda harus memiliki izin CAN MANAGE pada model terdaftar untuk membuat, memodifikasi, menghapus, atau menguji webhook khusus model.
Webhook di seluruh registri: Webhook dipicu oleh peristiwa pada model terdaftar apa pun di ruang kerja, termasuk pembuatan model terdaftar baru. Untuk membuat webhook di seluruh registri, hilangkan bidang model_name saat pembuatan. Anda harus memiliki izin admin ruang kerja untuk membuat, memodifikasi, menghapus, atau menguji webhook di seluruh registri.

Payload Webhook

Setiap pemicu peristiwa memiliki bidang minimal yang disertakan dalam payload untuk permintaan keluar ke titik akhir webhook.

Informasi sensitif seperti lokasi jalur artefak dikecualikan. Pengguna dan prinsipal dengan ACL yang sesuai dapat menggunakan API klien atau REST untuk meminta Registri Model untuk informasi ini.
Payload tidak dienkripsi. Lihat Keamanan untuk informasi tentang cara memvalidasi bahwa Azure Databricks adalah sumber webhook.
Bidang text memfasilitasi integrasi Slack. Untuk mengirim pesan Slack, sediakan titik akhir webhook Slack sebagai URL webhook.

Payload webhook registri pekerjaan

Payload untuk webhook registri pekerjaan tergantung pada jenis pekerjaan dan dikirim ke titik akhir jobs/run-now di ruang kerja target.

Pekerjaan tugas tunggal

Pekerjaan tugas tunggal memiliki salah satu dari tiga payload berdasarkan jenis tugas.

Pekerjaan wheel Notebook dan Python

Pekerjaan wheel Notebook dan Python memiliki payload JSON dengan kamus parameter yang berisi bidang event_message.

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

Pekerjaan Python, JAR, dan Spark Submit

Pekerjaan Python, JAR, dan Spark submit memiliki payload JSON dengan daftar parameter.

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

Semua pekerjaan lainnya

Semua jenis pekerjaan lainnya memiliki payload JSON tanpa parameter.

{
  "job_id": 1234567890
}

Pekerjaan multi-tugas

Pekerjaan multi-tugas memiliki payload JSON dengan semua parameter yang diisi untuk bertanggung jawab atas jenis tugas yang berbeda.

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

Contoh payload

peristiwa: `MODEL_VERSION_TRANSITIONED_STAGE`

Respons

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

peristiwa: `MODEL_VERSION_TAG_SET`

Respons

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

peristiwa: `COMMENT_CREATED`

Respons

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

Keamanan

Untuk keamanan, Azure Databricks menyertakan X-Databricks-Signature di header yang dihitung dari payload dan kunci rahasia bersama yang terkait dengan webhook menggunakan HMAC dengan algoritma SHA-256.

Selain itu, Anda dapat menyertakan header Otorisasi standar dalam permintaan keluar dengan menentukan header di HttpUrlSpec webhook.

Verifikasi klien

Jika rahasia bersama ditetapkan, penerima payload harus memverifikasi sumber permintaan HTTP dengan menggunakan rahasia bersama untuk mengodekan payload HMAC, lalu membandingkan nilai yang dikodekan dengan X-Databricks-Signature dari header. Ini sangat penting jika validasi sertifikat SSL dinonaktifkan (yaitu, jika bidang enable_ssl_verification diatur ke false).

Catatan

enable_ssl_verification adalah true secara default. Untuk sertifikat yang ditandatangani sendiri, bidang ini harus false, dan server tujuan harus menonaktifkan validasi sertifikat.

Untuk tujuan keamanan, Databricks merekomendasikan agar Anda melakukan validasi rahasia dengan bagian payload yang dikodekan HMAC. Jika Anda menonaktifkan validasi nama host, Anda meningkatkan risiko bahwa permintaan dapat dialihkan ke host yang tidak diinginkan.

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

Header otorisasi untuk webhook registri HTTP

Jika header Otorisasi ditetapkan, klien harus memverifikasi sumber permintaan HTTP dengan memverifikasi token pembawa atau kredensial otorisasi di header Otorisasi.

Daftar IP yang diizinkan untuk webhook registri pekerjaan

Untuk menggunakan webhook yang memicu pekerjaan berjalan di ruang kerja lain yang mengaktifkan pengaktifan IP, Anda harus mengizinkan daftar IP NAT wilayah tempat webhook berada untuk menerima permintaan masuk.

Jika webhook dan pekerjaan berada di ruang kerja yang sama, Anda tidak perlu menambahkan IP apa pun ke daftar yang diizinkan.

Jika pekerjaan Anda terletak di wilayah multipenyewa Azure, lihat Alamat sarana kontrol Azure Databricks. Untuk semua wilayah lain, hubungi tim akun Anda untuk mengidentifikasi IP yang perlu Anda izinkan.

Penglogan Audit

Jika pencatatan audit diaktifkan untuk ruang kerja Anda, peristiwa berikut disertakan dalam log audit:

Membuat webhook
Perbarui webhook
Cantumkan webhook
Hapus webhook
Menguji Webhook
Pemicu Webhook

Pencatatan audit pemicu webhook

Untuk webhook dengan titik akhir HTTP, permintaan HTTP yang dikirim ke URL yang ditentukan untuk webhook bersama dengan URL dan nilai enable_ssl_verification dicatat.

Untuk webhook dengan pemicu pekerjaan, nilai job_id dan workspace_url dicatat.

Contoh

Bagian ini meliputi:

Contoh alur kerja webhook registri HTTP.
Contoh alur kerja webhook registri pekerjaan.
contoh daftar webhook.
dua contoh notebook: satu menggambarkan REST API, dan satu menggambarkan klien Python.

Alur kerja contoh webhook registri HTTP

1. Membuat webhook

Jika titik akhir HTTPS siap untuk menerima permintaan peristiwa webhook, Anda dapat membuat webhook menggunakan webhook REST API Databricks. Misalnya, URL webhook dapat menunjuk ke Slack untuk memposting pesan ke saluran.

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

Respons

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

Anda juga dapat membuat webhook registri HTTP dengan penyedia Databricks Terraform dan databricks_mlflow_webhook.

2. Menguji webhook

Webhook sebelumnya dibuat pada TEST_MODE, sehingga acara tiruan dapat dipicu untuk mengirim permintaan ke URL yang ditentukan. Namun, webhook tidak memicu pada peristiwa nyata. Titik akhir pengujian mengembalikan kode status dan badan yang diterima dari URL yang ditentukan.

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

Respons

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

3. Memperbarui webhook ke status aktif

Untuk mengaktifkan webhook untuk peristiwa nyata, atur statusnya ACTIVE melalui panggilan pembaruan, yang juga dapat digunakan untuk mengubah properti lainnya.

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

Respons

{"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. Menghapus webhook

Untuk menonaktifkan webhook, atur statusnya ke DISABLED (menggunakan perintah pembaruan serupa seperti di atas), atau hapus.

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

Respons

{}

Alur kerja contoh webhook registri HTTP

Alur kerja untuk mengelola webhooks registri pekerjaan mirip dengan webhooks registri HTTP, dengan satu-satunya perbedaan adalah job_spec bidang yang menggantikan bidang http_url_spec.

Dengan webhook, Anda dapat memicu pekerjaan di ruang kerja yang sama atau di ruang kerja yang berbeda. Ruang kerja ditentukan menggunakan parameter workspace_urlopsional. Jika workspace_url tidak ada, perilaku default adalah memicu pekerjaan di ruang kerja yang sama dengan webhook.

Persyaratan

Pekerjaan yang ada.
Token akses pribadi. Perhatikan bahwa token akses hanya dapat dibaca oleh layanan MLflow dan tidak dapat dikembalikan oleh pengguna Azure Databricks di API Registri Model.

Catatan

Sebagai praktik terbaik keamanan, saat Anda mengautentikasi dengan alat, sistem, skrip, dan aplikasi otomatis, Databricks merekomendasikan agar Anda menggunakan token akses pribadi milik perwakilan layanan, bukan pengguna ruang kerja. Untuk membuat token untuk perwakilan layanan, lihat Mengelola token untuk perwakilan layanan.

Membuat webhook registri pekerjaan

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

Respons

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

Anda juga dapat membuat webhook registri pekerjaan dengan penyedia Databricks Terraform dan databricks_mlflow_webhook.

Cantumkan contoh registri 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>")

Respons

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

Bagikan melalui

Webhook Registri Model MLflow di Azure Databricks

Peristiwa webhook

Jenis webhook

Payload Webhook

Payload webhook registri pekerjaan

Pekerjaan tugas tunggal

Pekerjaan wheel Notebook dan Python

Pekerjaan Python, JAR, dan Spark Submit

Semua pekerjaan lainnya

Pekerjaan multi-tugas

Contoh payload

peristiwa: `MODEL_VERSION_TRANSITIONED_STAGE`

peristiwa: `MODEL_VERSION_TAG_SET`

peristiwa: `COMMENT_CREATED`

Keamanan

Verifikasi klien

Header otorisasi untuk webhook registri HTTP

Daftar IP yang diizinkan untuk webhook registri pekerjaan

Penglogan Audit

Pencatatan audit pemicu webhook

Contoh

Alur kerja contoh webhook registri HTTP

1. Membuat webhook

2. Menguji webhook

3. Memperbarui webhook ke status aktif

4. Menghapus webhook

Alur kerja contoh webhook registri HTTP

Persyaratan

Membuat webhook registri pekerjaan

Cantumkan contoh registri webhook

Notebook

MLflow webhook Registri Model REST API contoh notebook

Webhook Registri Model MLflow contoh notebook klien Python

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Webhook Registri Model MLflow di Azure Databricks

Peristiwa webhook

Jenis webhook

Payload Webhook

Payload webhook registri pekerjaan

Pekerjaan tugas tunggal

Pekerjaan wheel Notebook dan Python

Pekerjaan Python, JAR, dan Spark Submit

Semua pekerjaan lainnya

Pekerjaan multi-tugas

Contoh payload

peristiwa: MODEL_VERSION_TRANSITIONED_STAGE

peristiwa: MODEL_VERSION_TAG_SET

peristiwa: COMMENT_CREATED

Keamanan

Verifikasi klien

Header otorisasi untuk webhook registri HTTP

Daftar IP yang diizinkan untuk webhook registri pekerjaan

Penglogan Audit

Pencatatan audit pemicu webhook

Contoh

Alur kerja contoh webhook registri HTTP

1. Membuat webhook

2. Menguji webhook

3. Memperbarui webhook ke status aktif

4. Menghapus webhook

Alur kerja contoh webhook registri HTTP

Persyaratan

Membuat webhook registri pekerjaan

Cantumkan contoh registri webhook

Notebook

MLflow webhook Registri Model REST API contoh notebook

Webhook Registri Model MLflow contoh notebook klien Python

Saran dan Komentar

Sumber Daya Tambahan:

peristiwa: `MODEL_VERSION_TRANSITIONED_STAGE`

peristiwa: `MODEL_VERSION_TAG_SET`

peristiwa: `COMMENT_CREATED`