وكيلك يستدعي واجهة برمجة تطبيقات (API). تعيد واجهة برمجة التطبيقات الرمز 429. يعيد وكيلك المحاولة على الفور، ويتلقى 429 أخرى، ثم يعيد المحاولة مرة أخرى، والآن لديك حلقة تضغط على خدمة محدودة حتى تتوقف العملية أو ترتفع الفاتورة بشكل كبير. لم يقم أحد بكتابة هذه الحلقة عن قصد. إنها تنتج عن النسخة الساذجة من "التعامل مع الخطأ"، وهي الشيء الأكثر شيوعًا الذي يسأل عنه المطورون في لوحة مناقشة Anthropic SDK.
استعادة الأخطاء هي الجزء من بناء الوكيل الذي يفصل العرض التوضيحي النظيف عن شيء يمكن أن تستدعي شخصًا بسببه. النموذج ليس المشكلة. المشكلة هي ما يفعله الكود الخاص بك عندما تعود استدعاء الأداة بطيئة، أو محدودة، أو معطلة. إذا قمت بالاستعادة بشكل صحيح، يصبح الاعتماد المتقطع مجرد توقف قصير لا يلاحظه المستخدم أبدًا. أما إذا أخطأت، فيتحول خطأ 500 واحد إلى حادثة. يغطي هذا الدليل الأنماط الأربعة التي تحمل معظم العبء: إعادة المحاولة مع التراجع التدريجي، والمهل الزمنية، وقواطع الدائرة، ومفاتيح الثبات. ثم يوضح كيفية اختبارها مقابل كائن وهمي (mock)، قبل أن يكتشف المستخدم الثغرات نيابة عنك. للحصول على صورة أوسع لكيفية فشل الوكلاء، ابدأ بـ لماذا تتعطل وكلاء الذكاء الاصطناعي في بيئة الإنتاج.
لا يمكنك اختبار الاستعادة مقابل واجهة برمجة تطبيقات سليمة
هذا هو الفخ. يعمل تبعيتك بشكل جيد في مرحلة التطوير. تكتب وكيلك، تنجح الاستدعاءات، العرض التوضيحي نظيف، وتقوم بالنشر. لم يتم تشغيل كود الاستعادة ولو لمرة واحدة، لأن واجهة برمجة التطبيقات السليمة لا تعيد الأخطاء التي من المفترض أن تتعامل معها. أول مرة تعمل فيها منطق التراجع التدريجي لديك تكون في بيئة الإنتاج، مقابل انقطاع حقيقي، ومع مستخدمين حقيقيين يراقبون. هذا هو أسوأ مكان لاكتشاف خطأ مطبعي في حلقة إعادة المحاولة.
لذا القاعدة بسيطة. لاختبار الاستعادة، عليك إنتاج الإخفاقات عمدًا. قم بإعداد محاكاة (mock) لواجهة برمجة التطبيقات التي يستدعيها الوكيل، وقم ببرمجتها لتعيد الرمز 429، أو 500، أو مهلة زمنية (timeout)، أو جسم طلب غير سليم (malformed body)، ثم وجه الوكيل إليها، وراقب ما يفعله. يصبح الفشل شيئًا تقوم بتشغيله في اختبار بدلاً من شيء يزعجك في الساعة 3 صباحًا. يقوم Apidog بإعداد تلك المحاكاة وبرمجة الاستجابات، ويتم استعراض ذلك في قسم الاختبار في النهاية.
إعادة المحاولة مع التراجع التدريجي الأسي والارتعاش
إعادة المحاولة هي خط الدفاع الأول، والنسخة الساذجة منها هي الفخ. التقاط الخطأ، ثم الاتصال مرة أخرى فورًا. يعمل هذا ضد عطل مؤقت. أما ضد خدمة تحت الضغط، فإنه يجعل الأمور أسوأ، لأن كل عميل فاشل يعيد المحاولة في نفس اللحظة، وتستمر هذه الاندفاعة في تعطيل الخدمة.
يتم الجمع بين إصلاحين. التراجع التدريجي الأسي يباعد المحاولات: انتظر ثانية واحدة، ثم ثانيتين، ثم 4، ثم 8، تتضاعف حتى تصل إلى حد أقصى. تحصل الخدمة على مساحة للتعافي بدلاً من جدار من المحاولات الفورية. يضيف الارتعاش (Jitter) إزاحة عشوائية لكل انتظار بحيث لا يعيد ألف عميل فشلوا جميعًا في نفس اللحظة المحاولة في نفس اللحظة أيضًا. بدونه، لا يزال التراجع التدريجي ينتج موجات متزامنة.
حدد أمرين: التأخير، حتى لا تنتظر دقائق بين المحاولات، وعدد المحاولات، بحيث تتوقف المحاولة في حالة الفشل الدائم بدلاً من إعادة المحاولة إلى الأبد. تغطي ثلاث إلى خمس محاولات تقريبًا كل الأخطاء العابرة. بعد ذلك، عادةً ما تكون إعادة المحاولة لشيء لن ينجح. يقوم Anthropic SDK بجزء من هذا لاستدعاءاته الخاصة: فهو يعيد محاولة أخطاء الاتصال ورموز حالة معينة مع التراجع التدريجي الأسي، وتحدد الحد الأقصى بخيار الحد الأقصى للمحاولات (max-retries). لا يغطي واجهات برمجة التطبيقات الأخرى التي تستخدمها أدوات وكيلك، لذلك يجب عليك تغليفها بنفسك. تتعلم الفرق التي تتعامل مع الأموال من خلال محاولاتها هذا مبكرًا، ويظهر تحليلنا لـ منطق إعادة المحاولة لواجهات برمجة التطبيقات عالية المخاطر أين يمكن أن تتسبب إعادة المحاولة غير المبالية في ضرر حقيقي.
تعيين مهلة زمنية لكل استدعاء
تساعد إعادة المحاولة فقط إذا فشل الطلب. الحالة الأسوأ هي طلب لا يعود أبدًا: تبعية تقبل اتصالك، ثم تتوقف. بدون مهلة زمنية، يتم حظر استدعاء الأداة وتتوقف العملية بأكملها خلف مقبس واحد معطل. لا يوجد خطأ، ولا استعادة، فقط وكيل عالق يحرق وقت التنفيذ وميزانية الرمز المميز على لا شيء.
كل استدعاء خارجي يحتاج إلى مهلة زمنية. قم بتعيين مهلة اتصال (connect timeout) لإنشاء الاتصال ومهلة قراءة (read timeout) للانتظار على الاستجابة، ثم ميزانية إجمالية لتشغيل الوكيل بالكامل حتى لا تتمكن سلسلة من الاستدعاءات البطيئة ولكن القانونية من تجاوز صبر المستخدم. عندما تنتهي مهلة، تعامل معها كأي خطأ آخر يمكن إعادة المحاولة فيه: تراجع وحاول مرة أخرى، حتى تصل إلى الحد الأقصى.
اختر الأرقام من زمن الاستجابة الحقيقي، وليس تخمينًا. اضبط كل مهلة زمنية أعلى من نسبة 99 في المائة (p99) للتبعية مع مساحة إضافية. إذا كانت ضيقة جدًا، فإنك تلغي استدعاءات كانت ستنجح. وإذا كانت فضفاضة جدًا، فإن تبعية عالقة تربط الوكيل لفترة طويلة بعد نقطة الفائدة. امنح الاستجابات المتدفقة ميزانيتها الخاصة، نظرًا لأن الإكمال الطويل يكون بطيئًا بشكل مشروع، والمهلة الزمنية الثابتة القصيرة تقتله في منتصف التدفق.
تشغيل قاطع الدائرة عندما تكون تبعية معطلة
يتعامل التراجع التدريجي مع خدمة مشغولة لفترة وجيزة. إنه الأداة الخاطئة لخدمة معطلة تمامًا. إذا كانت تبعية تفشل منذ دقيقة، فمن شبه المؤكد أن الطلب التالي سيفشل أيضًا، وإعادة محاولته تزيد من الحمل على شيء معطل بالفعل بينما ينتظر المستخدم فشلًا كان بإمكانك توقعه.
يصلح قاطع الدائرة هذا بثلاث حالات. المغلق هو الحالة الطبيعية: تتدفق الطلبات ويحسب القاطع الإخفاقات. عندما تتجاوز الإخفاقات عتبة معينة، ينتقل إلى حالة الفتح: يتوقف عن إرسال الطلبات ويفشل بسرعة لفترة تهدئة، حتى لا تدفع تكلفة المهلة الزمنية في كل استدعاء لخدمة معطلة. بعد هذه الفترة، يصبح شبه مفتوح ويسمح بمرور طلب اختبار واحد. إذا نجح طلب الاختبار، يغلق القاطع ويستأنف حركة المرور؛ وإذا فشل، يفتح مرة أخرى وينتظر.
بالنسبة للوكيل، يحوّل القاطع عبارة "واجهة برمجة تطبيقات الدفع معطلة" إلى فشل واحد سريع ونظيف يمكن للوكيل التعامل معه، بدلاً من أربعين مهلة زمنية بطيئة تستنزف ميزانية الرمز والوقت. قم بتوصيله لكل تبعية على حدة، وليس عالميًا، حتى لا توقف واجهة برمجة تطبيقات بحث معطلة الوكيل عن استخدام واجهة برمجة تطبيقات فواتير سليمة.
اجعل عمليات إعادة المحاولة آمنة باستخدام مفاتيح الثبات
كل نمط حتى الآن يفترض أن إعادة المحاولة آمنة. غالبًا ما لا تكون كذلك. يرسل وكيلك POST /charge، يعالج الخادم الطلب، وتنتهي مهلة الاستجابة في طريق العودة. لم يرَ الوكيل النجاح أبدًا، لذا يعيد المحاولة، والآن تم تحصيل المبلغ من العميل مرتين. لقد فعلت إعادة المحاولة بالضبط ما طلبته. كان التصميم هو الخطأ.
يُسد مفتاح الثبات (Idempotency Key) هذه الفجوة. ينشئ العميل مفتاحًا فريدًا لكل إجراء منطقي ويرسله مع الطلب، عادةً كعنوان Idempotency-Key. يسجل الخادم المفتاح عند الاستلام الأول، وإذا رأى نفس المفتاح مرة أخرى، فإنه يعيد النتيجة الأصلية بدلاً من تنفيذ العمل مرتين. الآن، تصبح إعادة المحاولة آمنة بطبيعتها: طلب POST /charge الثاني بنفس المفتاح هو عملية لا تفعل شيئًا سوى إعادة الشحن الأول.
يجب أن يظل المفتاح ثابتًا عبر عمليات إعادة المحاولة لنفس الإجراء ويتغير بين الإجراءات المختلفة. قم بتوليده مرة واحدة عند بناء الطلب، وليس داخل حلقة إعادة المحاولة، وإلا ستحصل كل محاولة على مفتاح جديد ولن يتم إلغاء التكرار أبدًا. تحتاج أي استدعاء أداة ينشئ أو يغير حالة (الرسوم، الطلبات، رسائل البريد الإلكتروني، السجلات) إلى مفتاح. يغطي دليلنا حول مفاتيح الثبات التوليد والتعامل على جانب الخادم بالكامل.
النجاة من حدود المعدل وحلقة خطأ تجاوز حد المعدل
تستحق حدود المعدل معالجة خاصة بها لأنها تأتي مع تعليمات. تصل استجابة تجاوز حد المعدل عادةً كرمز 429 تحمل رأس Retry-After يخبرك بالضبط كم من الوقت يجب أن تنتظر، بالثواني أو كتاريخ. احترم ذلك. إذا قال الخادم انتظر 30 ثانية وقمت بإعادة المحاولة في ثانيتين، فستتلقى رمز 429 آخر، وقد بنيت حلقة RateLimitError التي تملأ لوحة مناقشة SDK: التقط الحد، أعد المحاولة مبكرًا جدًا، يتم تحديدك بشكل أقوى، كرر حتى تتوقف العملية. يغطي موضوع SDK منفصل نفس الجدار الذي يواجهه المطورون هنا.
الحل هو السماح للخادم بتحديد الوتيرة. عندما تتلقى رمز 429، اقرأ Retry-After وانتظر على الأقل تلك المدة قبل إعادة المحاولة. إذا كان الرأس مفقودًا، عد إلى التراجع التدريجي الأسي مع الارتعاش. حدد عدد المحاولات بحيث ينتهي الحد المستمر بفشل نظيف بدلاً من انتظار لا نهائي. يحترم Anthropic SDK بالفعل Retry-After لاستدعاءاته الخاصة؛ والعمل هو تطبيق نفس القاعدة على واجهات برمجة التطبيقات الأخرى ذات الحدود الزمنية التي يستخدمها وكيلك.
هناك جانب استباقي أيضًا. إذا سمح مزود بعدد معين من الطلبات في الدقيقة، قم بقياس استدعاءاتك الخاصة باستخدام "سلة الرموز" (token bucket) بحيث تبقى تحت الحد الأقصى بدلاً من اكتشافه عن طريق التقييد. تعالج الاستعادة الحدود التي تضربها؛ ويمنعك التوقيت من الوصول إليها.
كيفية اختبار مسار الاستعادة
الآن، دعنا نجمع كل ذلك. الأنماط المذكورة أعلاه جيدة فقط بقدر إثباتك لتشغيلها، والإثبات هو اختبار يجبر على حدوث الأعطال التي لن توفرها لك واجهة برمجة تطبيقات سليمة. يتكرر الشكل في كل سيناريو:
- محاكاة التبعية. قم بإعداد محاكاة لواجهة برمجة التطبيقات التي تستدعيها أداة وكيلك، بحيث تتحكم في كل رمز حالة، ورأس، وجسم طلب، وتأخير، ولا تحدث أي رسوم حقيقية أو إرسال بريد إلكتروني أثناء الاختبار.
- برمجة تسلسل. قم ببرمجة المحاكاة للرد على سلسلة من الاستدعاءات بالترتيب: أولاً رمز 429 مع
Retry-After: 2، ثم رمز 500، ثم رمز 200 مع جسم طلب صالح. نقطة نهاية واحدة، ثلاث استجابات مبرمجة، قوس استعادة كامل في تشغيل واحد. - شغل الوكيل على المحاكاة. وجه أداة الوكيل إلى عنوان URL الخاص بالمحاكاة بدلاً من الخدمة الحقيقية وقم بتشغيل السيناريو من البداية إلى النهاية.
- تأكيد السلوك. تحقق مما يهم: هل انتظر الوكيل 2 ثانية على الأقل بعد رمز 429 قبل إعادة المحاولة، هل أعاد المحاولة بعد رمز 500، هل نجح في الاستدعاء الثالث، وهل لم يتجاوز الحد الأقصى لعدد المحاولات لديك.
يثبت هذا السيناريو الواحد التراجع التدريجي وRetry-After في تمريرة واحدة. أضف سيناريو ثانيًا لمسار التخلي: قم ببرمجة المحاكاة للفشل في كل مرة وتأكد من أن الوكيل يتوقف عند الحد الأقصى ويعيد خطأ نظيفًا بدلاً من الدوران في حلقة. أضف سيناريو ثالثًا لقاطع الدائرة: افشل عددًا كافيًا من الاستدعاءات على التوالي وتأكد من أن الوكيل يتعثر ويفشل بسرعة بدلاً من دفع مهلة زمنية في كل محاولة.
فحص الثبات هو الذي يتجاهله الناس، وهو الذي يوفر المال. قم ببرمجة المحاكاة لقبول استدعاء متغير (mutating call)، ثم إسقاط الاستجابة بحيث يعتقد الوكيل أنها فشلت، ثم قبول إعادة المحاولة. الآن تأكد من شكل الطلب: هل حمل كلا الطلبين نفس Idempotency-Key، وهل رأت المحاكاة إجراءً منطقيًا واحدًا وليس اثنين. مفتاح جديد عند إعادة المحاولة، أو استدعاء مكرر، يعني أنك وجدت إرسالًا مزدوجًا قبل أن يفعله العميل. تحدد الطريقة الأوسع لـ اختبار الوكلاء الذين يستدعون واجهات برمجة التطبيقات الخاصة بك الإعداد الكامل من البداية إلى النهاية.
قائمة مراجعة استعادة الأخطاء
قبل أن ينتقل الوكيل إلى مرحلة الإنتاج، راجع هذه القائمة:
- كل استدعاء خارجي يحتوي على مهلة اتصال، ومهلة قراءة، وميزانية تشغيل إجمالية.
- تستخدم عمليات إعادة المحاولة التراجع التدريجي الأسي مع الارتعاش، بحد أقصى للتأخير وعدد المحاولات.
- تقرأ استجابات 429 وتلتزم برأس
Retry-After، مع استخدام التراجع التدريجي كخيار احتياطي. - يتم تشغيل قاطع دائرة لكل تبعية بحيث تفشل الخدمة المعطلة بسرعة بدلاً من الدوران في حلقة.
- كل استدعاء يغير الحالة يحمل مفتاح ثبات مستقر يبقى صالحًا عبر عمليات إعادة المحاولة.
- مسار التخلي يعيد خطأ نظيفًا، وليس انتظارًا لا نهائيًا.
- تم إثبات كل من هذه البنود باختبار يجبر على حدوث الفشل مقابل محاكاة، ولا يتم افتراضه.
حدد جميع البنود السبعة، وسيتعافى وكيلك عن قصد بدلاً من الحظ.
أين يتناسب Apidog (وأين لا يتناسب)
حافظ على نزاهة عمل الأداة. Apidog ليس إطار عمل للوكيل، أو مضيف نموذج، أو بيئة تشغيل. إنه لا يبني، أو يشغل، أو ينسق وكيلك، ولا يقيم مخرجات النموذج. ما يمتلكه هو طبقة واجهة برمجة التطبيقات التي يستدعيها وكيلك، وهو بالضبط المكان الذي يتم فيه كسب أو خسارة الاستعادة.
يمنحه ذلك ثلاث مهام. يقوم بمحاكاة التبعيات التي يضربها وكيلك، لتحصل على بديل قابل للتحكم بدلاً من الخدمة الحية. يقوم ببرمجة استجابات الفشل (429 مع Retry-After، 500، مهلة زمنية، جسم طلب غير سليم) التي لن تنتجها واجهة برمجة تطبيقات حقيقية عند الطلب، حتى تتمكن من التدرب على الاستعادة. ويقوم بالتحقق من صحة الطلبات التي تتلقاها المحاكاة (مفتاح الثبات موجود وثابت، الشكل الصحيح، عدد الاستدعاءات المتوقع) بحيث يفشل الإرسال المزدوج أو الرأس المفقود في اختبار بدلاً من فشله مع العميل. هذا هو التوافق الصادق: Apidog يحاكي الإخفاقات التي يجب أن ينجو منها وكيلك ويتحقق مما يعيده.
الأسئلة الشائعة
ألا يتعامل Anthropic SDK مع عمليات إعادة المحاولة نيابة عني؟ لاستدعاءاته الخاصة، نعم. يقوم SDK بإعادة محاولة أخطاء معينة مع التراجع التدريجي الأسي ويحترم Retry-After، وتحدد الحد الأقصى بخيار الحد الأقصى للمحاولات. لا يغطي واجهات برمجة التطبيقات الأخرى التي تستدعيها أدوات وكيلك. تحتاج هذه إلى نفس الأنماط المطبقة من قبلك.
متى أحتاج إلى مفتاح ثبات؟ في أي استدعاء ينشئ أو يغير حالة: رسوم، طلبات، رسائل مرسلة، سجلات جديدة. تعتبر الاستدعاءات للقراءة فقط آمنة لإعادة المحاولة بدون مفتاح ثبات. قم بإنشاء المفتاح مرة واحدة لكل إجراء حتى يظل ثابتًا عبر عمليات إعادة المحاولة.
تدرب على فشل واحد هذا الأسبوع
ليس عليك بناء الأنماط الأربعة كلها في وقت واحد. اختر النمط الذي قد يسبب أكبر ضرر، عادةً حلقة حد المعدل أو إعادة المحاولة غير الثابتة، وتدرب عليه مقابل محاكاة. قم ببرمجة الرمز 429، أسقط استجابة، وراقب ما يرسله الوكيل. في المرة الأولى التي ترى فيها تراجعًا تدريجيًا نظيفًا ومفتاح ثبات واحد حيث كنت تخشى شحنًا مزدوجًا، ستثق بالوكيل لسبب أفضل من عرض توضيحي أخضر.
قم بتنزيل Apidog لمحاكاة الأعطال، وبرمجة التسلسل، والتأكد من تصرف وكيلك عندما تواجه واجهة برمجة التطبيقات مشاكل.