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

خطأ LLM API 429: الأسباب وكيفية إصلاحه

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

تم التحديث

حزم ضوء تتراكم عند بوابة ذات ثمانية ممرات، توضح حدود معدل الواجهة البرمجية

نقاط رئيسية

أنواع 429 الثلاثة

HTTP 429 هو وضع "طلبات كثيرة" القياسي. هنا يغطي ثلاث حالات، ويخبرك جسم الخطأ JSON بأي واحدة أنت.

رمز الخطأما يعنيهالإصلاح النموذجي
rate_limitedطلبات كثيرة جداً في الدقيقةأبطئ، ووزّع الطلبات على الدقيقة
concurrencyعدد كبير من الطلبات يعمل في نفس الوقتقلل من التوازي، وانتظر حتى تتحرر الخانات
حمل زائد، مع Retry-After: 5حمل مؤقت على الخدمة، وليس خطأ منكانتظر عدد الثواني في الرأس، ثم أعد المحاولة

اقرأ الرمز أولاً، لأن حل سبب واحد لا يؤثر في سبب آخر. لن يساعدك تقليل عدد طلباتك في الدقيقة إلى النصف إذا كانت المشكلة الحقيقية هي إرسال 20 عاملاً في نفس الوقت.

اعرف حدودك

تعتمد الحدود على نوع المفتاح:

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

تحتوي كل استجابة على X-RateLimit-Limit-Requests و X-RateLimit-Limit-Concurrency، مما يتيح للعميل قراءة الحد الأقصى بدلاً من تثبيته. مفتاح التجربة هو السبب المعتاد لدى المستخدمين الجدد: سكريبت يعمل بشكل جيد عند إرسال 1 طلب في كل مرة يبدأ بالفشل عند إضافة مجموعة خيوط مكونة من 4. التجربة مخصصة للاختبار، والمفتاح الكامل يأتي مع أي شحن رصيد من $20 (انظر صفحة الأسعار للمبالغ والمزايا).

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

لماذا يجعل البث المتدفق أخطاء التوازي أكثر احتمالاً

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

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

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

كود إعادة المحاولة في Python مع تراجع

النمط بسيط: التقاط حالة 429، قراءة الكود، الانتظار، المحاولة مرة أخرى بتأخير متزايد وبعض العشوائية، والاستسلام بعد بضع محاولات. تستخدم هذه النسخة الحزمة الرسمية openai مع عنوان URL الأساسي للخدمة:

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
    max_retries=0,  # we handle retries ourselves
)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=messages,
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            headers = e.response.headers
            wait = float(headers.get("Retry-After", 0))
            if not wait:
                wait = min(30, 2 ** i)  # 1, 2, 4, 8, 16 seconds
            wait += random.uniform(0, 1)  # jitter
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

print(chat([{"role": "user", "content": "Reply with the word ok."}]))

عند وجود الرأس، استخدمه كحد أدنى للانتظار. عند غيابه، يعمل التأخير الأسي بشكل جيد مع rate_limited لأن نافذة الدقيقة تتقدم. يقلل التذبذب من محاولة العديد من العمال إعادة المحاولة في اللحظة نفسها.

حدد الحد الأقصى للمكالمات المتوازية لتجنب رؤية خطأ 429 نادراً

تعامل إعادة المحاولة مع العرض. يمنع المسمافور (semaphore) معظمها بعدم إرسال أكثر من عدد خاناتك. اضبطه أقل قليلاً من الحد حتى يكون هناك مجال لإعادة المحاولة أو الطلب الضال:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6)  # full key allows 8; use 1 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 fact about the number {n}." for n in range(50)]
    results = await asyncio.gather(*(ask(p) for p in prompts))
    print(len(results))

asyncio.run(main())

بالنسبة للحد في الدقيقة، 300 طلب في الدقيقة تعني 5 طلبات في الثانية متوسطاً. إذا جمعت آلاف المهام القصيرة، أضف تأخيراً صغيراً أو دلو رمز في مقدمة قفل السعة. لأن الـ SDK يعيد المحاولة أيضاً بشكل افتراضي، اضبط max_retries صراحةً حتى لا تتراكم وتضاعف أوقات الانتظار بين منطقك الخاص وعمليات إعادة المحاولة في الـ SDK.

إعادة إنتاج وفحص خطأ 429 باستخدام curl

قبل تغيير الكود، انظر إلى الاستجابة الخام. أضف -i إلى curl لطباعة الرؤوس، وأرسل بضع طلبات بالتوازي لإثارة الخطأ عن قصد:

for i in 1 2 3 4; do
  curl -i -s https://api.onekeyllmapi.com/v1/chat/completions     -H "Authorization: Bearer $API_KEY"     -H "Content-Type: application/json"     -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait

على مفتاح التجربة الذي يسمح بـ 2 طلب في آن واحد، يجب أن تعود المكالمات الثالثة والرابعة بحالة 429 ورمز خطأ concurrency. على مفتاح كامل ستحتاج إلى أكثر من 8 في آن واحد. انظر إلى ثلاثة أشياء في كل رد: سطر الحالة، رأس Retry-After إذا وجد، وحقل error.code في جسم JSON. تخبرك هذه التجربة الصغيرة أكثر من ساعة من التخمين، وتعطيك حالة قابلة للتكرار لعرضها على الدعم إذا بدا شيء خاطئاً.

صممه ليكون جزءاً من التصميم، وليس حوله

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

قائمة تحقق قصيرة للتصحيح

  1. سجّل جسم الخطأ الكامل ورأس X-Request-Id لكل حالة 429. يفصل حقل الرمز بين rate_limited وconcurrency.
  2. تحقق مما إذا كان مفتاحك مفتاح تجربة. إذا كان كذلك، توقع وجود 2 طلب متزامن و60 طلب في الدقيقة.
  3. عدّ كل برنامج يستخدم المفتاح، وليس فقط البرنامج الذي فشل.
  4. ابحث عن التدفقات غير المغلقة، وعن الحلقات التي تعيد المحاولة فوراً دون تأخير. تحول حلقة إعادة المحاولة الفورية 429 واحداً إلى مئة.
  5. تحقق من الرصيد باستخدام X-Balance-USD أو GET /v1/balance. الرصيد الفارغ يمثل مشكلة مختلفة عن حالة 429، لكن التحقق يستغرق ثوانٍ.

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

أسئلة وأجوبة

هل خطأ 429 مني أم من مزود الخدمة؟

كلاهما ممكن. تعني الأكواد rate_limited وconcurrency أن مفتاحك تجاوز حدّه. يمكن أن تأتي حالة 429 مع رأس Retry-After أيضاً من الحمل الزائد المؤقت، والانتظار للمدة المحددة ثم إعادة المحاولة هو الاستجابة الصحيحة.

كم من الوقت يجب أن أنتظر قبل إعادة المحاولة؟

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

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

لا. الطلبات الفاشلة أو المرفوضة لا تُفرض عليها تكلفة.

هل يمكنني رفع حدودي؟

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

مفتاحك على بُعد استمارة واحدة

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