BroadRouter

كيف تعالج الخطأ 429 في LLM API: الانتظار المتزايد والتذبذب والمحدِّدات

بقلم فريق BroadNet Inference · قراءة في 5 دقائق · تاريخ النشر · آخر تحديث

الخطأ 429 يعني أنك بلغت حدًا للمعدل أو التزامن أو الإنفاق. أعد المحاولة بانتظار أُسّي متزايد له سقف مع تذبذب عشوائي، والتزم بترويسة Retry-After إن أُرسلت. ثم امنع معظم أخطاء 429: قيّد الطلبات قيد التنفيذ بإشارة (semaphore) عند حد المفتاح وضع الباقي في طابور. أعد محاولة 5xx بالطريقة نفسها؛ أما أخطاء 4xx الأخرى فأصلحها.

الخطأ 429 يعني أن حركة طلباتك تجاوزت حد المعدل: الطلبات في الدقيقة، أو الطلبات قيد التنفيذ، أو الرموز في الدقيقة، أو الإنفاق. وعلاجه من شقين. أعد المحاولة جيدًا: انتظار أُسّي متزايد له سقف مع تذبذب عشوائي، والتزام بترويسة Retry-After. أرسل أقل في آنٍ واحد: إشارة (semaphore) عند حد الطلبات قيد التنفيذ للمفتاح، مع طابور. تجد الاثنين أدناه مع الشيفرة.

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

ما الفرق بين 429 و5xx؟

الحالة مشكلة مَن إعادة المحاولة؟ الطريقة
429 حركة طلباتك تجاوزت حدًا نعم انتظار متزايد مع تذبذب؛ التزم بـ Retry-After؛ خفّض التزامن
500 / 502 / 503 / 504 من جهة الخادم نعم انتظار أُسّي متزايد محدود
انقطاع الاتصال، انتهاء المهلة الشبكة أو الخادم عادةً انتظار متزايد؛ وفي البث المتدفق، فقط إن كانت فاتورة جديدة مقبولة
400 / 422 طلب خاطئ لا أصلح محتوى الطلب
401 / 402 / 403 المفتاح أو الرصيد أو السياسة لا أصلح المفتاح، أو اشحن الحساب، أو أصلح قائمة العناوين المسموحة
413 الطلب كبير جدًا لا صغّره

في BroadNet Inference، قد يعني الخطأ 429 أيًّا من أربعة حدود: المعدل، أو التزامن، أو معدل الرموز، أو الإنفاق. وحد الإنفاق لن يزول خلال 30 ثانية. لا تذكر وثائق BroadNet أي حقل في جسم الخطأ يسمّي الحد، لذا سجّل جسم الخطأ وقارنه بالحدود الظاهرة في تفاصيل مفتاحك.

تقارن مجموعة بياناتنا المفتوحة عن الطبقات المجانية وحدود المعدل في LLM API ما ينشره 14 مزوّدًا عن الوصول المجاني، وحدود المعدل الأولية، واشتراط البطاقة، والتدريب على بيانات الطبقة المجانية، مع المصدر والتاريخ لكل قيمة.

ما الحدود التي تسبب أخطاء 429؟

اعرف الأرقام التي تعمل في حدودها. في BroadNet Inference:

نوع المفتاح الطلبات / الدقيقة قيد التنفيذ غير ذلك
الدفع حسب الاستخدام 30 4 ميزانية إنفاق مشتركة
مفتاح بالساعة 120 تدفق واحد 300,000 رمز / الدقيقة
جلسة خطة غير محدودة — طلب واحد لكل جلسة بلا عدّاد للرموز

