Webhooks

تُعدّ Webhooks أساسًا للميزات المتعلقة بـ MLOps. فهي تتيح لك الاستماع إلى التغييرات الجديدة في مستودعات محددة أو في جميع المستودعات التابعة لمجموعة معينة من المستخدمين/المنظمات (وليس مستودعاتك فقط، بل أي مستودع).

يمكنك استخدامهم لتحويل النماذج تلقائيًا، أو بناء روبوتات مجتمعية، أو بناء خطوط تكامل/اختبار مستمر (CI/CD) لنماذجك ومجموعات بياناتك ومساحاتك (Spaces) ودلاء التخزين (buckets) (وغير ذلك الكثير!). كما يمكن للخطافات (Webhooks) أن تُطلق مهام (Jobs) لأتمتة مهام الحساب استجابةً لأحداث المستودعات.

توجد وثائق Webhooks أدناه – أو يمكنك أيضًا تصفح أدلة التي تُظهر بعض حالات الاستخدام الممكنة لـ Webhooks:

• قُم بتدريب نموذج جديد كل ما يتم تحديث مجموعة البيانات (بايثون)
• إنشاء بوت نقاش على Hub باستخدام واجهة برمجة تطبيقات LLM (NodeJS)
• إنشاء تقارير جودة البيانات الوصفية (Python)
• معالجة ملفات جديدة في دلو باستخدام Jobs (CLI)
• والمزيد قادم…

إنشاء Webhook الخاص بك

يمكنك إنشاء نقاط Webhooks جديدة وتعديل الموجودة منها في الإعدادات الخاصة بنقاط Webhooks لديك:

يمكن لـ Webhooks مراقبة تحديثات المستودعات، وطلبات الدمج (Pull Requests)، والمناقشات، والتعليقات الجديدة. بل إنه من الممكن إنشاء مساحة (Space) للتفاعل مع Webhooks الخاصة بك!

حمولات Webhook

بعد تسجيل Webhook، سيتم إشعارك بالأحداث الجديدة عبر استدعاء HTTP POST على عنوان URL المستهدف المحدد. يتم ترميز الحمولة بتنسيق JSON.

يمكنك عرض سجل الأحمال المرسلة في تبويب النشاط في صفحة إعدادات الويب هوك، كما يُمكنك إعادة تشغيل الويب هوكات السابقة لتسهيل عملية تصحيح الأخطاء:

كمثال، فيما يلي الحمولة الكاملة عند فتح طلب سحب:

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    // Note: when `hidden` is `true`, `content` will be undefined
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

حدث

الخاصية العليا event محددة دائمًا وتُستخدم لتحديد طبيعة الحدث.

لديه خاصيتان فرعيتان: event.action وevent.scope.

event.scope ستكون إحدى القيم التالية:

• "repo" - الأحداث العامة على المستودعات. القيم الممكنة للمعامل action المرتبط: "create"، "delete"، "update"، "move".
• "repo.content" - الأحداث المتعلقة بمحتوى المستودع، مثل الالتزامات الجديدة أو الوسوم. كما يُطلق عند إنشاء طلبات سحب جديدة بسبب المرجع/الالتزام الجديد الذي يتم إنشاؤه. أما بالنسبة للحاويات، فيُطلق عند إضافة الملفات أو حذفها بدلاً من مراجع Git. والإجراء المرتبط action هو دائماً "update".
• "repo.config" - الأحداث المتعلقة بالإعدادات: تحديث أسرار المساحة، تحديث الإعدادات، تحديث معرفات DOI، أو ما إذا كانت معطّلة أم لا، وما إلى ذلك. الإجراء action المرتبط بها هو دائمًا "update".
• "discussion" - إنشاء نقاش أو طلب سحب، وتحديث العنوان أو الحالة، والدمج. القيم الممكنة للـaction المرتبط: "create"، "delete"، "update".
• "discussion.comment" - إنشاء تعليق أو تحديثه أو إخفاؤه. القيم الممكنة للمعامل action المرتبط به: "create"، "update".

يمكن إضافة نطاقات أخرى في المستقبل. للتعامل مع الأحداث غير المعروفة، يمكن لمعالج الويب هوك الخاص بك اعتبار أي إجراء على نطاق أضيق أنه إجراء "update" على النطاق الأوسع.

على سبيل المثال، إذا أُضيف نطاق "repo.config.dois" في المستقبل، فيمكن لمعالج الويب هوك الخاص بك اعتبار أي حدث بهذا النطاق إجراء "update" على نطاق "repo.config".

المستودع

