Azure Databricks'te MLflow Model Kayıt Defteri Web Kancaları

  • Makale

Önemli

Bu özellik Genel Önizlemededir.

Web kancaları, tümleştirmelerinizin eylemleri otomatik olarak tetikleyebilmesi için Model Kayıt Defteri olaylarını dinlemenizi sağlar. Makine öğrenmesi işlem hattınızı mevcut CI/CD araçları ve iş akışlarıyla otomatikleştirmek ve tümleştirmek için web kancalarını kullanabilirsiniz. Örneğin, yeni bir model sürümü oluşturulduğunda CI derlemelerini tetikleyebilir veya üretime her model geçişi istendiğinde Slack aracılığıyla ekip üyelerinizi bilgilendirebilirsiniz.

Web kancaları Databricks REST API veya PyPI üzerindeki Python istemcisi databricks-registry-webhooks aracılığıyla kullanılabilir.

Not

Unity Kataloğu'nda Modeller kullandığınızda web kancaları kullanılamaz. Alternatif olarak bkz . Aşama geçiş isteklerini kullanabilir miyim veya olaylarda web kancalarını tetikleyebilir miyim?. Web kancalarının özel uç noktalara (genel İnternet'ten erişilmeyen uç noktalar) gönderilmesi desteklenmez.

Web kancası olayları

Bu olaylardan biri veya daha fazlası üzerinde tetiklenmek üzere bir web kancası belirtebilirsiniz:

  • MODEL_VERSION_CREATED: İlişkili model için yeni bir model sürümü oluşturuldu.
  • MODEL_VERSION_TRANSITIONED_STAGE: Model sürümünün aşaması değiştirildi.
  • TRANSITION_REQUEST_CREATED: Kullanıcı model sürümünün aşamasının geçiş edilmesini istedi.
  • COMMENT_CREATED: Kullanıcı kayıtlı bir model hakkında yorum yazdı.
  • REGISTERED_MODEL_CREATED: Yeni bir kayıtlı model oluşturuldu. Bu olay türü yalnızca kayıt defteri genelindeki bir web kancası için belirtilebilir ve oluşturma isteğinde model adı belirtilmeyerek oluşturulabilir.
  • MODEL_VERSION_TAG_SET: Kullanıcı model sürümünde bir etiket ayarlar.
  • MODEL_VERSION_TRANSITIONED_TO_STAGING: Model sürümü hazırlamaya geçirildi.
  • MODEL_VERSION_TRANSITIONED_TO_PRODUCTION: Model sürümü üretime geçirildi.
  • MODEL_VERSION_TRANSITIONED_TO_ARCHIVED: Model sürümü arşivlendi.
  • TRANSITION_REQUEST_TO_STAGING_CREATED: Kullanıcı, bir model sürümünün hazırlamaya geçirilmesini istedi.
  • TRANSITION_REQUEST_TO_PRODUCTION_CREATED: Kullanıcı bir model sürümünün üretime geçirilmesini istedi.
  • TRANSITION_REQUEST_TO_ARCHIVED_CREATED: Bir kullanıcı bir model sürümünün arşiv edilmesini istedi.

Web kancası türleri

Tetikleyici hedeflerine göre iki tür web kancası vardır:

  • HTTP uç noktaları olan web kancaları (HTTP kayıt defteri web kancaları): Tetikleyicileri bir HTTP uç noktasına gönderin.
  • İş tetikleyicileri olan web kancaları (iş kayıt defteri web kancaları): Azure Databricks çalışma alanında bir işi tetikleyin. İşin çalışma alanında IP izin verilenler listesi etkinleştirildiyse, model kayıt defterinin çalışma alanı IP'lerini izin vermelisiniz. Daha fazla bilgi için bkz . İş kayıt defteri web kancaları için IP izin verilenler listesi.

Ayrıca, kapsamlarına göre farklı erişim denetimi gereksinimlerine sahip iki tür web kancası vardır:

  • Modele özgü web kancaları: Web kancası belirli bir kayıtlı model için geçerlidir. Modele özgü web kancaları oluşturmak, değiştirmek, silmek veya test etmek için kayıtlı modelde CAN MANAGE izinlerine sahip olmanız gerekir.
  • Kayıt defteri genelinde web kancaları: Web kancası, yeni bir kayıtlı model oluşturma dahil olmak üzere çalışma alanında kayıtlı herhangi bir modeldeki olaylar tarafından tetikler. Kayıt defteri genelinde bir web kancası oluşturmak için oluşturma işleminin alanını atlarsınız model_name . Kayıt defteri genelinde web kancaları oluşturmak, değiştirmek, silmek veya test etmek için çalışma alanı yöneticisi izinlerine sahip olmanız gerekir.

