حدود معدل Hub

لحماية سلامة منصتنا وضمان إتاحتها لأوسع شريحة ممكنة من أعضاء مجتمع الذكاء الاصطناعي، نفرض حدود معدل على جميع الطلبات المرسلة إلى Hugging Face Hub.

نعرّف حدود معدل مختلفة لفئات مختلفة من الطلبات. نميّز بين ثلاث فئات رئيسية:

• Hub APIs
  • مثلًا، البحث عن نموذج أو مجموعة بيانات، إنشاء مستودع، إدارة المستخدمين، وما إلى ذلك. جميع نقاط النهاية التي تنتمي إلى هذه الفئة موثقة في نقاط نهاية واجهة برمجة تطبيقات Hub.
• Resolvers
  • إنها جميع الروابط التي تحتوي على مقطع /resolve/ في مسارها، والتي تخدم المحتوى الذي أنشأه المستخدمون من Hub. وبشكل محدد، تلك هي الروابط التي تُنشأ بواسطة المكتبات مفتوحة المصدر (transformers، datasets، vLLM، llama.cpp، …) أو تطبيقات الذكاء الاصطناعي (LM Studio، Jan، ollama، …) لتنزيل ملفات النماذج/المجموعات من HF.
  • تحديداً، هذا هو نقطة نهاية “Resolve a file” الموثقة في مواصفة OpenAPI الخاصة بنا.
  • تُستخدم طلبات Resolve على نطاق واسع من قبل المجتمع، وبما أننا نُحسّن بنيتنا التحتية لتقديمها بأقصى كفاءة، فإن حدود المعدل الخاصة بـ Resolvers هي الأعلى.
• Pages
  • جميع صفحات الويب التي نستضيفها على huggingface.co.
  • عادةً ما تُرسل طلبات تصفح الويب من قِبل البشر، لذا لا تحتاج حدود المعدل إلى أن تكون عالية كما هو الحال في نقاط النهاية البرمجية المذكورة أعلاه.

تُعرَّف جميع القيم على نوافذ زمنية مدتها خمس دقائق، مما يسمح بدرجة معينة من "التقلبات" من وجهة نظر التطبيق أو المطوّر.

إذا كنتَ أنت، أو مؤسستك، أو تطبيقك بحاجة إلى حدود معدل أعلى، فنشجعك على ترقية حسابك إلى PRO أو Team أو Enterprise. نُعطي الأولوية لطلبات الدعم من عملاء PRO وTeam وEnterprise – راجع الحدود المدمجة في مستويات حدود المعدل.

لوحة الفوترة

في أي وقت، يمكنك التحقق من حالة حد المعدل الخاص بك على صفحة الفوترة الخاصة بك (أو بمنظمتك): https://huggingface.co/settings/billing

على الجانب الأيمن، ستلاحظ ثلاثة مقاييس، مقياس واحد لكل دلو من دلاء الطلبات.

تعرض كل حاوية عدد الطلبات الحالية (آخر 5 دقائق)، وعدد الطلبات المسموح بها بناءً على خطة حساب المستخدم أو خطة المؤسسة الخاصة بك.

في كل مرة تتجاوز فيها الحد خلال الدقائق الخمس الماضية (يتم تحديث العرض في الوقت الفعلي)، سيتحول الشريط إلى اللون الأحمر.

ملاحظة: يمكنك استخدام مبدّل السياق للتبديل بسهولة بين حساب المستخدم الخاص بك ومنظماتك.

ترويسات HTTP

عندما تصل أنت أو مؤسستك إلى حد المعدل، ستتلقى خطأ HTTP 429 Too Many Requests.

ننفذ الآلية الموصوفة في مسودة IETF (الإصدار 9) بعنوان “حقول ترويسة HTTP الخاصة بـ RateLimit” (المعروفة أيضًا باسم draft-ietf-httpapi-ratelimit-headers).

الهدف هو تحديد ترويسات HTTP موحّدة يمكن للخوادم استخدامها للإعلان عن سياسات الحصص/معدلات التقييد، وإبلاغ العملاء بالاستخدام الحالي/الحدود، حتى يتمكنوا من تجنب التقييد.

تحديداً، ننفذ الترويسات التالية:

الترويسة	الغرض / المعنى
RateLimit	الحد الأقصى المسموح به لمعدل الطلبات في النافذة الزمنية الحالية. “عدد الطلبات (من هذا النوع) المسموح لك بتنفيذها.”
RateLimit-Policy	يحمل سياسة حد المعدل نفسها (مثلًا “100 طلبات خلال 5 دقائق”). وهو ذو طابع إخباري؛ يُظهر السياسة التي يخضع لها العميل.

يُعدّ مجموعة من الأمثلة على النحو التالي:

الترويسة	مثال
RateLimit	"api\|pages\|resolvers";r=[remaining];t=[seconds remaining until reset]
RateLimit-Policy	"fixed window";"api\|\pages\|resolvers";q=[total allowed for window];w=[window duration in seconds]

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

إليك حدود المعدل الحالية (في سبتمبر 2025) بناءً على خطتك:

الخطة	واجهة برمجة التطبيقات	المُحلِّلات	الصفحات
مستخدم مجهول (حسب عنوان IP)	500 *	3,000 *	100 *
مستخدم مجاني	1,000 *	5,000 *	200 *
مستخدم PRO	2,500	12,000	400
تنظيم الفريق	3,000	20,000	400
منظمة المؤسسات	6,000	50,000	600
منظمة Enterprise Plus	10,000	100,000	1,000
منظمة Enterprise Plus مع تفعيل “حدود معدل Hub الأعلى”	100,000	500,000	10,000
منظمة Academia Hub	3,000	20,000	400

* تخضع الحسابات المجهولة والمستخدمون المجانيون للتغيير随着 مرور الوقت اعتمادًا على صحة المنصة 🤞

تُحسب جميع الحصص على نوافذ ثابتة مدتها 5 دقائق.

ملاحظة: بالنسبة للمنظمات، تُطبَّق حدود المعدل على كل عضو على حدة، ولا تُشارك بين الأعضاء.

ماذا لو واجهتُ حدًّا لمعدل الطلبات

أولاً، تأكد من أنك تمرر دائمًا HF_TOKEN، وأنه يُمرَّر إلى جميع المكتبات أو التطبيقات التي تُحمِّل محتوى من Hub.

هذا هو السبب الأول الذي يجعل المستخدمين يواجهون حدود المعدل، وهو إصلاح سهل للغاية.

على الرغم من تمرير HF_TOKEN، إذا كنت لا تزال مقيدًا بمعدل الطلبات، يمكنك:

• وزّع طلباتك على فترات زمنية أطول
• استبدل استدعاءات واجهة برمجة تطبيقات Hub باستدعاءات Resolver كلما أمكن ذلك (فحدود معدل Resolver أعلى بكثير وأكثر تحسينًا).
• الترقية إلى PRO أو Team أو Enterprise.

التعامل الذكي مع حدود المعدل باستخدام huggingface_hub

تتضمن مكتبة Python الخاصة بالـ Hub huggingface_hub (الإصدار 1.2.0+) معالجة ذكية لإعادة المحاولة في أخطاء حدود المعدل.

عند حدوث خطأ 429، يقوم SDK تلقائيًا بتحليل الترويسة RateLimit لاستخراج عدد الثواني الدقيق حتى إعادة تعيين حد المعدل، ثم ينتظر تلك المدة بالضبط قبل إعادة المحاولة. ينطبق هذا على تنزيلات الملفات (أي Resolvers) واستدعاءات واجهة API الخاصة بالمركز المقسّمة إلى صفحات (قوائم النماذج، مجموعات البيانات، المساحات، إلخ).

نوصي بشدة باستخدام huggingface_hub للوصول البرمجي إلى Hub للاستفادة من سلوك إعادة المحاولة المحسّن هذا وتجنب تنفيذ معالجة مخصصة لمعدلات الحد.

حدود معدل الاستخدام التفصيلية لأفعال المستخدم

بالإضافة إلى تلك الفئات الرئيسية من حدود المعدل، نفرض حدودًا على أنواع محددة معينة من إجراءات المستخدم، مثل:

• إنشاء المستودع
• التزامات المستودع
• المناقشات والتعليقات
• إجراءات الإشراف
• إلخ.

لا نقوم حاليًا بتوثيق حدود المعدل لتلك الإجراءات المحددة، نظرًا لأنها تميل إلى التغيير بشكل متكرر مع مرور الوقت. إذا واجهت أخطاء تتعلق بالحصة، نشجعك على ترقية حسابك إلى PRO أو Team أو Enterprise. لا تتردد في التواصل معنا عبر فريق الدعم.

Update on GitHub