في الإصدار الحالي من webhooks، يُحدَّد دائمًا الخاصية العلوية repo، إذ يمكن دائمًا ربط الأحداث بمستودع. على سبيل المثال، فكّر في القيمة التالية:

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha هو معرف sha لأحدث التزام على فرع main في المستودع. يُرسل هذا المعرف فقط عندما يبدأ event.scope بـ "repo"، وليس في أحداث المجتمع مثل النقاشات والتعليقات، وليس في الدلاء التي لا تملك تاريخ Git.

تغييرات الكود

عند حدوث تغييرات في الكود، يُحدَّد الخاصية العلوية updatedRefs على أحداث المستودع. وهي مصفوفة من المراجع التي تم تحديثها. إليك مثالاً على القيمة:

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

ستكون قيمة oldSha في المراجع الجديدة المُنشأة null. وستكون قيمة newSha في المراجع المحذوفة null.

يمكنك الرد على التزامات الجديدة في طلبات الدمج المحددة، أو على الوسوم الجديدة، أو على الفروع الجديدة.

الدلاء

لا تُعدّ Buckets مستودعات Git: فهي لا تحتوي على أي التزامات أو فروع أو وسوم. تستخدم أحداث دورة الحياة (create، delete، move، وتحديثات الإعدادات مثل مستوى الظهور) النطاقات "repo" / "repo.config" نفسها المستخدمة في أنواع المستودعات الأخرى.

تستخدم تغييرات الملفات "repo.content"، لكن الحمولة تحتوي على خاصية updatedFiles بدلاً من updatedRefs. يتم الإبلاغ عن الكتابة فوق ملف موجود كـ "add". فيما يلي مثال على الحمولة بعد إضافة ملف وحذف آخر:

{
  "event": {
    "action": "update",
    "scope": "repo.content"
  },
  "repo": {
    "type": "bucket",
    "name": "some-user/some-bucket",
    "id": "6366c000a2abcdf2fd69a080",
    "private": false,
    "url": {
      "web": "https://huggingface.co/buckets/some-user/some-bucket",
      "api": "https://huggingface.co/api/buckets/some-user/some-bucket"
    },
    "owner": {
      "id": "61d2000c3c2083e1c08af22d"
    }
  },
  "updatedFiles": [
    {
      "path": "data/train.txt",
      "action": "add",
      "xetHash": "55faef2f2f80cd1a087c35b729f228960739441d38073cd5aa4320751e137166",
      "size": 20
    },
    {
      "path": "data/old.txt",
      "action": "delete"
    },
    ...
  ],
  "updatedFilesTruncated": true,
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

عند تجاوز 10,000 إدخال، يتم تقصير القائمة ويُضبط updatedFilesTruncated على true. في هذه الحالة، قم بتعداد الدلو للحصول على الصورة الكاملة.

لا تحتوي الأوعية (Buckets) على نقاشات أو طلبات سحب (Pull Requests)، لذا لن تستقبل أحداث "discussion" و"discussion.comment" بشأنها أبدًا.

إذا كنت ترغب في أن يتتبع العميل تغييرات ملفات الدلو مباشرةً بدلاً من ذلك عبر استدعاء غير متزامن إلى خادمك الخاص، فإن الدلاء تعرض أيضًا بث متابعة مباشر.

تغييرات الإعداد

عندما تكون الخاصية العليا event.scope هي "repo.config"، يتم تحديد الخاصية updatedConfig. وهي كائن يحتوي على الإعدادات المحدّثة. فيما يلي مثال على القيمة:

"updatedConfig": {
  "private": false
}

عندما لا يدعم خطاف الويب مفتاح الإعداد المحدّث، سيكون الكائن فارغاً:

"updatedConfig": {}

حاليًا، يُدعم المفتاح private فقط. إذا كنت ستستفيد من وجود مفاتيح إعداد إضافية هنا، فيرجى إعلامنا عبر website@huggingface.co.

المناقشات وطلبات الدمج

يُحدَّد الخاصية العليا discussion على الأحداث المجتمعية (المناقشات وطلبات الدمج). الخاصية discussion.isPullRequest هي قيمة منطقية تشير إلى ما إذا كانت المناقشة طلب دمج أيضًا (على المنصة، يُعد طلب الدمج نوعًا خاصًا من المناقشات). إليك مثالًا على قيمة:

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

تعليق

يتم تحديد الخاصية comment على المستوى الأعلى عند إنشاء تعليق (بما في ذلك عند إنشاء نقاش) أو تحديثه. فيما يلي مثال على قيمة:

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

سر Webhook

يُعدّ تعيين سرّ Webhook مفيدًا للتأكد من أن الأحمال (payloads) المُرسلة إلى عنوان URL الخاص بمعالج Webhook الخاص بك صادرة فعليًا من Hugging Face.

إذا قمت بتعيين سر لـ Webhook الخاص بك، فسيتم إرساله مع كل طلب كعنوان HTTP يحمل اسم X-Webhook-Secret. يتم دعم أحرف ASCII فقط.

من الممكن أيضًا إضافة السر مباشرةً في عنوان URL الخاص بالمعالج. على سبيل المثال، عن طريق تعيينه كمتغير استعلام: https://example.com/webhook?secret=XXX.

قد يكون هذا مفيدًا إذا كان الوصول إلى ترويسات HTTP للطلب معقدًا لمعالج Webhook الخاص بك.

التسليم والمحاولات

تُسلَّم حمولات Webhook بشكل غير متزامن، بعد وقت قصير من وقوع الحدث على Hub. لا يُكفَل ترتيب التسليم: إذا وقعت عدة أحداث متقاربة في الوقت، فقد تصل خارج الترتيب.

يجب أن يُقرّ مُعالجك بالاستلام برمز حالة 2xx. يُحتسب أي رمز حالة آخر كاستلام فاشل، تمامًا مثل خطأ الاتصال: إذ يُعاد إرساله مع تراجع تدريجي. إذا كانت المعالجة بطيئة، فاستجب برمز 2xx فورًا وأدِّ العمل بشكل غير متزامن، حتى لا يُعتبر الاستلام فاشلًا.

يتميز كل تسليم برأس HTTP فريد هو Webhook-Id. تعيد محاولات إعادة التسليم الفاشل استخدام المعرف نفسه، لذا يمكنك اعتباره مفتاحًا للتعامل مع الأحداث مرة واحدة فقط ومعالجة كل حدث مرة واحدة.

عند استمرار فشل التسليمات إلى Webhook، يتم إيقاف Webhook تلقائيًا وإشعار مالكه عبر البريد الإلكتروني. يمكنك استكشاف المشكلة وإعادة تفعيله من الإعدادات الخاصة بـ Webhooks لديك.

الحد من معدل الطلبات

يخضع كل Webhook لحد أقصى قدره 1,000 تشغيل خلال 24 ساعة. يمكنك عرض استخدامك في صفحة إعدادات Webhook في تبويب “Activity”.

إذا كنت بحاجة إلى زيادة عدد المحفّزات الخاصة بـ Webhook، فقم بالترقية إلى PRO أو Team أو Enterprise وتواصل معنا عبر website@huggingface.co.

تطوير Webhooks الخاصة بك

إذا لم يكن لديك نقطة نهاية/رابط HTTPS، يمكنك تجربة أدوات عامة لاختبار الـ webhook. تعمل هذه الأدوات كقاطعة شاملة (تلتقط جميع الطلبات) المرسلة إليها وتعيد رمز الحالة 200 OK. Beeceptor هو أحد الأدوات التي يمكنك استخدامها لإنشاء نقطة نهاية HTTP مؤقتة ومراجعة الحمولة الواردة. أداة أخرى من هذا النوع هي Webhook.site.

بالإضافة إلى ذلك، يمكنك توجيه حمولة Webhook حقيقية إلى الكود الذي يعمل محليًا على جهازك أثناء التطوير. هذه طريقة رائعة للاختبار وتصحيح الأخطاء لتحقيق تكاملات أسرع. يمكنك القيام بذلك عن طريق تعريض منفذ localhost الخاص بك للإنترنت. ولتتمكن من اتباع هذا المسار، يمكنك استخدام ngrok أو localtunnel.

استكشاف أخطاء Webhooks

يمكنك بسهولة العثور على الأحداث التي تم توليدها مؤخراً لخطوط الويب الخاصة بك. افتح تبويب النشاط لخط الويب الخاص بك. ستجد هناك قائمة بالأحداث الأخيرة.

هنا يمكنك مراجعة رمز حالة HTTP ومحمول الأحداث المولّدة. بالإضافة إلى ذلك، يمكنك إعادة تشغيل هذه الأحداث بالنقر على زر Replay!

ملاحظة: عند تغيير عنوان URL أو كلمة المرور الخاصة بـ Webhook، فإن إعادة تشغيل حدث ما ستؤدي إلى إرسال الحمولة إلى العنوان المحدّث.

ملاحظة: يُرسل الحدث المُعاد مع Webhook-Id نفسه الذي كان عليه التسليم الأصلي.

الأسئلة الشائعة

هل يمكنني تعريف خطافات الويب (webhooks) على مستوى منظمّتي بدلاً من حسابي الشخصي؟

لا، هذا غير مدعوم حاليًا.

كيف يمكنني الاشتراك في جميع الأحداث على HF (أو عبر نوع مستودع كامل، مثل جميع النماذج)؟

لا يتم عرض هذا الخيار حاليًا للمستخدمين النهائيين، لكن يمكننا تفعيله لك إذا أرسلت بريدًا إلكترونيًا إلى website@huggingface.co.