AR ▾

ما هو حدّ معدل API؟ الحدود، إعادة المحاولة، السياق

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

محدّث

بوابة بثماني مسارات تمرر حزمًا خفيفة، توضح حدود معدل API والتزامن

نقاط رئيسية

  • يحدّ حدّ المعدل من عدد الطلبات في الدقيقة أو الطلبات قيد التنفيذ، بحيث لا يمكن لعميل واحد إجهاد الخدمة.
  • حدود المعدل ليست نفسها نافذة السياق: أحدها يحدد حركة المرور، والآخر يحدد حجم الطلب الواحد.
  • المفتاح الكامل: 8 طلبات متزامنة و300 في الدقيقة. مفتاح التجربة: 2 متزامن و60 في الدقيقة.
  • إدارة الحدود عبر تحديد حدّ التزامن، وإعادة المحاولة مع تأخير، ومراجعة رؤوس الاستجابة.

ما هو حدّ المعدل

إذن، ما هو حدّ معدل API؟ إنه قاعدة تحدد عدد المكالمات التي يمكن لحساب أو مفتاح واحد إجراؤها ضمن نافذة زمنية، أو عدد المكالمات التي يمكن تشغيلها في وقت واحد. إذا تجاوزت الحد، سيرفض الخادم المكالمات الإضافية بدلاً من معالجتها. تشير معظم واجهات برمجة تطبيقات HTTP إلى ذلك باستخدام رمز الحالة 429 (Too Many Requests)، وتضيف العديد منها رأساً يخبرك بموعد إعادة المحاولة. تحقق من وثائق كل خدمة لمعرفة سلوكها الدقيق.

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

أنواع الحدود الثلاثة التي ستواجهها

يخلط المزودون بين هذه الخيارات، لذا اقرأ لمعرفة أي منها ينطبق على مفتاحك.

النوعما الذي يتم حسابهالتأثير النموذجي
الطلبات في الدقيقةالمكالمات التي تبدأ في دقيقة متحركةيتم رفض الذروات حتى لو كانت كل مكالمة صغيرة
التزامنالمكالمات قيد التنفيذ في نفس اللحظةيتم رفض العمال (workers) المتوازين الذين يتجاوزون الحد أو وضعهم في قائمة الانتظار
حصة الرموز أو الإنفاقالرموز أو المال المستخدم في الدقيقة أو اليوم أو الشهرتصل الموجّهات الكبيرة إلى الحدّ أسرع من الموجّهات الصغيرة

تعدّ الطلبات المتزامنة أكثر أهمية للنماذج اللغوية منها لواجهات برمجة التطبيقات العادية، لأن إكمالاً واحداً قد يستغرق عدة ثوانٍ. يحتفظ عشرة عمال، كل منهم ينتظر ردّاً طويلاً، بعشرة أماكن طوال الوقت.

حدود واجهة برمجة التطبيقات هذه

تحدد واجهة برمجة التطبيقات هذه الطلبات في الدقيقة والتزامن، لكل مفتاح:

نوع المفتاحطلبات متزامنةالطلبات في الدقيقة
المفتاح الكامل (مع الرصيد)8300
مفتاح التجربة260

هناك رقمان آخران يستحقان المعرفة. الحد الأقصى لحجم جسم الطلب هو 8 ميجابايت، وكل استجابة تحمل رؤوساً يمكنك قراءتها: X-Request-Id لتحديد المكالمة عند طلب المساعدة، X-Balance-USD لمعرفة رصيدك المتبقي، وX-RateLimit-Limit-Requests وX-RateLimit-Limit-Concurrency لمعرفة الحدود المطبقة على مفتاحك. يمكنك رؤيتها باستخدام curl:

curl -i https://api.abliteratedapi.com/v1/chat/completions   -H "Authorization: Bearer $ABLITERATED_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"uncensored","max_tokens":5,"messages":[{"role":"user","content":"Hi"}]}'

الحدود هي نفسها بغض النظر عن العميل الذي تستخدمه؛ الـ API متوافق مع OpenAI، لذا فإن أي SDK من OpenAI يعمل بمجرد تغيير الـ Base URL إلى https://api.abliteratedapi.com/v1.

