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

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

מתי לנסות שוב

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

בחירת נקודת הקצה המתאימה

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

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

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

הגדרת טווח הגמישות של זמן האחזור

  • בזמן אמת (לדוגמה, צ'אט): עצירה מיידית במקרה שגיאה. הגבילו את מספר ניסיונות השליחה החוזרת כדי שהמשתמשים לא ימתינו לתגובה ללא הגבלת זמן.
  • הסקה באצווה: אל תנסו שוב פריטים בודדים. שירות 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 PayGo

ב-Flex PayGo, הזמן הקצוב לתפוגה שמוגדר כברירת מחדל הוא 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
  )
)

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

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

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

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

דפוסים לא מומלצים לניסיונות חוזרים

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

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