Web kancası yükü

Her olay tetikleyicisinin, web kancası uç noktasına giden isteğin yüküne en az alan eklenir.

  • Yapıt yolu konumu gibi hassas bilgiler dışlanır. Uygun ACL'lere sahip kullanıcılar ve sorumlular, bu bilgiler için Model Kayıt Defteri'ni sorgulamak için istemci veya REST API'lerini kullanabilir.
  • Yükler şifrelenmez. Web kancasının kaynağının Azure Databricks olduğunu doğrulama hakkında bilgi için bkz . Güvenlik .
  • Bu text alan Slack tümleştirmesini kolaylaştırır. Slack iletisi göndermek için web kancası URL'si olarak bir Slack web kancası uç noktası sağlayın.

İş kayıt defteri web kancası yükü

İş kayıt defteri web kancasının yükü işin türüne bağlıdır ve hedef çalışma alanında uç noktaya gönderilir jobs/run-now .

Tek görevli işler

Tek görevli işler, görev türüne göre üç yüke sahiptir.

Not defteri ve Python tekerlek işleri

Not defteri ve Python tekerlek işleri, alanını event_messageiçeren parametre sözlüğüne sahip bir JSON yüküne sahiptir.

{
  "job_id": 1234567890,
  "notebook_params": {
    "event_message": "<Webhook Payload>"
  }
}
Python, JAR ve Spark Submit işleri

Python, JAR ve Spark gönderme işlerinin parametre listesi içeren bir JSON yükü vardır.

{
  "job_id": 1234567890,
  "python_params": ["<Webhook Payload>"]
}
Diğer tüm işler

Diğer tüm iş türlerinin parametresiz bir JSON yükü vardır.

{
  "job_id": 1234567890
}

Çok görevli işler

Çok görevli işler, farklı görev türlerini hesaba eklemek için tüm parametrelerin doldurulmasıyla bir JSON yüküne sahiptir.

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

Örnek yük

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

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

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

Güvenlik

Güvenlik için Azure Databricks, yükten hesaplanan üst bilgide X-Databricks-Signature'ı ve SHA-256 algoritmasıyla HMAC kullanan web kancasıyla ilişkili paylaşılan gizli anahtarı içerir.

Ayrıca, web kancasında bir tane belirterek HttpUrlSpec giden isteğe standart bir Yetkilendirme üst bilgisi ekleyebilirsiniz.

İstemci doğrulaması

Paylaşılan gizli dizi ayarlanırsa, yük alıcısı yükü HMAC ile kodlamak için paylaşılan gizli diziyi kullanarak HTTP isteğinin kaynağını doğrulamalı ve ardından kodlanmış değeri üst bilgiden ile X-Databricks-Signature karşılaştırmalıdır. Ssl sertifika doğrulaması devre dışı bırakıldıysa (yani alan olarak ayarlandıysa enable_ssl_verificationfalse) bu özellikle önemlidir.

Not

enable_ssl_verification varsayılan değerdir true . Otomatik olarak imzalanan sertifikalar için bu alan olmalıdır falseve hedef sunucunun sertifika doğrulamasını devre dışı bırakması gerekir.

Databricks, güvenlik amacıyla yükün HMAC ile kodlanmış bölümüyle gizli dizi doğrulama gerçekleştirmenizi önerir. Konak adı doğrulamasını devre dışı bırakırsanız, isteğin istenmeyen bir konağa kötü amaçlı olarak yönlendirilme riskini artırırsınız.

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 kayıt defteri web kancaları için yetkilendirme üst bilgisi

Yetkilendirme üst bilgisi ayarlanırsa, istemcilerin Yetkilendirme üst bilgisindeki taşıyıcı belirteci veya yetkilendirme kimlik bilgilerini doğrulayarak HTTP isteğinin kaynağını doğrulaması gerekir.

İş kayıt defteri web kancaları için IP izin verilenler listesi

İş çalıştırmalarını tetikleyen bir web kancasını IP izin listesi etkinleştirilmiş farklı bir çalışma alanında kullanmak için, gelen istekleri kabul etmek için web kancasının bulunduğu bölge NAT IP'sini izin verilenler listesine eklemelisiniz.

