Webhooks

تُعدّ Webhooks أساسًا للميزات المتعلقة بـ MLOps. فهي تتيح لك الاستماع إلى التغييرات الجديدة في مستودعات محددة، أو في جميع المستودعات التابعة لمستخدمين أو منظمات معينة ترغب في متابعتها. سيشرح هذا الدليل أولًا كيفية إدارة Webhooks برمجيًا. ثم سنرى كيف نستفيد من huggingface_hub لإنشاء خادم يستمع إلى Webhooks ونشره على Space.

يفترض هذا الدليل أنك على دراية بمفهوم خطافات الويب (webhooks) على Huggingface Hub. للتعرف على المزيد حول خطافات الويب نفسها، ينبغي عليك قراءة هذا الدليل أولاً.

إدارة الخطافات

huggingface_hub يتيح لك إدارة webhooks الخاصة بك برمجياً. يمكنك عرض قائمة بـ webhooks الموجودة لديك، وإنشاء أخرى جديدة، وتحديثها أو تفعيلها أو تعطيلها أو حذفها. يوجهك هذا القسم عبر الإجراءات باستخدام دوال واجهة برمجة التطبيقات (API) الخاصة بـ Hugging Face Hub.

إنشاء خطاف ويب

لإنشاء webhook جديد، استخدم create_webhook() وحدد عنوان URL الذي يجب إرسال الحمولة إليه، والأحداث التي يجب مراقبتها، مع إمكانية تعيين نطاق وسرّ للأمان بشكل اختياري.

from huggingface_hub import create_webhook

