مدیریت خطا، محدودیت نرخ، و مدیریت سهمیه

وقتی در برنامه‌های تولیدی از سرور Developer Knowledge API یا Developer Knowledge MCP پُرسمان می‌کنید و در کارگزاران هوش مصنوعی باید مدیریت سهمیه و مدیریت خطا وجود داشته باشد تا عملکرد بالا به‌دست آید.

در این راهنما، با نحوه انجام این کارها آشنا می‌شوید:

  • برای پاسخ‌های HTTP 429، پس‌گیری نمایی کوتاه با لرزش پیاده‌سازی کنید.
  • کدهای خطای gRPC متعارف را مدیریت کنید (INVALID_ARGUMENT، PERMISSION_DENIED، RESOURCE_EXHAUSTED).
  • مدیریت کردن زمان‌های اتمام اتصال MCP و منطق تلاش مجدد.
  • روال‌های مطلوب مدیریت سهمیه و ذخیره کردن در حافظه نهان را اعمال کنید.

محدود کردن نرخ HTTP 429 و پس‌گیری نمایی

وقتی نرخ درخواست‌ها از سهمیه پیش‌فرض API فراتر رود، سرویس خطای HTTP 429 Too Many Requests برمی‌گرداند. برنامه‌ها باید منطق تلاش مجدد را بااستفاده از پس‌گرد نمایی کوتاه با لرزش پیاده‌سازی کنند تا از بار اضافی بر سرویس جلوگیری کنند.

عقب‌گرد نمایی کوتاه

تأخیرهای تلاش مجدد را بااستفاده از فرمول زیر محاسبه کنید:

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

از پارامترهای زیر برای محاسبه تأخیرهای تلاش مجدد استفاده کنید:

  • ‫initial_delay: تأخیر اولیه برای تلاش مجدد (برای مثال، ۱٫۰ ثانیه).
  • ‫max_delay: حداکثر ظرفیت بازگشت (برای مثال، ۳۲٫۰ ثانیه).
  • ‫attempt: تعداد تلاش‌های مجدد فعلی (۰، ۱، ۲، …).
  • jitter: مقدار تصادفی بین ۰ و ۱٫۰ ثانیه برای جلوگیری از جهش‌های همگام‌سازی رشته (مشکل گله تندر).

مدیریت خطای gRPC

برنامه‌هایی که ازطریق gRPC به سرویس دسترسی پیدا می‌کنند باید مقادیر grpc.StatusCode متعارف را بازرسی کنند.

کدهای وضعیت استاندارد gRPC

جدول زیر فهرست کدهای وضعیت متعارف gRPC برگردانده‌شده توسط سرویس و مدیریت توصیه‌شده مشتری را ارائه می‌دهد:

کد وضعیت gRPC وضعیت HTTP علت اصلی کنش توصیه‌شده
INVALID_ARGUMENT 400 Bad Request رشته پُرسمان قالب نادرست، قالب پارامتر نامعتبر، یا پوشش فیلد نامعتبر. امتحان مجدد نکنید. پیش‌از تکرار کردن، پارامترهای درخواست را اصلاح کنید.
UNAUTHENTICATED 401 Unauthorized کلید میانای برنامه‌سازی کاربردی یا کد OAuth Bearer وجود ندارد، منقضی شده است، یا قالب آن درست نیست. امتحان مجدد نکنید. اطلاعات اعتباری را بازآوری کنید یا کلید میانای برنامه‌سازی کاربردی معتبری تولید کنید.
PERMISSION_DENIED 403 Forbidden کلید میانای برنامه‌سازی کاربردی اجازه ندارد یا «میانای برنامه‌سازی کاربردی دانش توسعه‌دهنده» در پروژه غیرفعال است. امتحان مجدد نکنید. فعال‌سازی «میانای برنامه‌سازی کاربردی» را در کنسول Google Cloud درستی‌سنجی کنید.
NOT_FOUND 404 Not Found مسیر سند parent مشخص‌شده وجود ندارد. اگر هریک از سندهای درخواستی پیدا نشود، BatchGetDocuments به‌صورت اتمی ناموفق می‌شود. امتحان مجدد نکنید. نام منبع سند را درستی‌سنجی کنید.
RESOURCE_EXHAUSTED 429 Too Many Requests از حد مجاز نرخ یا سهمیه پروژه فراتر رفته‌اید. بااستفاده از عقب‌گرد نمایی با لرزش، دوباره امتحان کنید.
UNAVAILABLE 503 Service Unavailable قطع موقت اتصال شبکه یا بازراه‌اندازی سرور. با عقب‌گرد نمایی دوباره امتحان کنید.
DEADLINE_EXCEEDED 504 Gateway Timeout درخواست پیش‌از تکمیل از مهلت پیکربندی‌شده RPC فراتر رفت. با افزایش مهلت زمانی RPC مشتری دوباره امتحان کنید.

مدیریت خطا و اتمام زمان اتصال MCP

سرور MCP «دانش توسعه‌دهنده» سرویس از دور میزبانی‌شده در https://developerknowledge.googleapis.com/mcp است که ازطریق HTTPS (بااستفاده از HTTP POST یا «رویدادهای ارسال‌شده از سرور») به آن دسترسی پیدا می‌شود. میزبان‌ها و کارگزاران هوش مصنوعی باید مهلت‌های اتصال و خطاهای ابزار را به‌خوبی مدیریت کنند.

زمان‌های اتمام اجرای ابزار

وقتی کارگزاری search_documents، get_documents، یا answer_query را فرا می‌خواند، اگر اتصال شبکه تأخیر داشته باشد، تماس‌های ابزار ممکن است از بازه‌های زمانی اتمام مهلت (برای مثال، ۳۰ ثانیه) فراتر برود.

برای مدیریت کردن زمان‌های اتمام اجرای ابزار:

  • پیکربندی زمان‌های اتمام کارخواه: زمان‌های اتمام اجرای ابزار را روی ۳۰ تا ۶۰ ثانیه در پیکربندی کارخواه میزبان MCP تنظیم کنید.
  • مدیریت وقفه‌های شبکه: وقتی با افت موقت شبکه یا پاسخ‌های HTTP 503 مواجه می‌شوید، درخواست‌های HTTP ناموفق را با پس‌گیری نمایی دوباره امتحان کنید.
  • بازرسی پیام‌های خطا: پیام‌های خطای استاندارد JSON-RPC یا کدهای وضعیت خطای HTTP را تجزیه کنید تا آرگومان‌های نامعتبر را از اتمام سهمیه تشخیص دهید.

روال‌های مطلوب مدیریت سهمیه

برای حفظ استفاده بهینه از API و جلوگیری از محدودیت‌های نرخ غیرمنتظره، این روال‌های مطلوب را دنبال کنید:

  1. محتوای سند بازیابی‌شده را در حافظه نهان ذخیره کنید: هنگام ساختن برنامه‌هایی که به صفحات یکسان به‌طور مکرر دسترسی دارند، اسناد Markdown واکشی‌شده را به‌صورت محلی یا در حافظه نهان (مثل Redis) ذخیره کنید.
  2. استفاده از بازیابی دسته‌ای: به‌جای اجرای چندین درخواست documents.get متوالی، از documents.batchGet استفاده کنید.
  3. بهینه‌سازی فیلدهای پُرسمان: بااستفاده از پوشش‌های فیلد (fields=results(parent,content)) فقط فیلدهای پاسخ موردنیاز را درخواست کنید.
  4. پایش مصرف سهمیه: نرخ درخواست‌های API را در داشبورد API کنسول Google Cloud پیگیری کنید.

محتوای مرتبط