טיפול בשגיאות, הגבלת קצב וניהול מכסות

כשמבצעים שאילתות ב-Developer Knowledge API או בשרת Developer Knowledge MCP באפליקציות ובסוכני AI בייצור, צריך לנהל את השגיאות ואת המכסות כדי להשיג ביצועים גבוהים.

במדריך הזה תלמדו איך:

  • הטמעת השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff) עם רעידות לתגובות HTTP 429.
  • טיפול בקודי שגיאה קנוניים של gRPC ‏ (INVALID_ARGUMENT, ‏ PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • ניהול פסק זמן לחיבור ל-MCP ולוגיקה של ניסיון חוזר.
  • מיישמים שיטות מומלצות לניהול מכסות ולשמירת נתונים במטמון.

הגבלת קצב של יצירת בקשות (HTTP 429) והשהיה מעריכית לפני ניסיון חוזר (exponential backoff)

אם קצב הבקשות חורג ממכסת ה-API שמוגדרת כברירת מחדל, השירות מחזיר שגיאה HTTP 429 Too Many Requests. האפליקציות צריכות להטמיע לוגיקה של ניסיונות חוזרים באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff) עם רעידות, כדי למנוע עומס יתר על השירות.

קיטוע השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

אפשר לחשב את העיכובים בין ניסיונות חוזרים באמצעות הנוסחה הבאה:

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 מפתח ה-API או טוקן ה-OAuth Bearer חסרים, פג התוקף שלהם או שהם לא תקינים. לא לנסות שוב. מרעננים את פרטי הכניסה או יוצרים מפתח API תקין.
PERMISSION_DENIED 403 Forbidden למפתח ה-API אין הרשאה או שממשק Developer Knowledge API מושבת בפרויקט. לא לנסות שוב. מוודאים שה-API מופעל במסוף Google Cloud.
NOT_FOUND 404 Not Found נתיב המסמך שצוין, parent, לא קיים. הפעולה BatchGetDocuments נכשלת באופן אטומי אם לא נמצא אף אחד מהמסמכים המבוקשים. לא לנסות שוב. מאמתים את שם המשאב של המסמך.
RESOURCE_EXHAUSTED 429 Too Many Requests הייתה חריגה מהגבלת הקצב של יצירת בקשות או ממכסת הפרויקט. ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם רעידות.
UNAVAILABLE 503 Service Unavailable ניתוק זמני מהרשת או הפעלה מחדש של השרת. ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
DEADLINE_EXCEEDED 504 Gateway Timeout הבקשה חרגה מהזמן הקצוב לתפוגה שהוגדר לקריאה לשירות מרוחק (RPC) לפני שהושלמה. מנסים שוב עם הגדלת הזמן הקצוב לתפוגה של RPC של הלקוח.

זמן קצוב לתפוגה של חיבור ל-MCP וניהול שגיאות

שרת ה-MCP של Developer Knowledge הוא שירות מרוחק שמתארח בכתובת https://developerknowledge.googleapis.com/mcp ומתבצעת אליו גישה באמצעות HTTPS (באמצעות HTTP POST או Server-Sent Events). מנחים וסוכני AI צריכים לנהל את פסק הזמן של החיבור ואת שגיאות הכלים בצורה חלקה.

הזמן הקצוב להרצת הכלי

כשנציג מפעיל את search_documents,‏ get_documents או answer_query, יכול להיות שהזמן הקצוב לתפוגה של קריאות לכלים (לדוגמה, 30 שניות) יחרוג מהחלון אם יש עיכובים בחיבורים לרשת.

כדי לטפל במקרים שבהם מסתיים הזמן הקצוב לתפוגה של הרצת הכלי:

  • הגדרת פסק זמן (timeout) ללקוח: מגדירים פסק זמן לביצוע כלי של 30 עד 60 שניות בהגדרות של לקוח המארח של MCP.
  • טיפול בהפרעות ברשת: ניסיון חוזר של בקשות HTTP שנכשלו עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) אם יש נפילות זמניות ברשת או תגובות HTTP 503.
  • בדיקת הודעות שגיאה: ניתוח של הודעות שגיאה רגילות של JSON-RPC או של קודי סטטוס של שגיאות HTTP כדי להבחין בין ארגומנטים לא תקינים לבין חריגה ממכסה.

שיטות מומלצות לניהול מכסות

כדי לשמור על שימוש אופטימלי ב-API ולמנוע הגבלות קצב לא צפויות, כדאי לפעול לפי השיטות המומלצות הבאות:

  1. שמירת תוכן של מסמכים שאוחזרו במטמון: אחסון מקומי או במטמון (כמו Redis) של מסמכי Markdown שנמשכו, כשמפתחים אפליקציות שגולשות באותם דפים בתדירות גבוהה.
  2. שימוש באחזור באצווה: שימוש ב-documents.batchGet במקום לבצע כמה בקשות documents.get ברצף.
  3. אופטימיזציה של שדות שאילתה: בקשה רק של שדות התגובה הנדרשים באמצעות אנונימיזציה סלקטיבית של שדות (fields=results(parent,content)).
  4. מעקב אחרי ניצול המכסה: אפשר לעקוב אחרי שיעורי הבקשות ל-API במרכז הבקרה ל-API של מסוף Google Cloud.

תוכן קשור