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

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

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

קודי שגיאה

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

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

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

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

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

  • שימוש בהשהיה מעריכית לפני ניסיון חוזר: ממתינים זמן קצר לפני הניסיון החוזר הראשון (לדוגמה, שנייה אחת), ואז מגדילים את העיכוב באופן מעריכי (לדוגמה, 2 שניות, 4 שניות, 8 שניות).
  • הוספת תנודות: הוספת תנודות אקראיות לעיכוב כדי למנוע מכל הלקוחות לנסות שוב בדיוק באותו הזמן.
  • ניסיון חוזר בשגיאות ספציפיות: כדאי לנסות שוב רק בשגיאות זמניות (כמו 429, 408 או 5xx). לא כדאי לנסות שוב בשגיאות לקוח (כמו 400 או 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 חסומים או לא תקינים

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

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

זיהינו נקודת חולשה שבה יכול להיות שחלק ממפתחות ה-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 שלי ידלפו?

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

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

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

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

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

בעיות מוכרות

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

דיווח על באג

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