Web kancası ve iş aynı çalışma alanındaysa, izin verilenler listenize ip eklemeniz gerekmez.

İşiniz çok kiracılı bir Azure bölgesinde bulunuyorsa bkz . Azure Databricks denetim düzlemi adresleri. Diğer tüm bölgelerde izin verilenler listesine eklemeniz gereken IP'leri belirlemek için hesap ekibinize başvurun.

Denetim günlüğü

Çalışma alanınız için denetim günlüğü etkinleştirildiyse, denetim günlüklerine aşağıdaki olaylar eklenir:

  • Web kancası oluştur
  • Web kancasını güncelleştirme
  • Web kancasını listeleme
  • Web kancasını silme
  • Web kancasını test et
  • Web kancası tetikleyicisi

Web kancası tetikleyicisi denetim günlüğü

HTTP uç noktaları olan web kancaları için, WEB kancası için belirtilen URL'ye gönderilen HTTP isteği, URL ve enable_ssl_verification değerlerle birlikte günlüğe kaydedilir.

İş tetikleyicileri olan web kancaları job_id için ve workspace_url değerleri günlüğe kaydedilir.

Örnekler

Bu bölüm şunları içerir:

HTTP kayıt defteri web kancası örnek iş akışı

1. Web kancası oluşturma

Https uç noktası web kancası olay isteğini almaya hazır olduğunda, web kancaları Databricks REST API'sini kullanarak bir web kancası oluşturabilirsiniz. Örneğin, web kancasının URL'si bir kanala ileti göndermek için Slack'i işaret edebilir.

$ 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 sağlayıcısı ve databricks_mlflow_webhook ile bir HTTP kayıt defteri web kancası da oluşturabilirsiniz.

2. Web kancasını test edin

Önceki web kancası içinde TEST_MODEoluşturulmuştur, bu nedenle belirtilen URL'ye istek göndermek için bir sahte olay tetiklenebilir. Ancak, web kancası gerçek bir olayda tetiklenmez. Test uç noktası, belirtilen URL'den alınan durum kodunu ve gövdesini döndürür.

$ 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. Web kancasını etkin duruma güncelleştirme

Web kancasını gerçek olaylar için etkinleştirmek için, diğer özelliklerinden herhangi birini değiştirmek için de kullanılabilen bir güncelleştirme çağrısı aracılığıyla durumunu ACTIVE olarak ayarlayın.

$ 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. Web kancasını silme

Web kancasını devre dışı bırakmak için durumunu olarak ayarlayın DISABLED (yukarıdakine benzer bir güncelleştirme komutu kullanarak) veya silin.

$ 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

{}

İş kayıt defteri web kancası örnek iş akışı

İş kayıt defteri web kancalarını yönetmeye yönelik iş akışı HTTP kayıt defteri web kancalarına benzer ve tek fark alanın yerini http_url_spec alan job_spec alan olur.

Web kancalarıyla, işleri aynı çalışma alanında veya farklı bir çalışma alanında tetikleyebilirsiniz. Çalışma alanı isteğe bağlı parametresi workspace_urlkullanılarak belirtilir. Yoksa workspace_url , varsayılan davranış web kancası ile aynı çalışma alanında bir işi tetiklemedir.

Gereksinimler

  • Var olan bir iş.
  • Kişisel erişim belirteci. Erişim belirteçlerinin API'ler tarafından döndürülen web kancası nesnesine dahil edilmediğini unutmayın.

Not

En iyi güvenlik uygulaması olarak otomatik araçlar, sistemler, betikler ve uygulamalarla kimlik doğrulaması yaptığınızda Databricks, çalışma alanı kullanıcıları yerine hizmet sorumlularına ait kişisel erişim belirteçlerini kullanmanızı önerir. Hizmet sorumlularına yönelik belirteçler oluşturmak için bkz . Hizmet sorumlusu için belirteçleri yönetme.

İş kayıt defteri web kancası oluşturma

$ 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 sağlayıcısı ve databricks_mlflow_webhook ile bir iş kayıt defteri web kancası da oluşturabilirsiniz.

Liste kayıt defteri web kancaları örneği

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

Notebooks

MLflow Model Kayıt Defteri web kancaları REST API örnek not defteri

Not defterini alma

MLflow Model Kayıt Defteri web kancaları Python istemci örneği not defteri

Not defterini alma