מדריך לפתרון בעיות

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

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

קודי שגיאה

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

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

אם קיבלתם שגיאה שמציינת שצריך לנסות שוב את הבקשה (כמו 429 RESOURCE_EXHAUSTED או 503 UNAVAILABLE), מומלץ להטמיע אסטרטגיית השהיה מעריכית לפני ניסיון חוזר (exponential backoff). המשמעות היא שצריך להמתין זמן קצר לפני הניסיון החוזר הראשון, ואז להגדיל בהדרגה את זמן ההמתנה בין הניסיונות החוזרים הבאים.

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

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

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

בדיקת הקריאות ל-API כדי לאתר שגיאות בפרמטרים של המודל

מוודאים שהפרמטרים של המודל נמצאים בטווח הערכים הבא:

פרמטר של מודל ערכים (טווח)
מספר המועמדים ‫1-8 (מספר שלם)
טמפרטורה ‫0.0 עד 1.0
מספר מקסימלי של טוקנים בפלט בדף המודלים אפשר לבדוק מה המספר המקסימלי של טוקנים במודל שבו אתם משתמשים.
TopP 0.0-1.0

בנוסף לבדיקת ערכי הפרמטרים, ודאו שאתם משתמשים בגרסת ה-API הנכונה (למשל, /v1 או /v1beta) ובמודל שתומך בתכונות שאתם צריכים. לדוגמה, אם תכונה מסוימת נמצאת בגרסת בטא, היא תהיה זמינה רק בגרסת API‏ /v1beta.

איך בודקים אם יש לכם את המודל הנכון

מוודאים שאתם משתמשים במודל נתמך שמופיע בדף המודלים.

זמן אחזור ארוך יותר או שימוש רב יותר בטוקנים עם מודלים של חשיבה

השהיה גבוהה יותר או שימוש באסימונים מתרחשים לעיתים קרובות כי במודלים של Gemini 3.x מופעלת חשיבה כברירת מחדל. גם מודלים של Gemini 2.5 שהוצאו משימוש משתמשים בחשיבה כברירת מחדל.

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

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

פרטים על ההגדרה ודוגמאות קוד מופיעים במדריך לתכנון.

בעיות בטיחות

אם אתם רואים שהנחיה נחסמה בגלל הגדרת בטיחות בקריאה ל-API, בדקו את ההנחיה בהתאם למסננים שהגדרתם בקריאה ל-API.

אם מופיע הסמל BlockedReason.OTHER, יכול להיות שהשאילתה או התשובה מפרות את התנאים וההגבלות או שהן לא נתמכות מסיבה אחרת.

בעיה בהקראה

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

בעיה של טוקנים חוזרים

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

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

כדי שהמודל ייצור טבלאות Markdown, מוסיפים להנחיה הוראות ספציפיות. צריך לספק דוגמאות שפועלות לפי ההנחיות האלה. אפשר גם לנסות לשנות את הטמפרטורה. כדי ליצור קוד או פלט מובנה מאוד כמו טבלאות Markdown, רמת אקראיות גבוהה (‎>= 0.8) עובדת טוב יותר.

הנה דוגמה להנחיות שאפשר להוסיף להנחיה כדי למנוע את הבעיה הזו: 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
טוקנים חוזרים בטבלאות Markdown בדומה למקפים החוזרים, זה קורה כשהמודל מנסה ליישר באופן חזותי את תוכן הטבלה. היישור ב-Markdown לא נדרש כדי שהעיבוד יהיה תקין.
  • נסו להוסיף להנחיית המערכת הוראות כמו אלה: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • כדאי לנסות לשנות את הטמפרטורה. ערכים גבוהים יותר (‎>= 0.8) בדרך כלל עוזרים למנוע חזרות או כפילויות בפלט.
שורות חדשות חוזרות (\n) בפלט מובנה אם קלט המודל מכיל רצפי Unicode או רצפי escape כמו \u או \t, יכול להיות שיופיעו שורות חדשות חוזרות.
  • בודקים אם יש בהנחיה רצפי Escape אסורים ומחליפים אותם בתווים בתקן UTF-8. לדוגמה, אם בדוגמאות של JSON יש רצף escape של \u, המודל עלול להשתמש בו גם בפלט שלו.
  • לתת למודל הוראות לגבי תווים מיוחדים מותרים. מוסיפים הוראה למערכת כמו זו: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
חזרה על טקסט בפלט מובנה אם סדר השדות בפלט מהמודל שונה מסדר השדות בסכימה המובנית שהוגדרה, הדבר עלול לגרום לחזרה על טקסט.
  • אל תציינו את סדר השדות בהנחיה.
  • כל שדות הפלט הם שדות חובה.
קריאה חוזרת לכלי זה יכול לקרות אם המודל מאבד את ההקשר של מחשבות קודמות או אם הוא נאלץ לבצע קריאה לנקודת קצה לא זמינה. הוראות למודל לשמור על מצב בתהליך החשיבה שלו. מוסיפים את הטקסט הבא בסוף ההוראות למערכת: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
טקסט שחוזר על עצמו ולא מהווה חלק מהפלט המובנה זה יכול לקרות אם המודל נתקע בבקשה שהוא לא יכול לפתור.
  • אם התכונה 'חשיבה' מופעלת, אל תתנו הוראות מפורשות לגבי אופן הפתרון של בעיה בהוראות. פשוט בקשו את הפלט הסופי.
  • נסו טמפרטורה גבוהה יותר, למשל ‎>= 0.8.
  • מוסיפים הוראות כמו "תמציתי", "אל תחזור על עצמך" או "תספק את התשובה פעם אחת".

מפתחות API חסומים או לא תקינים

בקטע הזה מוסבר איך לבדוק אם מפתח ה-API של Gemini חסום ומה לעשות במקרה כזה.

למה מפתחות נחסמים

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

אישור אם המפתחות מושפעים

אם ידוע שהמפתח שלכם הודלף, לא תוכלו יותר להשתמש במפתח הזה עם Gemini API. אתם יכולים להשתמש ב-Google AI Studio כדי לבדוק אם אחד ממפתחות ה-API שלכם חסום לשליחת קריאות ל-Gemini API, וליצור מפתחות חדשים. יכול להיות שתוצג גם השגיאה הבאה כשמנסים להשתמש במפתחות האלה:

Your API key was reported as leaked. Please use another API key.

פעולה למפתחות API חסומים

מומלץ ליצור מפתחות API חדשים לשילובים של Gemini API באמצעות Google AI Studio. מומלץ מאוד לבדוק את שיטות הניהול של מפתחות ה-API כדי לוודא שהמפתחות החדשים מאובטחים ולא חשופים באופן ציבורי.

חיובים לא צפויים בגלל נקודת חולשה

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

אמצעי האבטחה של Google למפתחות שדלפו

איך Google תעזור לי להגן על החשבון מפני חריגה מהעלויות וניצול לרעה במקרה של דליפת מפתחות ה-API?

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

שיפור הפלט מהמודל

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

הסבר על מגבלות הטוקנים

במדריך שלנו בנושא אסימונים מוסבר איך סופרים אסימונים ומהן המגבלות שלהם.

בעיות מוכרות

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

דיווח על באג

אם יש לכם שאלות, אתם יכולים להצטרף לדיון בפורום המפתחים של Google AI.