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

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

در این راهنما، شما یاد خواهید گرفت که چگونه:

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

محدود کردن سرعت HTTP 429 و کاهش نمایی

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

پس‌روی نمایی کوتاه‌شده

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

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

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

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

مدیریت خطاهای gRPC

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

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

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

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

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

سرور Developer Knowledge MCP یک سرویس از راه دور است که در آدرس https://developerknowledge.googleapis.com/mcp میزبانی می‌شود و از طریق HTTPS (با استفاده از HTTP POST یا Server-Sent Events) قابل دسترسی است. میزبان‌ها و عامل‌های هوش مصنوعی باید وقفه‌های اتصال و خطاهای ابزار را به طور مناسب مدیریت کنند.

وقفه‌های اجرای ابزار

وقتی یک عامل، search_documents ، get_documents یا answer_query فراخوانی می‌کند، در صورت تأخیر در اتصالات شبکه، فراخوانی‌های ابزار ممکن است از پنجره‌های زمانی انقضا (مثلاً 30 ثانیه) فراتر رود.

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

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

بهترین شیوه‌های مدیریت سهمیه

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

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

مطالب مرتبط