אסטרטגיה של ניסיון חוזר

ספריות הלקוח של Google Gen AI SDK כוללות לוגיקה של ניסיון חוזר אוטומטי עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) לטיפול בשגיאות זמניות כמו זמן קצוב לתפוגה, בעיות ברשת והגבלת קצב של יצירת בקשות (קודי סטטוס HTTP‏ 429 ו-5xx). לדוגמה, Python SDK מנסה באופן אוטומטי לתקן שגיאות זמניות עד ארבע פעמים עם השהיה ראשונית של כ-1 שניות והשהיה מקסימלית של 60 שניות. למרות ש-SDK מטפל בזה כברירת מחדל, אתם יכולים להגדיר את ההתנהגות הזו כך שתתאים יותר לעומס העבודה הספציפי שלכם.

קביעה מתי לנסות שוב

לפני שמטמיעים אסטרטגיה מותאמת אישית לניסיון חוזר, כדאי לחשוב איך בחירת נקודת הקצה, מודל התשלום ועומס העבודה משפיעים על הצרכים שלכם.

בחירת נקודת הקצה הנכונה

  • נקודת קצה גלובלית: מומלצת לזמינות. נקודת הקצה הגלובלית מנתבת את התנועה באופן דינמי, מה שיכול להפחית את הצורך בניסיונות חוזרים בצד הלקוח שנגרמים בגלל בעיות קיבולת אזוריות.
  • נקודות קצה אזוריות: מוגבלות למיקום ספציפי. אם אזור מסוים עמוס מדי, ניסיונות חוזרים מיידיים עלולים להיכשל. במקרה כזה, כדאי לשקול אסטרטגיות מעבר לגיבוי.

התאמה למודל התשלום

  • ‫Standard תשלום לפי שימוש: משתמש במשאבים משותפים. שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לטפל בשגיאות זמניות של הגבלת קצב (429) שנגרמות מעומסי תנועה.
  • ‫Flex תשלום לפי שימוש: מיועד לעיבוד איטי יותר של בקשות עם עדיפות נמוכה יותר. לא מומלץ לנסות שוב באופן אגרסיבי. במקום זאת, כדאי להגדיל את הזמן הקצוב לתפוגת הבקשה (למשל ל-30 דקות) כדי לתת למערכת זמן להשלים את המשימה.
  • ‫Priority pay-as-you-go: מיועד לעומסי עבודה שרגישים לזמן האחזור ודורשים רמת מהימנות גבוהה, בלי התחייבות מראש ל-Provisioned Throughput. אם מתקבלת שגיאה 429 ברמה הזו, צריך לנסות שוב עם נסיגה אקספוננציאלית, אבל לוודא שלא חורגים מהמכסה.
  • הקצאת משאבים לפי התפוקה שנקבעה: משתמש בקיבולת שמורה. שגיאות חוזרות ונשנות בדרך כלל מצביעות על כך שחרגתם מהקיבולת שרכשתם, ולכן הוספת ניסיונות חוזרים לא תפתור את הבעיה הבסיסית.

הגדרת סף סובלנות לזמן אחזור

  • בזמן אמת (לדוגמה, צ'אט): כדאי להיכשל מהר. הגבלת מספר הניסיונות החוזרים כדי שהמשתמשים לא יחכו לתשובה ללא הגבלת זמן.
  • הסקת מסקנות באצווה: אל תנסו לשלוח מחדש פריטים בודדים. שירות ה-Batch מטפל אוטומטית בניסיונות חוזרים של בקשות בודדות בעבודה, כדי להשיג שיעור גבוה של השלמת העבודה. האחריות היחידה שלכם היא לשלוח את המשימה פעם אחת. מידע נוסף זמין במאמר בנושא חיזוי באצווה.

זיהוי שגיאות שאפשר לנסות לתקן

יש שני גורמים עיקריים שקובעים אם בטוח לבצע ניסיון חוזר של בקשה:

תשובה

קוד השגיאה או התשובה שמתקבלים מציינים אם הבעיה היא זמנית או קבועה. בדרך כלל, אפשר לבצע ניסיון חוזר לתגובות שקשורות לבעיות זמניות. למשל:

  • קודי HTTP: 408 (זמן קצוב לתפוגה של בקשה), 429 (יותר מדי בקשות) ו-5xx (שגיאות שרת).
  • בעיות ברשת: זמנים קצובים לתפוגה של שקעים וניתוקים של TCP.

מידע נוסף מופיע במאמר שגיאות ב-API.

האידמפוטנטיות

אפשר להריץ בקשות אידמפוטנטיות שוב ושוב בלי לשנות את המצב הסופי של המשאב. כשקובעים את האידמפוטנטיות, חשוב להביא בחשבון את הנקודות הבאות:

  • תמיד אידמפוטנטיות: פעולות של רשימה (הן לא משנות את המשאבים), בקשות get, בקשות לספירת טוקנים ובקשות להטמעות.
  • לעולם לא אידמפוטנטיות: פעולות שיוצרות משאבים ייחודיים בכל פעם שהן מצליחות, כמו יצירת מודל חדש שעבר התאמה אישית.
  • הבדלים ב-AI גנרטיבי: למרות שהשיטה generateContent לא אידמפוטנטית באופן מוחלט בגלל האופי האקראי של מודלים גנרטיביים, בדרך כלל אפשר לנסות שוב במקרה של שגיאות זמניות, כי היא לא משנה את מצב צד השרת.

הגדרת ניסיונות חוזרים

‫Google Gen AI SDK מאפשר להגדיר התנהגות של ניסיון חוזר באמצעות פרמטרים של לקוח או HttpRetryOptions.

פרמטרים מרכזיים

  • ‫initial_delay: ההשהיה הראשונית בשניות לפני הניסיון החוזר הראשון (ברירת מחדל: 1.0).
  • ‫attempts: המספר המקסימלי של ניסיונות חוזרים (ברירת מחדל: 5).
  • ‫exp_base: הבסיס לחישוב ההשהיה המעריכית לפני ניסיון חוזר (ברירת מחדל: 2).
  • ‫max_delay: העיכוב המקסימלי בשניות בין ניסיונות חוזרים (ברירת מחדל: 60).
  • ‫jitter: פקטור להוספת עיכוב אקראי לנסיגה (ברירת מחדל: 1).
  • ‫http_status_codes: רשימה של קודי סטטוס שמפעילים ניסיון חוזר.

דוגמאות

הגדרות ברמת הלקוח

אפשר להגדיר אפשרויות באופן גלובלי כשמאתחלים את הלקוח.

Python

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location="global",
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            initial_delay=1.0,
            attempts=5,
            http_status_codes=[408, 429, 500, 502, 503, 504],
        ),
        timeout=120 * 1000,
    ),
)

