نادرًا ما تُنشر حدود معدل API بالوحدة التي تحتاجها فعلًا. فالحد الموثّق بعبارة "60 طلبًا في الدقيقة" لا يخبرك بالفاصل بالميلي ثانية الذي ينبغي انتظاره بين الاستدعاءات، والحد المعطى بالطلبات في اليوم لا يوضح ما يعنيه لدفعة من الطلبات في ثانية واحدة. تحوّل هذه الأداة بين الوحدات الأربع الشائعة وتضيف هامش أمان، فيكون الرقم الذي تحصل عليه رقمًا يمكنك أن تبني عليه محدِّد معدل بأمان.
كيف تعمل
أدخل الحد كما هو موثّق (قيمة ووحدة: في الثانية أو الدقيقة أو الساعة أو اليوم) ويُحوَّل أولًا إلى طلبات في الثانية، لأنها الوحدة المشتركة التي تُشتق منها بقية الأرقام.
يخفّض هامش الأمان الحد الأقصى النظري قبل تحويله إلى معدل مستمر وإلى حد أدنى للفاصل. وللهامش أهمية لأن دفعات الطلبات الفعلية، وانحراف الساعة بين خادمك ونافذة حد المعدل لدى API، وإعادة المحاولة بعد الأخطاء العابرة، يمكنها كلها أن تدفعك فوق حد تلتزم به من الناحية الفنية في المتوسط.
الحد الأدنى للفاصل بالميلي ثانية هو ما ستستخدمه فعلًا في الشيفرة، مثلًا كمدة التأخير في محدِّد من نوع token-bucket أو leaky-bucket، أو في `setTimeout` بسيط بين استدعاءات متتابعة.
مثال محلول
الحد البالغ 60 طلبًا في الدقيقة يساوي تمامًا طلبًا واحدًا في الثانية. ومع هامش أمان 15%، ينخفض المعدل المستمر الآمن إلى 0.85 طلب في الثانية، أي فاصل أدنى نحو 1,176 ms بين الطلبات، بدلًا من خفضه إلى 1,000 ms بالضبط.
أمثلة إضافية
حد 10,000 طلب في اليوم يبدو كبيرًا لكنه لا يتجاوز نحو 0.12 طلب في الثانية، أي طلبًا واحدًا تقريبًا كل 10 ثوانٍ مع هامش 15%. وستستغرق مهمة دفعية من 50,000 عنصر خمسة أيام عند هذا الحد.
أخطاء شائعة
- توزيع الحد اليومي بالتساوي بينما لدى المزوّد حدود في الدقيقة أيضًا.
- العمل عند 100% من الحد، فتتسبب أي دفعة مفاجئة في أخطاء 429.
- إعادة المحاولة فورًا بعد خطأ 429 بدل التمهّل والتراجع.
- نسيان حدود الرموز (tokens) في الدقيقة في واجهات الذكاء الاصطناعي، وهي كثيرًا ما تُبلَغ قبل حدود الطلبات.
أسئلة يطرحها الناس
لماذا نضيف هامش أمان أصلًا؟ أليس الحد الموثّق دقيقًا؟
هو دقيق عادةً بالنسبة للإنتاجية المتوسطة، لكن معظم واجهات API تطبّق الحدود على نافذة منزلقة أو ثابتة، وقد تتجاوز دفعة من الطلبات في بداية النافذة الحد حتى لو كان معدلك المتوسط ملتزمًا به من الناحية الفنية. ويُعدّ هامش من 10 إلى 20% ممارسة شائعة لمحدِّدات المعدل في الإنتاج.
كيف ينطبق هذا على واجهات الذكاء الاصطناعي مثل OpenAI وAnthropic وGemini؟
تطبّق واجهات LLM عادةً حدّين في آن واحد: الطلبات في الدقيقة (RPM) والرموز في الدقيقة (TPM). يتناول هذا المحوّل جانب RPM؛ أما القيد الفعلي في الممارسة فكثيرًا ما يكون TPM لا RPM، خاصة مع المطالبات أو الإجابات الكبيرة. تحقق من الحد الذي يصل إليه استخدامك أولًا قبل الاعتماد على أي من الرقمين وحده.
ما الفرق بين token-bucket والحد ذي النافذة الثابتة؟
الحد ذو النافذة الثابتة يُعاد ضبطه بالكامل عند بداية كل نافذة (مثلًا كل 60 ثانية)، مما يتيح إرسال دفعة تصل إلى الحد الكامل عند حدّ النافذة. أما token-bucket (أو النافذة المنزلقة) فيتجدد تدريجيًا، فيوزّع الطلبات بانتظام أكبر. و"المعدل المستمر الآمن" هنا يصلح للنوعين، لكن واجهات النافذة الثابتة تستفيد تحديدًا من هامش أكبر قرب حدود النوافذ.
تعطيني واجهة API حدودًا منفصلة لنقاط نهاية مختلفة. كيف أجمعها؟
حوّل حد كل نقطة نهاية على حدة بهذه الأداة؛ فحدود المعدل تُتتبَّع في الغالب لكل نقطة نهاية (أو لكل مفتاح API مع نقطة النهاية)، لا مجمّعة على حسابك كله، ما لم تنص الوثائق صراحةً على غير ذلك.
كيف أحوّل الطلبات في الدقيقة إلى طلبات في الثانية؟
اقسم على 60. فالحد البالغ 600 طلب في الدقيقة يعادل 10 طلبات في الثانية في المتوسط، و3,000 في الدقيقة تعادل 50 في الثانية. وتذكّر أن بعض واجهات API تطبّق الحد في نوافذ أقصر، فقد تُرفض دفعات مفاجئة حتى لو كان المتوسط سليمًا.