عدد الطلبات قيد التنفيذ هو الأهم في نماذج اللغة. تشغل الإجابة المتدفقة خانتها حتى يصل آخر رمز، لذا تُبقي الإجابة الطويلة الخانة مشغولة طوال المدة التي يستغرقها النموذج في كتابتها (تذكر BroadNet سرعة نموذجية تبلغ نحو 100 رمز في الثانية). وإذا أرسلت استدعاءات متوازية أكثر من خانات المفتاح البالغة 4، تتلقى الاستدعاءات الزائدة الخطأ 429، مع أنك لم ترسل سوى عدد قليل من الطلبات في تلك الدقيقة. هذه مشكلة تزامن، والانتظار المتزايد وحده يعالجها معالجة سيئة. ولتحديد عدد العمّال وفق حدٍّ ما قبل الإطلاق، استخدم حاسبة حدود معدل LLM المجانية. ولمهمة ثابتة من عناصر كثيرة، يحوّل مخطِّط مهام LLM المجمّعة الحدود نفسها إلى مدة تشغيل. ويحسب المزوّدون الآخرون بطرق مختلفة (رموز في الدقيقة، أو طلبات في اليوم، أو طلبات قيد التنفيذ)؛ ويقارن مقال حدود معدل LLM API حسب المزوّد بين 13 منهم من وثائقهم.

كيف تكتب انتظارًا متزايدًا مع تذبذب؟

الانتظار الأُسّي المتزايد العادي ينتظر 1 ثم 2 ثم 4 ثم 8 ثوانٍ. فإذا قُيِّد مئة عامل في اللحظة نفسها، عادوا جميعًا في اللحظة نفسها. ووجدت محاكاة AWS لـ 100 عميل متنافس أن التذبذب الكامل خفّض عدد الاستدعاءات إلى أقل من النصف وأنهى العمل أسرع من الانتظار المتزايد بلا تذبذب. وأبسط صيغة، التذبذب الكامل، تنتظر مدة عشوائية بين الصفر والسقف الأُسّي:

import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError, APIConnectionError) as e:
            status = getattr(e, "status_code", None)
            if status is not None and status not in RETRYABLE:
                raise  # 400, 401, 403...: retrying will not help
            if attempt == max_attempts - 1:
                raise
            retry_after = None
            if getattr(e, "response", None) is not None:
                retry_after = e.response.headers.get("retry-after")
            wait = random.uniform(0, min(cap, base * 2 ** attempt))
            if retry_after and retry_after.isdigit():
                wait = max(wait, float(retry_after))
            time.sleep(wait)

يعطّل max_retries=0 إعادة المحاولة الخاصة بالحزمة حتى لا تعيد المحاولة مرتين. وإذا كان السلوك المدمج في الحزمة يكفيك، فالعكس يصلح أيضًا: احذف حلقتك واضبط max_retries=4 على العميل، كما يوضح دليل Python SDK. تعيد حزمتا SDK الرسميتان لـ Python وNode محاولة أخطاء الاتصال و408 و409 و429 و5xx مرتين افتراضيًا.

Retry-After ترويسة قياسية (RFC 9110) قد تحمل عدد ثوانٍ أو تاريخًا. ولا تَعِد وثائق BroadNet بإرسالها، لذا تعاملها الشيفرة على أنها اختيارية.

كيف تمنع أخطاء 429 قبل حدوثها؟

قيّد الطلبات قيد التنفيذ عند حد المفتاح. في Python، تؤدي asyncio.Semaphore المهمة بكائن واحد وكتلة async with واحدة. تستخدم الشيفرة القيمة 4 مثالًا؛ اضبطها على حد الطلبات قيد التنفيذ لمفتاحك (4 في مفتاح الدفع حسب الاستخدام من BroadNet):

import asyncio, os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4)  # match the key's in-flight limit

async def ask(prompt):
    async with slots:
        r = await client.chat.completions.create(
            model="broadnet/gemma-4-26b-a4b",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))

تبدأ gather كل المهام، لكن لا يعمل منها في آنٍ واحد إلا العدد الذي تسمح به الإشارة. وتنتظر البقية في طابور الإشارة. وفي Node، تؤدي الحزمة p-limit الشيء نفسه، مع القيمة 4 مثالًا هنا أيضًا:

// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit

async function ask(prompt) {
  const r = await client.chat.completions.create({
    model: "broadnet/gemma-4-26b-a4b",
    messages: [{ role: "user", content: prompt }],
  });
  return r.choices[0].message.content;
}