# Example: Creating a webhook
webhook = create_webhook(
    url="https://webhook.site/your-custom-url",
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

يمكن أن يُطلق webhook أيضًا مهمة (Job) لتنفيذها على بنية Hugging face التحتية بدلاً من إرسال الحمولة (payload) إلى عنوان URL. في هذه الحالة، تحتاج إلى تمرير المعرّف (ID) لمهمة المصدر (source Job).

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

يُطلق الـ webhook مهمة الـ Job باستخدام حمولة الـ webhook في متغير البيئة WEBHOOK_PAYLOAD. لا يتم نسخ أسرار المهمة المصدرية إلى الـ webhook. إذا كانت المهمة المُطلقة تحتاج إلى أسرار (مثل HF_TOKEN)، فمررها باستخدام secrets={"HF_TOKEN": "hf_***"}. عند استخدام update_webhook()، يجب عليك تمرير job_id مع secrets. تحل الأسرار المذكورة محل القيم المخزنة، ويُحذف السر إذا كان نصاً فارغاً، وتُحفظ جميع الأسرار الأخرى. لمزيد من المعلومات حول Hugging Face Jobs، والأجهزة المتاحة (CPU، GPU)، وسكربتات UV، راجع توثيق Jobs.

قائمة خطافات الويب

لعرض جميع الخطافات (webhooks) التي قمت بإعدادها، يمكنك إدراجها باستخدام list_webhooks(). وهذا مفيد لمراجعة معرفاتها وعناوينها (URLs) وحالاتها.

from huggingface_hub import list_webhooks

# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
    print(webhook)

تحديث خطاف ويب

إذا كنت بحاجة إلى تغيير تكوين webhook موجود، مثل عنوان URL أو الأحداث التي يراقبها، يمكنك تحديثه باستخدام update_webhook().

from huggingface_hub import update_webhook

# Example: Updating a webhook
updated_webhook = update_webhook(
    webhook_id="your-webhook-id",
    url="https://new.webhook.site/url",
    watched=[{"type": "user", "name": "new-username"}],
    domains=["repo"]
)

تفعيل وإلغاء تفعيل الخطافات

قد ترغب في تعطيل خطاف ويب مؤقتًا دون حذفه. يمكن القيام بذلك باستخدام disable_webhook()، ويمكن إعادة تفعيل الخطاف لاحقًا باستخدام enable_webhook().

from huggingface_hub import enable_webhook, disable_webhook

# Example: Enabling a webhook
enabled_webhook = enable_webhook("your-webhook-id")
print("Enabled:", enabled_webhook)

# Example: Disabling a webhook
disabled_webhook = disable_webhook("your-webhook-id")
print("Disabled:", disabled_webhook)

حذف خطاف ويب

عندما لم يعد هناك حاجة إلى خطاف ويب (webhook)، يمكن حذفه بشكل دائم باستخدام delete_webhook().

from huggingface_hub import delete_webhook

# Example: Deleting a webhook
delete_webhook("your-webhook-id")

إدارة خطافات الويب من سطر الأوامر

جميع العمليات المذكورة أعلاه متاحة أيضًا من واجهة سطر الأوامر hf. وهذا مفيد بشكل خاص لأتمتة المهام عبر السكربتات وسير العمل الوكيلي.

# List all webhooks
>>> hf webhooks ls

# Get details about a specific webhook
>>> hf webhooks info <webhook_id>

# Create a webhook that pings a URL
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased --domain repo

# Create a webhook that triggers a Job
>>> hf webhooks create --job-id <job_id> --watch user:julien-c

# Create a webhook that triggers a Job with your HF token as a secret
>>> hf webhooks create --job-id <job_id> --watch bucket:my-org/my-bucket --secrets HF_TOKEN

# Update an existing webhook
>>> hf webhooks update <webhook_id> --url https://new-url.com/hook

# Enable / disable a webhook
>>> hf webhooks enable <webhook_id>
>>> hf webhooks disable <webhook_id>

# Delete a webhook (with confirmation prompt)
>>> hf webhooks delete <webhook_id>

يستخدم الخيار --watch التنسيق type:name حيث يكون النوع أحد model أو dataset أو space أو org أو user. يمكن تكراره لمراقبة عدة عناصر. للحصول على القائمة الكاملة للخيارات، شغّل hf webhooks <command> --help. لمزيد من التفاصيل، راجع دليل سطر الأوامر.

خادم Webhooks

الفئة الأساسية التي سنستخدمها في قسم هذا الدليل هي WebhooksServer(). وهي فئة تتيح تكوين خادم بسهولة يمكنه استقبال خطافات الويب (webhooks) من Huggingface Hub. يعتمد الخادم على تطبيق Gradio. ويتضمن واجهة مستخدم لعرض التعليمات لك أو لمستخدميك، وواجهة برمجة تطبيقات (API) للاستماع إلى خطافات الويب.

للاطلاع على مثال عملي لخادم ويبهوك قيد التشغيل، راجع Spaces CI Bot. إنه مساحة تُطلق بيئات مؤقتة عند فتح طلب سحب على مساحة.

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

إنشاء نقطة نهاية

إن تنفيذ نقطة نهاية webhook بسيطة إلى حدّ تزيين دالة. دعونا ننظر إلى مثال أولي لتوضيح المفاهيم الرئيسية:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

احفظ هذا المقطع في ملف باسم 'app.py' وشغّله باستخدام 'python app.py'. يجب أن ترى رسالة مشابهة لهذه:

Webhook secret is not defined. This means your webhook endpoints will be open to everyone.
To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization:
        `app = WebhooksServer(webhook_secret='my_secret', ...)`
For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret.
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://1fadb0f52d8bf825fc.gradio.live

This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces

Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
Go to https://huggingface.co/settings/webhooks to setup your webhooks.

أحسنت! لقد أطلقتَ خادم ويب هوك للتو. دعنا نفكك ما حدث بالضبط:

1. عند تزيين دالة بـ webhook_endpoint()، يتم إنشاء كائن WebhooksServer() في الخلفية. كما ترون، هذا الخادم هو تطبيق Gradio يعمل على http://127.0.0.1:7860. إذا فتحت هذا الرابط في متصفحك، فسترى صفحة هبوط تحتوي على تعليمات حول الخطافات (webhooks) المسجلة.
2. تعمل تطبيقات Gradio في الخلفية كخوادم FastAPI. وقد أُضيفت إليها نقطة نهاية POST جديدة /webhooks/trigger_training. هذه هي النقطة النهائية التي ستستمع إلى webhooks وتشغّل دالة trigger_training عند تفعيلها. سيقوم FastAPI بتحليل الحمولة تلقائيًا ومرورها إلى الدالة ككائن WebhookPayload. هذا كائن pydantic يحتوي على جميع المعلومات المتعلقة بالحدث الذي فعّل الـ webhook.
3. فتحت تطبيق Gradio أيضًا نفقًا لاستقبال الطلبات من الإنترنت. وهذا هو الجزء المثير للاهتمام: يمكنك تكوين Webhook على https://huggingface.co/settings/webhooks يشير إلى جهازك المحلي. وهذا مفيد لتصحيح أخطاء خادم الـ webhook لديك والتكرار بسرعة قبل نشره على Space.
4. أخيرًا، تُخبرك السجلات أيضًا بأن خادمك غير محمي حاليًا بكلمة مرور سرية. هذا ليس مشكلة في حالة التصحيح المحلي، لكن يجب وضعه في الاعتبار لاحقًا.

بشكل افتراضي، يتم تشغيل الخادم في نهاية سكربتك. إذا كنت تشغّله في دفتر ملاحظات، يمكنك بدء تشغيل الخادم يدوياً عن طريق استدعاء decorated_function.launch(). وبما أنه يتم استخدام خادم فريد، فلا يتعين عليك بدء تشغيل الخادم إلا مرة واحدة حتى لو كان لديك نقاط نهاية متعددة.

إعداد Webhook

الآن وقد أصبحت لديك خادم Webhook قيد التشغيل، تريد تكوين Webhook لبدء استلام الرسائل. انتقل إلى https://huggingface.co/settings/webhooks، وانقر على “إضافة Webhook جديد” وقم بتكوين Webhook الخاص بك. حدد المستودعات المستهدفة التي تريد مراقبتها وعنوان Webhook، وهو هنا https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

وهذا كل ما في الأمر! يمكنك الآن تفعيل ذلك الخطاف البرمجي (webhook) من خلال تحديث المستودع المستهدف (مثل دفع التزامن). تحقق من تبويب النشاط الخاص بخطافك البرمجي لرؤية الأحداث التي تم تفعيلها. الآن وقد حصلت على إعداد يعمل، يمكنك اختباره والتكرار بسرعة. إذا قمت بتعديل كودك وإعادة تشغيل الخادم، فقد يتغير عنوانك العام. تأكد من تحديث إعدادات الخطاف البرمجي على Hub عند الحاجة.

النشر إلى مساحة

الآن وقد أصبحت لديك خادم Webhook يعمل، فإن الهدف هو نشره على Space. انتقل إلى https://huggingface.co/new-space لإنشاء Space. أعطِه اسمًا، واختر Gradio SDK ثم انقر على “Create Space”. ارفع كودك إلى Space في ملف يُسمى app.py. سيبدأ Space الخاص بك تلقائيًا! لمزيد من التفاصيل حول Spaces، يُرجى الرجوع إلى هذا الدليل.

يعمل خادم الويب هوك الخاص بك الآن على مساحة عامة. في معظم الحالات، ستحتاج إلى تأمينه بسِرّ. انتقل إلى إعدادات مساحتك > القسم “Repository secrets” > “Add a secret”. اضبط متغير البيئة WEBHOOK_SECRET على القيمة التي تختارها. عد إلى إعدادات الويب هوك واضبط السِرّ في تكوين الويب هوك. الآن، لن يقبل خادمك إلا الطلبات التي تحمل السِرّ الصحيح.

وهذا كل شيء! أصبح مساحتك الآن جاهزة لاستقبال خطافات الويب (webhooks) من Hub. يرجى ملاحظة أنه إذا كنت تشغّل المساحة على عتاد مجاني من نوع ‘cpu-basic’، فسيتم إيقاف تشغيلها بعد 48 ساعة من عدم النشاط. إذا كنت بحاجة إلى مساحة دائمة، فيجب عليك النظر في الترقية إلى عتاد محسّن.

الاستخدام المتقدم

شرح الدليل أعلاه أسرع طريقة لإعداد WebhooksServer(). في هذا القسم، سنرى كيف يمكننا تخصيصه بشكل أكبر.

نقاط نهاية متعددة

يمكنك تسجيل نقاط نهاية متعددة على نفس الخادم. على سبيل المثال، قد ترغب في وجود نقطة نهاية واحدة لتفعيل مهمة تدريب وأخرى لتفعيل تقييم نموذج. يمكنك القيام بذلك بإضافة عدة زخارف @webhook_endpoint:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload) -> None:
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