Java

import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

HttpOptions httpOptions = HttpOptions.builder()
  .retryOptions(
      HttpRetryOptions.builder()
          .attempts(5)
          .httpStatusCodes(408, 429, 500, 502, 503, 504).build())
  .build();

Client client = Client.builder()
  .project(PROJECT_ID)
  .location("global")
  .vertexAI(true)
  .httpOptions(httpOptions)
  .build();

הגדרה ברמת הבקשה

אפשר גם לשנות את ההגדרות עבור בקשה יחידה באמצעות הפרמטר config.

Python

from google import genai
from google.genai import types

client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Tell me a joke about a rabbit.",
    config=types.GenerateContentConfig(
        http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                initial_delay=1.0,
                attempts=10,
                http_status_codes=[408, 429, 500, 502, 503, 504],
            ),
            timeout=120 * 1000,
        )
    )
)

תשלום לפי שימוש ב-Flex

בתוכנית Flex תשלום לפי שימוש, ברירת המחדל של הזמן הקצוב לתפוגה היא 10 דקות, בגלל עיבוד איטי יותר וניסיון חוזר שקוף. המשתמשים יכולים להגדיל את משך הזמן הזה ל-30 דקות כדי לשפר את שיעור ההצלחה.

Python

from google import genai
from google.genai import types

client = genai.Client(
  vertexai=True, project=PROJECT_ID, location='global',
  http_options=types.HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex" # Use Flex PayGo
      },
      timeout = 30 * 60 * 1000 # Increase to 30 minutes
  )
)

שיטות מומלצות ודפוסים בעייתיים

בין אם אתם משתמשים במנגנוני הניסיון החוזר שמוגדרים כברירת מחדל, מבצעים בהם התאמה אישית או מטמיעים לוגיקה משלכם לניסיון חוזר, כדאי לפעול לפי השיטות המומלצות האלה ולהימנע מדפוסי התנהגות נפוצים שעלולים לגרום לבעיות.

שיטות מומלצות

  • שימוש בהשהיה מעריכית לפני ניסיון חוזר: ממתינים זמן קצר לפני הניסיון החוזר הראשון (לדוגמה, שנייה אחת), ואז מגדילים את ההשהיה באופן מעריכי (לדוגמה, 2 שניות, 4 שניות, 8 שניות).
  • הוספת ג'יטר: הוספת ג'יטר אקראי לעיכוב עוזרת למנוע מצב שבו כל הלקוחות מנסים שוב בדיוק באותו הזמן.
  • ניסיון חוזר לתיקון שגיאות ספציפיות: רק שגיאות זמניות (429, ‏ 408, ‏ 5xx) יתוקנו בניסיון חוזר.
  • הגדרת מספר מקסימלי של ניסיונות חוזרים: הגדרת מספר מקסימלי של ניסיונות חוזרים כדי למנוע לולאות אינסופיות.
  • מעקב ורישום ביומן: כדאי לרשום ביומן פרטים על ניסיונות חוזרים, סוגי שגיאות וזמני תגובה כדי לנפות באגים באסטרטגיה.

ניסיון חוזר של אנטי-דפוסים

  • ניסיון חוזר ללא השהיה לפני ניסיון חוזר (backoff): ניסיון חוזר מיידי עלול לגרום לכשלים מדורגים ולהעמיס על השירות.
  • ניסיון חוזר בשגיאות שלא ניתן לבצע לגביהן ניסיון חוזר: אל תנסו לבצע ניסיון חוזר בשגיאות לקוח (4xx מלבד 429/408), כי הן מצביעות על בעיות כמו מפתחות API לא תקינים או תחביר שגוי.
  • ביצוע חוזר ללא תנאי של פעולות שהן לא אידמפוטנטיות: ביצוע חוזר של פעולות שהן לא אידמפוטנטיות עלול להוביל לתופעות לוואי, כמו משאבים כפולים.
  • התעלמות ממגבלות הניסיון החוזר: ניסיון חוזר ללא הגבלה עלול לגרום לניצול יתר של משאבים. לכן, חשוב תמיד להגדיר מספר מקסימלי של ניסיונות.

המאמרים הבאים