أي حد ستصل إليه فعلياً؟

اقسم الرقمين. يمكن للمفتاح الكامل تشغيل 8 طلبات في وقت واحد و300 في الدقيقة، وهو ما يعني متوسط 5 في الثانية. للوصول إلى 300 في الدقيقة مع وجود 8 طلبات فقط قيد التنفيذ، يجب أن تنتهي كل مكالمة في 1.6 ثانية كمتوسط (8 × 60 / 300). تستغرق الردود من نموذج لغوي عادةً وقتاً أطول من ذلك عندما تكون أطول من بضع جمل، لذا فإن حدّ التوازي هو الذي يحدّ أولاً على المفتاح الكامل.

خذ حالة افتراضية حيث تستغرق المكالمة المتوسطة 10 ثوانٍ. تمنحك ثمانية أماكن 8 × 60 / 10 = 48 طلباً في الدقيقة، وهو أقل بكثير من 300. نفس المنطق على مفتاح تجريبي: مكانان و60 في الدقيقة يعني أنه يلزم أن تكون المكالمات أقل من ثانيتين قبل أن يصبح الحد الخاص بالدقيقة مهماً. هذه المدة للتوضيح فقط وليست قياساً. قم بقياس مكالماتك الخاصة وأدخل الرقم الفعلي.

النصيحة العملية: اضبط حجم مجموعة العمال وفقاً لحدّ التوازي، وليس حدّ الطلب، واترك حدّ الدقيقة يعمل كشبكة أمان.

كيفية التعامل مع الحدود في الكود

ثلاث عادات تغطي معظم الحالات.

  1. حدّ التزامن بنفسك. يعني استخدام semaphore بحجم حدّ التزامن أنك نادراً ما تواجه رفضاً.
  2. أعد المحاولة مع زيادة أسية وتذبذب عشوائي. انتظر ثانيةً واحدة، ثم 2، ثم 4، مع إضافة جزء عشوائي حتى لا يحاول العديد من العمال إعادة المحاولة في تزامن. توقف بعد محاولات قليلة.
  3. لا تعيد المحاولة بشكل أعمى. الطلب غير الصحيح أو المفتاح الخاطئ سيفشل في كل مرة. أعد المحاولة فقط على أخطاء حدّ المعدل وأخطاء الخادم المؤقتة.

تعيد OpenAI Python SDK الرسمي المحاولة تلقائياً عند حدوث خطأ 429 وأخطاء الخادم مع تأخير متزايد، ويمكنك التحكم فيها باستخدام max_retries. بالاقتران مع semaphore، تبدو مهمة الدُفعات (batch) كالتالي:

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.abliteratedapi.com/v1",
    api_key=os.environ["ABLITERATED_API_KEY"],
    max_retries=5,
)
sem = asyncio.Semaphore(8)   # use 2 on a trial key