const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));

ولإضافة سقف في الدقيقة أيضًا، أضف دلو رموز (token bucket) يطلق إذنًا واحدًا كل 60 / rpm ثانية، حيث rpm هو حد الطلبات في الدقيقة لمفتاحك (30 في مفتاح الدفع حسب الاستخدام من BroadNet).

متى تحتاج إلى طابور حقيقي؟

الإشارة تعيش داخل عملية واحدة. وحين يتشارك عدة عمّال أو خوادم مفتاحًا واحدًا، يصبح الحد مشتركًا ولا ترى كل عملية إلا حركة طلباتها. عندها:

  1. ضع المهام في طابور مشترك (Redis أو SQS أو جدول في قاعدة بيانات).
  2. شغّل عددًا ثابتًا من المستهلكين يساوي حد الطلبات قيد التنفيذ للمفتاح.
  3. أعطِ كل مهمة معرّفًا واحفظ النتائج حسب المعرّف، حتى لا تُنفَّذ المهمة المُعادة مرتين.
  4. مرّر الحركة التفاعلية وحركة الدفعات عبر مفاتيح منفصلة أو طوابير منفصلة، حتى لا يحجب تراكم الدفعات مستخدمًا ينتظر ردًا.

لمهمة ضخمة من آلاف العناصر دون Batch API، راجع أداة تشغيل الدفعات القابلة للاستئناف.

ما أخطاء إعادة المحاولة التي تحوّل 429 إلى انقطاع كامل؟

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

سجّل كل إعادة محاولة مع حالتها ومدة الانتظار وترويسة الاستجابة X-Request-ID، التي تطلب وثائق BroadNet الاحتفاظ بها للدعم الفني. ارتفاع نسبة إعادة المحاولة هو أبكر إنذار بأنك تحتاج إلى سعة أكبر؛ ويوضح مقال تسجيل الاستخدام كيف تسجّلها.

أين تقع BroadNet Inference من هذا؟

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

أسئلة شائعة

ماذا يعني الخطأ HTTP 429 في LLM API؟

Too Many Requests، أي «طلبات كثيرة جدًا». لقد تجاوزت حدًا لعدد الطلبات في الدقيقة، أو الطلبات قيد التنفيذ، أو الرموز في الدقيقة، أو الإنفاق. لم يُعالَج الطلب، لذا يمكن إرساله مجددًا بأمان بعد الانتظار.

كم أنتظر قبل إعادة المحاولة بعد خطأ 429؟

استخدم Retry-After إن أرسلها الخادم. وإلا فابدأ بنحو ثانية واحدة، وضاعف المدة مع كل محاولة، واجعل السقف بين 30 و60 ثانية تقريبًا، واختر انتظارًا عشوائيًا بين الصفر وذلك السقف. توقّف بعد أربع إلى ست محاولات.

هل أعيد محاولة أخطاء 500 و503 من LLM API؟

نعم، بالانتظار المتزايد المحدود نفسه. فهي أخطاء من جهة الخادم. أما 400 أو 401 أو 403 أو 422 فستفشل بالطريقة نفسها في كل مرة، لذا أصلح سببها.

هل تعيد OpenAI SDK محاولة 429 تلقائيًا؟

نعم. تعيد حزمتا SDK الرسميتان لـ Python وNode محاولة أخطاء الاتصال و408 و409 و429 و5xx مرتين افتراضيًا مع انتظار أُسّي قصير. ارفع max_retries للمهام المجمّعة، وأضف حدًا خاصًا بك للتزامن.

لماذا يظهر لي 429 وأنا تحت حد الطلبات في الدقيقة؟

غالبًا بسبب حد التزامن. الاستجابات المتدفقة الطويلة تبقى قيد التنفيذ ثوانيَ كثيرة، لذا قد تبلغ بضعة استدعاءات متوازية سقف الطلبات قيد التنفيذ بينما يبدو العدد في الدقيقة منخفضًا.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity