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

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

אם נתקלתם בבעיות במפתח API, ודאו שהגדרתם את מפתח ה-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,‏ 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 חסומים או לא תקינים

בקטע הזה מוסבר איך לבדוק אם מפתח 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.