تحديد معدل استخدام AI API: كيف يعمل وكيفية التعامل معه

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

أبرز النقاط

• يمكن أن تعني 429 تجاوز سقف الطلبات، أو ميزانية الرموز، أو حد التزامن، أو استنفاد رصيد الحساب. كل حالة تتطلب حلاً مختلفاً، وإعادة المحاولة العشوائية تحل واحدة فقط من هذه المشكلات الأربع.
• اقرأ ترويسات (headers) تحديد المعدل في الاستجابات الناجحة، وليس فقط بعد حدوث الأخطاء، وقم بتقليل وتيرة الطلبات قبل الاقتراب من السقف.
• حساب الرموز من جانب العميل هو تقدير وليس ضماناً. يمكن أن تؤدي الاختلافات في "المُرمّز" (tokenizer) بين مكتبتك وبين الحساب الفعلي للمزود إلى جعل هامش الأمان أضيق مما تعتقد.
• سقوف RPM/TPM الدقيقة لكل نموذج وفئة غير منشورة في الأدلة المتاحة لهذا المقال. تعامل مع أي رقم تراه في مكان آخر كشيء يجب التحقق منه مقابل لوحة تحكم حسابك الخاص، وليس كثابت لا يتغير.
• تتطلب عمليات إعادة المحاولة المرنة استخدام التراجع الأسي (exponential backoff)، والتشويش (jitter)، والحد الأقصى لعدد المحاولات، واحترام ترويسة retry-after. لا تقم أبداً بإعادة محاولة العمليات غير المتماثلة (non-idempotent) بشكل أعمى.

فهم تحديد معدل استهلاك AI API: أنماط الفشل الأربعة

حدود الطلبات

يحسب معظم المزودين الطلبات في الدقيقة (RPM). إذا تجاوزتها، ستحصل على 429 فورية، وغالباً ما تكون بجسم استجابة فارغ. المستخدم الذي يتصفح النتائج بسرعة كبيرة، أو مهمة مجدولة (cron job) تعمل دون تحديد للسرعة، هي أسباب شائعة لهذا التجاوز.

حدود الرموز (Token limits)

هذا هو الفخ الذي تستهين به معظم الفرق. غالباً ما يفرض المزودون حدوداً للرموز في الدقيقة (TPM) بشكل منفصل عن RPM، لذا يمكنك الحصول على 429 بينما لا تزال ضمن سقف الطلبات الخاص بك. تجعل النماذج ذات السياق الكبير هذا الأمر أسوأ: وفقاً لأدلة التسعير المباشرة من TokenLab (تمت ملاحظتها في 2026-07-07)، يدعم كل من Claude Opus 4.8 و GPT-5.5 ما يقرب من 1,000,000+ رمز من السياق. يمكن لطلب يقوم بتحميل مستند كبير، أو قاعدة برمجية كاملة، أو سجل محادثة طويل في تلك النافذة أن يستهلك جزءاً كبيراً من ميزانية الرموز الخاصة بك في الدقيقة في طلب واحد، على الرغم من أنه "طلب واحد" فقط. هذه مخاطرة تتعلق بتخطيط السعة بناءً على حجم نافذة السياق، وليس عدداً مقاساً لكل طلب، لذا تحقق من الاستخدام الفعلي مقابل سجلاتك الخاصة بدلاً من افتراض رقم ثابت.

حدود التزامن (Concurrency limits)

قد يتسامح المزودون مع متوسط حجم طلباتك في الدقيقة حتى تفتح خمسين تدفقاً (stream) في وقت واحد. تحد حدود التزامن من الطلبات أو الاتصالات المتزامنة قيد التنفيذ. تبقي استجابات البث الاتصالات مفتوحة لفترة أطول، مما يستهلك فتحات التزامن بشكل أسرع من الطلبات القصيرة والمفردة. وكلاء البرمجة المبنيون على Claude Sonnet 5 أو Kimi K2.7 Code، وواجهات الصوت التي تبث من Gemini 3.5 Flash، هي أسباب شائعة لأنها تبقي العديد من الاتصالات طويلة الأمد مفتوحة في وقت واحد.

استنفاد الحصة أو الرصيد

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

لقطة المصدر

نقطة البيانات	المصدر	تمت ملاحظتها في
نوافذ سياق النموذج وتسعير الرموز	أدلة TokenLab المباشرة للنماذج/التسعير	2026-07-07
تسمية SSOT للنماذج (Claude Sonnet 5, GPT-5.5, Gemini 3.5 Flash, إلخ)	TokenLab model SSOT	2026-07-07، تنتهي في 2026-07-14
حدود فئات RPM/TPM الرسمية للمزود	غير متوفرة في مجموعة الأدلة هذه	غير محققة، تحقق من لوحة تحكم حساب المزود
سلوك تطبيع ترويسة بوابة TokenLab	غير متوفرة في مجموعة الأدلة هذه	تحقق من وثائق TokenLab API قبل الاعتماد على مخطط ترويسة واحد