async def ask(prompt):
    async with sem:
        r = await client.chat.completions.create(
            model="uncensored",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main():
    prompts = [f"Give one short fact about the number {n}." for n in range(40)]
    answers = await asyncio.gather(*(ask(p) for p in prompts))
    print(len(answers), "answers")

asyncio.run(main())

تمر أربعون موجهاً، ولا يزيد العدد عن ثمانية في كل مرة. إذا بنيت عميلك الخاص، ضع هاتين الفكرتين في الكود: حد للمكالمات الجارية، وتأخير إعادة المحاولة الذي يزداد.

حدود المعدل ليست نافذة السياق

يخلط الناس كثيراً بين الاثنين، لأن كليهما ينتج أخطاء عندما تطلب الكثير. يتحكم حدّ المعدل في عدد الطلبات التي تقدمها. تتحكم نافذة السياق في حجم الطلب الواحد.

في هذا الـ API، تبلغ نافذة السياق 100,000 رمز (token)، وتشمل الموجّه والإكمال معاً. إذا كان الموجّه الخاص بك يحتوي على 95,000 رمز (token)، يتبقى كحد أقصى 5,000 رمز (token) للرد. معلمة max_tokens اختيارية: اتركها دون تحديد ليستخدم الإكمال المساحة المتبقية في النافذة. ومع ذلك، فإن تحديدها عادة جيدة عندما تعرف أن الإجابة يجب أن تكون قصيرة، لأن رموز (tokens) المخرجات تكلف $0.50 لكل مليون مقابل $0.15 لكل مليون للمدخلات. يكلف الموجّه الكامل المكون من 95,000 رمز (token) 95,000 × 0.15 / 1,000,000 = $0.01425 في المدخلات.

لا يقلل حدّ المعدل من حجم نافذة السياق، ولا يستهلك السياق الكبير حدّ معدل إضافي. كل مكالمة هي طلب واحد، بغض النظر عن حجمها، طالما أن جسم الطلب أقل من 8 MB.

البث المتدفق وحدود المعدل

عند استخدام stream: true، يعود الرد عبر أحداث مُرسلة من الخادم (SSE)، رمزاً تلو الآخر، وتصل بيانات الاستخدام في النهاية. لا تزال المكالمة المتدفقة تشغل فتحة توازي واحدة حتى ينتهي البث، لذا فإن القارئ البطيء الذي يفتح الاتصالات يمسك الفتحات لفترة أطول مما تتوقع. أغلق البث المتدفق الذي لم تعد بحاجة إليه.

الأخطاء الشائعة

  • لا يوجد حد لعدد العمال. يعني وجود مجموعة خيوط بـ 50 عاملاً مقابل حد 8 أن معظم المكالمات ستُرفض. طابق حجم مجموعة الخيوط مع حد الطلبات المتزامنة.
  • إعادة المحاولة الفورية. إعادة المحاولة فوراً بعد الرفض تضيف حِملاً إضافياً في أسوأ لحظة. انتظر، وازدِد الانتظار في كل مرة.
  • اعتبار كل خطأ كحدّ معدل. كل من المهلة الزمنية، والمفتاح الخاطئ، وجسم الطلب الكبير يحتاج إلى حل مختلف. سجل رمز الحالة ورأس X-Request-Id.
  • مشاركة مفتاح واحد لكل شيء. تتنافس مهمة دفعية ليلية وميزة دردشة مباشرة على نفس المفتاح للحصول على نفس 8 فتحات. استخدم مفاتيح منفصلة، أو جدوِل المهمة خلال ساعات الهدوء.
  • إهمال البث المتدفق البطيء. العميل الذي يتوقف عن القراءة لكنه يفتح الاتصال لا يزال يمسك بفتحة.

أضف عدّاداً للمكالمات المرفوضة إلى سجلاتك. إذا بقي صفراً، فإن حدّك مضبوط بشكل صحيح. إذا ارتفع، قلل حجم المجموعة قبل أن تضيف إعادة المحاولة.

التخطيط حول الحدود

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

أسئلة وأجوبة

ماذا يحدث عندما أتجاوز الطلبات في الدقيقة؟

يرفض الخادم الطلبات الإضافية، عادةً بـ HTTP 429، ويجب أن ينتظر الكود الخاص بك ويعيد المحاولة. قلل السرعة أو خفض التوازي حتى تتوقف الأخطاء.

ما هي الحدود على واجهة برمجة التطبيقات هذه؟

المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة. مفتاح التجربة يسمح بـ طلبين متزامنين و60 في الدقيقة.

هل الطلبات في الدقيقة هو نفسه نافذة السياق؟

لا. حدّ المعدل يتحكم في عدد الطلبات التي يمكنك إرسالها بمرور الوقت. نافذة السياق، 100,000 رمز هنا، تتحكم في حجم طلب واحد وردّه.

كيف أرى حدودي من الاستجابة؟

اقرأ رؤوس الاستجابة X-RateLimit-Limit-Requests و X-RateLimit-Limit-Concurrency. يعرض رأس X-Balance-USD رصيدك المتبقي، ويحدد X-Request-Id مكالمة محددة.

هل تكلف الطلبات المرفوضة مالاً؟

لا. الطلبات الفاشلة أو المرفوضة لا تُحتسب عليها رسوم في واجهة برمجة التطبيقات هذه.

مفتاحك على بُعد نموذج واحد

أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.

احصل على مفتاح API