الخطأ 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).
متى تحتاج إلى طابور حقيقي؟
الإشارة تعيش داخل عملية واحدة. وحين يتشارك عدة عمّال أو خوادم مفتاحًا واحدًا، يصبح الحد مشتركًا ولا ترى كل عملية إلا حركة طلباتها. عندها:
- ضع المهام في طابور مشترك (Redis أو SQS أو جدول في قاعدة بيانات).
- شغّل عددًا ثابتًا من المستهلكين يساوي حد الطلبات قيد التنفيذ للمفتاح.
- أعطِ كل مهمة معرّفًا واحفظ النتائج حسب المعرّف، حتى لا تُنفَّذ المهمة المُعادة مرتين.
- مرّر الحركة التفاعلية وحركة الدفعات عبر مفاتيح منفصلة أو طوابير منفصلة، حتى لا يحجب تراكم الدفعات مستخدمًا ينتظر ردًا.
لمهمة ضخمة من آلاف العناصر دون Batch API، راجع أداة تشغيل الدفعات القابلة للاستئناف.
ما أخطاء إعادة المحاولة التي تحوّل 429 إلى انقطاع كامل؟
- إعادة المحاولة بلا حد. حلقة إعادة بلا سقف أثناء انقطاع طويل تضاعف الحمل، ومع الدفع لكل رمز تضاعف الفاتورة أيضًا.
- إعادة محاولة بث متدفق نصف مكتمل دون تمييز. إذا كان البث قد أعاد رموزًا بالفعل، فإعادة المحاولة استدلال جديد وقد يرى المستخدم النص مرتين. راجع مقال البث المتدفق لاكتشاف البث غير المكتمل.
- إعادة محاولة أخطاء الحساب. الخطأ 401 بسبب استنفاد حصة الدفع حسب الاستخدام، أو 402 بسبب عدم كفاية الرصيد، لن يُصلح نفسه.
سجّل كل إعادة محاولة مع حالتها ومدة الانتظار وترويسة الاستجابة X-Request-ID، التي تطلب وثائق BroadNet الاحتفاظ بها للدعم الفني. ارتفاع نسبة إعادة المحاولة هو أبكر إنذار بأنك تحتاج إلى سعة أكبر؛ ويوضح مقال تسجيل الاستخدام كيف تسجّلها.
أين تقع BroadNet Inference من هذا؟
حدود BroadNet منشورة وصغيرة بما يكفي لتصمّم وفقها: 4 طلبات قيد التنفيذ على مفتاح الدفع حسب الاستخدام. وهذا يناسب التطبيقات والوكلاء، لكنه ضيّق جدًا لمهمة ضخمة تريد مئات الاستدعاءات المتوازية على مفتاح واحد. أما للوكلاء، فإن الخطة غير المحدودة بلا عدّاد للرموز وتشغّل طلبًا واحدًا في كل مرة لكل جلسة؛ وتضيف جلسات للعمل المتوازي، كما يشرح مقال تشغيل وكلاء برمجة متوازين. والحدود الحالية في المرجع التقني.