نوافذ سياق النماذج الحالية والتسعير (أدلة TokenLab المباشرة)

تأتي هذه الأرقام مباشرة من لقطة التسعير المباشرة لـ TokenLab. إنها ليست حدود RPM أو TPM، بل توضح لماذا يمكن لطلب واحد على نموذج ذي سياق كبير أن يستهلك جزءاً غير متناسب من ميزانية الرموز.

النموذج	المزود	نافذة السياق	الإدخال $/مليون رمز	الإخراج $/مليون رمز	المصدر	تمت ملاحظته
Claude Sonnet 5	Anthropic	1,000,000	$2.00	$10.00	أدلة TokenLab المباشرة	2026-07-07
Claude Opus 4.8	Anthropic	1,000,000	$5.00	$25.00	أدلة TokenLab المباشرة	2026-07-07
Claude Fable 5	Anthropic	1,000,000	$10.00	$50.00	أدلة TokenLab المباشرة	2026-07-07
GPT-5.5	OpenAI	1,050,000	$5.00	$30.00	أدلة TokenLab المباشرة	2026-07-07
GPT-5.5 Batch/Flex	OpenAI	1,050,000	$2.50	$15.00	أدلة TokenLab المباشرة	2026-07-07
Gemini 3.5 Flash	Google	1,048,576	$1.50	$9.00	أدلة TokenLab المباشرة	2026-07-07
GLM-5.2	Z.ai	1,048,576	$0.93	$3.00	أدلة TokenLab المباشرة	2026-07-07
Kimi K2.7 Code	Moonshot AI	262,144	$0.74	$3.50	أدلة TokenLab المباشرة	2026-07-07
DeepSeek V4 Pro	DeepSeek	1,048,576	$0.44	$0.87	أدلة TokenLab المباشرة	2026-07-07
DeepSeek V4 Flash	DeepSeek	1,048,576	$0.09	$0.18	أدلة TokenLab المباشرة	2026-07-07
Qwen3.7 Plus	Alibaba	1,000,000	$0.32	$1.28	أدلة TokenLab المباشرة	2026-07-07
MiniMax M3	MiniMax	1,048,576	$0.30	$1.20	أدلة TokenLab المباشرة	2026-07-07

ملاحظة SSOT للنماذج: تعكس هذه الأسماء TokenLab model SSOT التي تمت ملاحظتها في 2026-07-07، وتنتهي في 2026-07-14. تتغير التسمية والتوافر بشكل متكرر. قبل أن تقوم ببرمجة اسم نموذج في كود الإنتاج، تأكد من أنه لا يزال يعمل في دليل نماذج TokenLab أو لوحة صدارة النماذج.

إصلاح أخطاء تحديد المعدل دون بناء منطق إعادة المحاولة من الصفر

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

تنبيه صادق واحد: تجلس TokenLab أمام العديد من المزودين، ويعيد كل مزود مجموعة الترويسات الخاصة به، وتنسيق الخطأ، ودلالات إعادة المحاولة. ما إذا كانت البوابة تقوم بتطبيع كل ترويسة تحديد معدل بالكامل في مخطط واحد متسق، أو تمرر بعض ترويسات المزودين دون تغيير، غير مؤكد في الأدلة المتاحة لهذا المقال. تحقق من سلوك الترويسة الحالي في وثائق API الخاصة بـ TokenLab قبل كتابة منطق تحليل يفترض مخططاً موحداً عبر كل نموذج. ابنِ محلل الترويسات الخاص بك بشكل دفاعي، وتحقق من وجود كل حقل بدلاً من افتراض وجوده.

قراءة ترويسات تحديد المعدل

يعيد المزودون معلومات تحديد المعدل في ترويسات الاستجابة، على الرغم من أن الأسماء الدقيقة تختلف حسب المزود. يبدو النمط الشائع كالتالي:

x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 499
x-ratelimit-reset-requests: 12s
retry-after: 0

اقرأ هذه الترويسات في الاستجابات الناجحة، وليس فقط بعد 429. احتفظ بعدد تراكمي للميزانية المتبقية وقم بإبطاء الوتيرة عندما تنخفض عن حد الأمان، عادةً 10-20% من الهامش، على الرغم من أن الرقم الصحيح يعتمد على تذبذب حركة المرور الخاصة بك وليس شيئاً يمكن لمجموعة الأدلة هذه تحديده لك.

منطق إعادة المحاولة مع معالجة صريحة للأخطاء

يحتاج مساعد إعادة المحاولة إلى التعامل مع أكثر من حالة 429. يجب أن يميز بين الأخطاء العابرة (429، 503، انتهاء المهلة) وأخطاء العميل (4xx بخلاف 429) التي لن تنجح أبداً عند إعادة المحاولة، ويجب أن يحترم retry-after عند وجودها.

async function callWithRetry(fn, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = err.status;

      // أخطاء العميل بخلاف 429 لن تنجح عند إعادة المحاولة
      if (status && status >= 400 && status < 500 && status !== 429) {
        throw err;
      }

      // الاستسلام بعد الحد الأقصى للمحاولات بغض النظر عن نوع الخطأ
      if (attempt === maxRetries) throw err;

      // 429: احترام retry-after إذا كان موجوداً، وإلا التراجع مع التشويش
      if (status === 429) {
        const retryAfter = parseRetryAfterHeader(err);
        const delay = retryAfter
          ? retryAfter * 1000
          : Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        await sleep(delay);
        continue;
      }

      // 503 أو انتهاء مهلة الشبكة: التراجع وإعادة المحاولة، تسجيل للمراقبة
      if (status === 503 || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET') {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      // 5xx غير معروف: إعادة المحاولة مع التراجع، تحديد المحاولات بدقة
      if (status && status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      throw err;
    }
  }
}

لا تقم أبداً بتغليف العمليات غير المتماثلة، مثل خصم الدفع أو الكتابة ذات الآثار الجانبية، في حلقة إعادة محاولة ساذجة. تأكد من التماثل (idempotency) أو استخدم مفتاح تماثل قبل إعادة محاولة تلك الطلبات.

دقة تقدير الرموز: لماذا تختلف الحسابات المحلية عن حسابات المزود

تقوم مكتبات حساب الرموز من جانب العميل بتقريب المُرمّز الذي يستخدمه النموذج فعلياً. يتطابق tiktoken مع عائلة OpenAI بشكل وثيق ولكنه ليس مضموناً للتطابق تماماً مع مُرمّزات Anthropic أو Google أو النماذج مفتوحة الأوزان. تظهر الاختلافات حول الرموز الخاصة، والأحرف متعددة البايت، وتنسيق مطالبة النظام (system prompt)، وتتضاعف في المحادثات الطويلة.

خطوات عملية لتقليل الانحراف:

• اقرأ استخدام الرموز الفعلي الذي تم إرجاعه في جسم الاستجابة (يتضمن معظم المزودين عدد رموز المطالبة والإكمال) واستخدمه لمعايرة مقدرك المحلي بمرور الوقت.
• احتفظ بهامش أمان، وليس حداً صارماً. إذا كان سقف TPM الخاص بمزودك قريباً من استخدامك المقدر، قم بتأخير الطلب أو تقسيمه بدلاً من إرساله عند الحافة تماماً.
• إذا كانت مطالباتك كبيرة أو متكررة عبر الطلبات، راجع تغطية TokenLab لسلوك الترميز واستراتيجيات تقسيم المطالبات للحصول على طرق ملموسة لتقليل الرموز لكل طلب قبل أن تصل إلى السقف على الإطلاق. غالباً ما يكون تقليل الرموز لكل طلب حلاً أرخص من التفاوض على فئة أعلى.

تشكيل حركة المرور والاحتياط بالنموذج

التراجع الأسي مع التشويش. ضاعف وقت الانتظار بعد كل إعادة محاولة وأضف تشويشاً عشوائياً حتى لا يقوم العملاء المتزامنون بإعادة المحاولة في وقت واحد.

تشكيل حركة المرور لكل مستخدم أو مهمة. حدد الطلبات المتزامنة لكل مستخدم (على سبيل المثال، 3 متزامنة، 5 طلبات في الثانية كحد أقصى) حتى لا يتمكن مستخدم واحد ثقيل من استنفاد حد حسابك بالكامل وتدهور الخدمة للآخرين.

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

الاحتياط بالنموذج كشبكة أمان. عندما يعيد النموذج الأساسي 429، قم بالتوجيه إلى نموذج بديل بحدود منفصلة وقدرة مماثلة. يمكن لمهمة برمجة أن تفشل من Claude Sonnet 5 إلى DeepSeek V4 Pro أو Kimi K2.7 Code. يمكن لمهمة ذات حجم كبير وتكلفة منخفضة أن تفشل بين DeepSeek V4 Flash و Gemini 3.5 Flash و Qwen3.7 Plus، وكلها تقع في فئة التوجيه منخفضة التكلفة لكتالوج النماذج الحالي.