@webhook_endpoint
async def trigger_evaluation(payload: WebhookPayload) -> None:
    if payload.repo.type == "model" and payload.event.action == "update":
        # Trigger an evaluation job if a model is updated
        ...

والذي سيُنشئ نقطتي نهاية:

(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation

خادم مخصص

للحصول على مرونة أكبر، يمكنك أيضًا إنشاء كائن WebhooksServer() مباشرة. وهذا مفيد إذا كنت ترغب في تخصيص الصفحة الرئيسية لخادمك. يمكنك القيام بذلك عن طريق تمرير Gradio UI ستحل محل الصفحة الافتراضية. على سبيل المثال، يمكنك إضافة تعليمات لمستخدميك أو إضافة نموذج لتفعيل الخطافات البرمجية يدويًا. عند إنشاء WebhooksServer()، يمكنك تسجيل خطافات برمجية جديدة باستخدام الزخرفة add_webhook().

إليك مثالًا كاملًا:

import gradio as gr
from fastapi import Request
from huggingface_hub import WebhooksServer, WebhookPayload

# 1. Define  UI
with gr.Blocks() as ui:
    ...

# 2. Create WebhooksServer with custom UI and secret
app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

# 3. Register webhook with explicit name
@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

# 4. Register webhook with implicit name
@app.add_webhook
async def goodbye(payload: WebhookPayload):
    return {"message": "goodbye"}

# 5. Start server (optional)
app.launch()

1. نعرف واجهة مستخدم مخصصة باستخدام Gradio blocks. ستُعرض هذه الواجهة على الصفحة الرئيسية للخادم.
2. ننشئ كائن WebhooksServer() بواجهة مستخدم مخصصة وسر. السر اختياري ويمكن تعيينه عبر متغير البيئة WEBHOOK_SECRET.
3. نُسجّل خط ويب (webhook) باسم صريح. سيؤدي هذا إلى إنشاء نقطة نهاية عند /webhooks/say_hello.
4. نُسجّل خط ويب (webhook) باسم ضمني. سيؤدي هذا إلى إنشاء نقطة نهاية عند /webhooks/goodbye.
5. نبدأ تشغيل الخادم. هذه خطوة اختيارية، إذ سيُشغَّل خادمك تلقائيًا في نهاية السكربت.