معالجة الأخطاء والحدّ من عدد الطلبات وإدارة الحصص

عند طلب البحث من واجهة برمجة التطبيقات Developer Knowledge API أو خادم Developer Knowledge MCP في التطبيقات المتاحة للإنتاج ووكلاء الذكاء الاصطناعي، يجب توفير معالجة الأخطاء وإدارة الحصة لتحقيق أداء عالٍ.

في هذا الدليل، سنتعرّف على كيفية:

  • تنفيذ خوارزمية الرقود الأسي الثنائي المقتطع مع التشويش لاستجابات HTTP 429
  • التعامل مع رموز الخطأ الأساسية في gRPC (INVALID_ARGUMENT وPERMISSION_DENIED وRESOURCE_EXHAUSTED)
  • إدارة مهلات الاتصال ببروتوكول MCP ومنطق إعادة المحاولة
  • تطبيق أفضل الممارسات المتعلّقة بإدارة الحصص والتخزين المؤقت

الحدّ من معدّل الزحف باستخدام رمز الحالة HTTP 429 وأسلوب التراجع الدليلي

عندما تتجاوز معدّلات الطلبات حصة واجهة برمجة التطبيقات التلقائية، تعرض الخدمة الخطأ HTTP 429 Too Many Requests. يجب أن تنفّذ التطبيقات منطق إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي المقتطع مع التشويش لتجنُّب إرهاق الخدمة.

خوارزمية الرقود الأسي الثنائي المقتطعة

احتساب فترات التأخير بين المحاولات باستخدام الصيغة التالية:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

استخدِم المَعلمات التالية لاحتساب فترات التأخير بين المحاولات:

  • ‫initial_delay: تأخير إعادة المحاولة الأوّلية (على سبيل المثال، ثانية واحدة).
  • ‫max_delay: الحدّ الأقصى للتراجع (على سبيل المثال، 32.0 ثانية).
  • ‫attempt: عدد محاولات إعادة التشغيل الحالية (0 أو 1 أو 2 أو غير ذلك)
  • ‫jitter: قيمة عشوائية بين 0 و1.0 ثانية لمنع حدوث ارتفاعات مفاجئة في مزامنة سلاسل المحادثات (مشكلة القطيع الصاخب).

معالجة الأخطاء في gRPC

يجب أن تفحص التطبيقات التي تصل إلى الخدمة عبر gRPC قيم grpc.StatusCode الأساسية.

رموز الحالة العادية في gRPC

يسرد الجدول التالي رموز حالة gRPC الأساسية التي تعرضها الخدمة والطريقة المقترَحة التي يجب أن يتعامل بها العميل معها:

رمز حالة gRPC رموز حالة HTTP السبب الأساسي الإجراء المقترَح
INVALID_ARGUMENT 400 Bad Request سلسلة طلب بحث مكتوبة بشكل غير صحيح أو تنسيق مَعلمة غير صالح أو قناع حقل غير صالح عدم إعادة المحاولة يُرجى تصحيح مَعلمات الطلب قبل تكراره.
UNAUTHENTICATED 401 Unauthorized مفتاح واجهة برمجة التطبيقات أو رمز OAuth المميز للمالك غير متوفّر أو منتهي الصلاحية أو تمت صياغته بشكلٍ غير صحيح عدم إعادة المحاولة أعِد تحميل بيانات الاعتماد أو أنشئ مفتاحًا صالحًا لواجهة برمجة التطبيقات.
PERMISSION_DENIED 403 Forbidden لا يتوفّر الإذن لمفتاح واجهة برمجة التطبيقات أو أنّ واجهة Developer Knowledge API غير مفعّلة في المشروع. عدم إعادة المحاولة تأكَّد من تفعيل واجهة برمجة التطبيقات في Google Cloud Console.
NOT_FOUND 404 Not Found مسار المستند parent المحدّد غير متوفّر. يفشل BatchGetDocuments بشكل ذري إذا لم يتم العثور على أي مستند مطلوب. عدم إعادة المحاولة تحقَّق من اسم مورد المستند.
RESOURCE_EXHAUSTED 429 Too Many Requests تم تجاوز الحد المسموح به لمعدّل الإرسال أو الحد المسموح به لحصة المشروع. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي مع التشويش.
UNAVAILABLE 503 Service Unavailable انقطاع مؤقت في الشبكة أو إعادة تشغيل الخادم أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
DEADLINE_EXCEEDED 504 Gateway Timeout تجاوز الطلب الموعد النهائي المحدّد لطلب استدعاء الإجراء عن بُعد (RPC) قبل اكتماله. أعِد المحاولة مع زيادة المهلة الزمنية لطلب الإجراء عن بُعد (RPC) من العميل.

انتهاء مهلة اتصال منصّة إدارة الموافقة وإدارة الأخطاء

خادم Developer Knowledge MCP هو خدمة عن بُعد مستضافة على https://developerknowledge.googleapis.com/mcp ويمكن الوصول إليها عبر HTTPS (باستخدام HTTP POST أو Server-Sent Events). على المضيفين والوكلاء بالذكاء الاصطناعي إدارة مهل الاتصال وأخطاء الأدوات بشكل سليم.

انتهاء مهلات تنفيذ الأدوات

عندما يستدعي أحد الوكلاء search_documents أو get_documents أو answer_query، قد تتجاوز مدة استدعاء الأدوات مهلة الاستجابة (على سبيل المثال، 30 ثانية) إذا كان هناك تأخير في اتصالات الشبكة.

للتعامل مع حالات انتهاء المهلة أثناء تنفيذ الأدوات، اتّبِع الخطوات التالية:

  • ضبط مهلات العميل: اضبط مهلات تنفيذ الأداة على 30 إلى 60 ثانية في إعدادات عميل مضيف MCP.
  • التعامل مع انقطاعات الشبكة: إعادة محاولة طلبات HTTP التي تعذّر تنفيذها مع التمهّل بين عمليات إعادة المحاولة عند حدوث انقطاعات مؤقتة في الشبكة أو تلقّي استجابات HTTP 503.
  • فحص رسائل الخطأ: يمكنك تحليل رسائل الخطأ العادية بتنسيق JSON-RPC أو رموز حالة الخطأ بتنسيق HTTP للتمييز بين الوسيطات غير الصالحة والاستخدام المفرط للحصة.

أفضل الممارسات المتعلّقة بإدارة الحصص

اتّبِع أفضل الممارسات التالية للحفاظ على الاستخدام الأمثل لواجهة برمجة التطبيقات وتجنُّب حدود المعدّل غير المتوقّعة:

  1. تخزين محتوى المستند الذي تم استرجاعه مؤقتًا: يمكنك تخزين مستندات Markdown التي تم جلبها محليًا أو في ذاكرة تخزين مؤقت (مثل Redis) عند إنشاء تطبيقات تصل إلى الصفحات نفسها بشكل متكرر.
  2. استخدام عملية الاسترجاع المجمّع: استخدِم documents.batchGet بدلاً من تنفيذ طلبات documents.get متعدّدة ومتسلسلة.
  3. تحسين حقول طلب البحث: اطلب فقط حقول الردود المطلوبة باستخدام أقنعة الحقول الانتقائية (fields=results(parent,content)).
  4. مراقبة استهلاك الحصة: تتبُّع معدّلات طلبات بيانات من واجهة برمجة التطبيقات في لوحة بيانات واجهة برمجة التطبيقات في Google Cloud Console

محتوى ذو صلة