Share via

خطافات الويب الخاصة بسجل نموذج MLflow على Azure Databricks

  • مقالة

هام

هذه الميزة في المعاينة العامة.

تمكنك خطافات الويب من الاستماع إلى أحداث Model Registry بحيث يمكن أن تؤدي عمليات التكامل الخاصة بك إلى تشغيل الإجراءات تلقائيا. يمكنك استخدام خطافات الويب لأتمتة ودمج مسار التعلم الآلي الخاص بك مع أدوات CI/CD الحالية وسير العمل. على سبيل المثال، يمكنك تشغيل إصدارات CI عند إنشاء إصدار نموذج جديد أو إعلام أعضاء الفريق من خلال Slack في كل مرة يتم فيها طلب انتقال نموذج إلى الإنتاج.

تتوفر خطافات الويب من خلال Databricks REST API أو عميل databricks-registry-webhooks Python على 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 allowlisting لخطافات الويب لسجل الوظائف لمزيد من المعلومات.

هناك أيضا نوعان من خطافات الويب استنادا إلى نطاقها، مع متطلبات مختلفة للتحكم في الوصول:

  • خطافات الويب الخاصة بالنموذج: ينطبق خطاف الويب على نموذج مسجل محدد. يجب أن يكون لديك أذونات CAN MANAGE على النموذج المسجل لإنشاء خطافات ويب خاصة بالنموذج أو تعديلها أو حذفها أو اختبارها.
  • خطافات الويب على مستوى السجل: يتم تشغيل خطاف الويب بواسطة الأحداث على أي نموذج مسجل في مساحة العمل، بما في ذلك إنشاء نموذج مسجل جديد. لإنشاء خطاف ويب على مستوى السجل، احذف الحقل عند model_name الإنشاء. يجب أن يكون لديك أذونات مسؤول مساحة العمل لإنشاء خطافات الويب على مستوى السجل أو تعديلها أو حذفها أو اختبارها.

حمولة إخطار على الويب

يحتوي كل مشغل حدث على الحد الأدنى من الحقول المضمنة في الحمولة للطلب الصادر إلى نقطة نهاية خطاف الويب.

  • يتم استبعاد المعلومات الحساسة مثل موقع مسار البيانات الاصطناعية. يمكن للمستخدمين والكيانات ذات قوائم التحكم بالوصول المناسبة استخدام واجهات برمجة تطبيقات العميل أو REST للاستعلام عن تسجيل النموذج للحصول على هذه المعلومات.
  • الحمولات غير مشفرة. راجع الأمان للحصول على معلومات حول كيفية التحقق من أن Azure Databricks هو مصدر خطاف الويب.
  • يسهل text الحقل تكامل Slack. لإرسال رسالة Slack، قم بتوفير نقطة نهاية Slack webhook كعنون URL لخطاف الويب.

حمولة إخطار على الويب لسجل الوظائف

تعتمد حمولة خطاف الويب الخاص بسجل الوظيفة على نوع المهمة ويتم إرسالها إلى jobs/run-now نقطة النهاية في مساحة العمل الهدف.

مهام ذات مهمة واحدة

تحتوي المهام أحادية المهمة على واحدة من ثلاث حمولات استنادا إلى نوع المهمة.

مهام عجلة دفتر الملاحظات وPython

تحتوي مهام عجلة دفتر الملاحظات وPython على حمولة 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هذا الحقل ، ويجب على الخادم الوجهة تعطيل التحقق من صحة الشهادة.

لأغراض الأمان، توصي Databricks بإجراء التحقق من صحة البيانات السرية مع الجزء المشفر بواسطة 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 التي تحتاج إلى السماح بها.

تسجيل التدقيق

إذا تم تمكين تسجيل التدقيق لمساحة العمل الخاصة بك، يتم تضمين الأحداث التالية في سجلات التدقيق:

  • إنشاء إخطار على الويب
  • تحديث خطاف الويب
  • سرد خطاف الويب
  • حذف خطاف الويب
  • اختبار خطاف الويب
  • مشغل خطاف الويب

تسجيل تدقيق مشغل Webhook

بالنسبة للإخطارات على الويب مع نقاط نهاية HTTP، يتم تسجيل طلب HTTP المرسل إلى عنوان URL المحدد لخطاف الويب جنبا إلى جنب مع عنوان URL enable_ssl_verification والقيم.

بالنسبة للإخطارات على الويب مع مشغلات الوظائف، job_id يتم تسجيل القيم و workspace_url .

الأمثلة

يتضمن هذا القسم ما يلي:

  • مثال على سير عمل خطاف الويب الخاص بسجل HTTP.
  • مثال على سير عمل الإخطار على الويب لسجل الوظيفة.
  • مثال على خطافات الويب.
  • مثالان لدفاتر الملاحظات: واحد يوضح واجهة برمجة تطبيقات REST، والآخر يوضح عميل Python.

مثال على سير عمل خطاف الويب لسجل HTTP

1. إنشاء إخطار على الويب

عندما تكون نقطة نهاية HTTPS جاهزة لتلقي طلب حدث الإخطار على الويب، يمكنك إنشاء خطاف ويب باستخدام واجهة برمجة تطبيقات REST لخطاف الويب 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 موجودا، فإن السلوك الافتراضي هو تشغيل وظيفة في نفس مساحة العمل مثل خطاف الويب.

المتطلبات

  • وظيفة موجودة.
  • رمز مميز للوصول الشخصي. لاحظ أن رموز الوصول المميزة غير مضمنة في كائن webhook الذي تم إرجاعه بواسطة واجهات برمجة التطبيقات.

إشعار

كأفضل ممارسة أمان، عند المصادقة باستخدام الأدوات والأنظمة والبرامج النصية والتطبيقات التلقائية، توصي 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 لسجل نموذج MLflow

الحصول على دفتر الملاحظات

MLflow Model Registry webhooks Python client example notebook

الحصول على دفتر الملاحظات