قائمة التحقق للتعامل مع تحديد المعدل

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

نطاقات الحدود النموذجية: ما يمكننا وما لا يمكننا تأكيده

غالباً ما تبحث عمليات البحث الثانوية عن هذا الموضوع عن جدول لأرقام RPM/TPM "النموذجية". لن نبتكر واحداً. تتغير الحدود المنشورة لكل فئة بشكل متكرر، وتختلف حسب تاريخ الحساب وفئة الاستخدام، وليست جزءاً من الأدلة المتاحة لهذا المقال.

السؤال	الحالة	خطوة التحقق
ما هو حد RPM "النموذجي" لنموذج رائد؟	غير مؤكد في مجموعة الأدلة هذه	تحقق من لوحة تحكم حساب المزود أو ترويسات استجابة تحديد المعدل مباشرة
ما هو حد TPM "النموذجي" لنموذج بسياق 1 مليون؟	غير مؤكد في مجموعة الأدلة هذه	سجل الاستخدام الفعلي من ترويسات الاستجابة على مدار أسبوع من حركة المرور لبناء خط الأساس الخاص بك
هل تغير فئة الاستخدام هذه الأرقام؟	معقول بناءً على سلوك المزود العام، لم يتم قياسه هنا	تأكد من حدود الفئة الحالية في وحدة تحكم المزود الخاصة بك
هل تتطابق حدود TokenLab المجمعة مع حدود المزودين تماماً؟	غير مؤكد في مجموعة الأدلة هذه	تحقق من وثائق TokenLab API قبل تخطيط السعة

القيود

• لم تكن هناك أرقام RPM/TPM رسمية متاحة لـ GPT-5.5 أو Claude Opus 4.8 أو Gemini 3.5 Flash أو أي نموذج آخر مشار إليه هنا. كل رقم في جداول التسعير أعلاه هو حجم نافذة السياق وتكلفة الرمز الواحد، وليس حد معدل.
• ما إذا كانت بوابة TokenLab توحد ترويسات تحديد المعدل بالكامل عبر كل مزود، أو تمرر بعضها دون تغيير، غير مؤكد في مجموعة الأدلة هذه. تعامل مع تحليل الترويسة على أنه خاص بالمزود حتى تتحقق من سلوك البوابة الحالي في الوثائق.
• تعكس أسماء النماذج في هذا المقال TokenLab model SSOT التي تمت ملاحظتها في 2026-07-07، وتنتهي في 2026-07-14. تأكد من التوافر الحالي في دليل النماذج قبل شحن كود يبرمج اسم نموذج بشكل ثابت.
• لم يتم قياس دقة تقدير الرموز مقابل الحساب من جانب المزود في مجموعة الأدلة هذه. عاير مقدرك الخاص مقابل الاستخدام المبلغ عنه في الاستجابة بدلاً من الوثوق بإزاحة ثابتة.

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

لماذا يحصل تطبيقي على أخطاء 429 على الرغم من أن عدد الطلبات أقل من الحد؟ تحقق من ميزانية الرموز في الدقيقة (TPM) أولاً. يمكن لمطالبة واحدة كبيرة أن تستنفد مخصص الرموز بينما يظل عدد الطلبات منخفضاً. تحقق أيضاً من التزامن: يمكن لاتصالات البث المفتوحة أن تحظر الطلبات الجديدة حتى عندما تبدو RPM و TPM جيدة.

هل يجب أن أعيد المحاولة فوراً عند تلقي 429؟ لا. انتظر الفترة المحددة في retry-after، أو استخدم التراجع الأسي مع التشويش إذا كانت تلك الترويسة غائبة. تخاطر عمليات إعادة المحاولة الفورية بحدوث تأثير "القطيع الرعدي" (thundering-herd) ويمكن أن تمدد فترة حظرك.

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

هل تعرض TokenLab مجموعة موحدة من ترويسات تحديد المعدل عبر كل نموذج؟ غير مؤكد في الأدلة المتاحة هنا. يعيد المزودون المختلفون تنسيقات ترويسة مختلفة، ومقدار التطبيع الذي تطبقه TokenLab هو شيء يجب التحقق منه في وثائق API الحالية بدلاً من افتراضه.

كيف يمكنني تجنب حدود المعدل دون ترقية خطتي؟ اجمع بين ميزانية الرموز، وحدود التزامن المحلية، والاحتياط بالنموذج. قدر الرموز قبل الإرسال، وقسم المطالبات الطويلة، ووجه الطلب إلى نموذج بديل، على سبيل المثال من Claude Sonnet 5 إلى DeepSeek V4 Pro، عندما يتم الوصول إلى حدك الأساسي.

البدء

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