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

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

• generative-ai-python
• generative-ai-js
• generative-ai-android
• generative-ai-swift
• generative-ai-dart
• generative-ai-go

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

קודי שגיאה של שירות הקצה העורפי של Gemini API

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

קוד HTTP	סטטוס	תיאור	דוגמה	פתרון
400	INVALID_ARGUMENT	גוף הבקשה ערוך בצורה שגויה.	יש שגיאת הקלדה או שדה חובה חסר בבקשה.	בחומר העזר בנושא API תוכלו למצוא מידע על פורמט הבקשה, דוגמאות וגרסאות נתמכות. השימוש בתכונות מגרסת API חדשה יותר עם נקודת קצה ישנה יותר עלול לגרום לשגיאות.
400	FAILED_PRECONDITION	התוכנית ללא תשלום של Gemini API לא זמינה במדינה שלך. עליך להפעיל את החיוב בפרויקט ב-Google AI Studio.	הבקשה נשלחת באזור שבו אין תמיכה בתוכנית ללא תשלום, ולא הפעלת את החיוב בפרויקט ב-Google AI Studio.	כדי להשתמש ב-Gemini API, צריך להגדיר תוכנית בתשלום דרך Google AI Studio.
403	PERMISSION_DENIED	למפתח ה-API שלך אין את ההרשאות הנדרשות.	נעשה שימוש במפתח API שגוי; עבורך מנסים להשתמש במודל מכוונן בלי לעבור אימות מתאים.	מוודאים שמפתח ה-API מוגדר ושיש לו גישה מתאימה. בנוסף, חשוב לעבור אימות מתאים כדי להשתמש במודלים מכווננים.
404	NOT_FOUND	המשאב המבוקש לא נמצא.	לא מצאנו תמונה, אודיו או סרטון שמוזכרים בבקשה שלך.	בודקים אם כל הפרמטרים בבקשה תקינים בגרסת ה-API.
429	RESOURCE_EXHAUSTED	חרגת ממגבלת כמות התנועה.	שלחת יותר מדי בקשות בדקה באמצעות הגרסה החינמית של Gemini API.	חשוב לוודא שאתם עומדים במגבלת הקצב של יצירת הבקשות של המודל. מבקשים הגדלה של המכסה במקרה הצורך.
500	פנימי	אירעה שגיאה לא צפויה בצד של Google.	ההקשר שהזנת ארוך מדי.	מפחיתים את ההקשר להזנת הקלט או עוברים באופן זמני למודל אחר (למשל, מ-Gemini 1.5 Pro עד Gemini 1.5 Flash) ובודקים אם הוא עובד. אפשר גם להמתין זמן מה ולנסות שוב לשלוח את הבקשה. אם הבעיה נמשכת אחרי הניסיון החוזר, אפשר לדווח על כך באמצעות הלחצן שליחת משוב ב-Google AI Studio.
503	UNAVAILABLE	ייתכן שהשירות עמוס או מושבת באופן זמני.	הקיבולת של השירות נגמרה באופן זמני.	צריך לעבור באופן זמני לדגם אחר (למשל, מ-Gemini 1.5 Pro אל Gemini 1.5 Flash) ולבדוק אם הוא עובד. אפשר גם להמתין זמן מה ולנסות שוב לשלוח את הבקשה. אם הבעיה נמשכת אחרי הניסיון החוזר, אפשר לדווח על כך באמצעות הלחצן שליחת משוב ב-Google AI Studio.
504	DEADLINE_EXCEEDED	עיבוד השירות נכשל במסגרת המועד האחרון.	ההנחיה (או ההקשר) גדולים מדי ואי אפשר לעבד אותם בזמן.	הגדרת 'זמן קצוב לתפוגה' גדול יותר בבקשת הלקוח כדי להימנע מהשגיאה הזו.

קודי שגיאה של Python Client-SDK

בטבלה הבאה מפורטות הסיבות הנפוצות שגיאת Python client SDK קודים שאתם עשויים להיתקל בהם, יחד עם הסברים לגבי הסיבות שלהם:

סוג חריגה/שגיאה	מחלקה	תיאור
BlockedPromptException	google.generativeai.types.BlockedPromptException	ההצעה לפעולה חסומה מטעמי בטיחות.
BrokenResponseError	google.generativeai.types.BrokenResponseError	תגובה בסטרימינג לא תקינה. מושמעת כשניגשים למשהו שדורש את התשובה המלאה, כמו היסטוריית הצ'אט. אפשר לראות את פרטי השגיאה בדוח הקריסות.
IncompleteIterationError	google.generativeai.types.IncompleteIterationError	הועלה כשניגשים למשהו שדורש תגובת API מלאה, אבל לא בוצע שינוי מלא בתגובה בסטרימינג. קוראים לפונקציה resolve() באובייקט התשובה כדי לצרוך את האיטרטור.
StopCandidateException	google.generativeai.types.StopCandidateException	ה-API הגיב עם finish_reason יוצא מן הכלל. כדי לקבל עצה לגבי המשך התהליך, מומלץ לבדוק את הסיבה לכך.
PermissionDenied	google.api_core.exceptions.PermissionDenied	אין לך הרשאה למשאב המבוקש (למשל, מודל).
ResourceExhausted	google.api_core.exceptions.ResourceExhausted	ניצלת את כל המכסה. אפשר להמתין זמן מה ולנסות שוב. כדאי להגדיר ניסיונות חוזרים אוטומטיים כדי לטפל בשגיאות האלה.
AlreadyExists	google.api_core.exceptions.AlreadyExists	כבר קיים מודל מכוונן עם אותו מזהה. יש לציין מזהה דגם ייחודי בעת כוונון של מודל חדש.
InvalidArgument	google.api_core.exceptions.InvalidArgument	ארגומנט לא חוקי. אחת הדוגמאות: הקובץ גדול מדי וחורג ממגבלת הגודל של המטען הייעודי (payload). מפתח אחר מספק מפתח API לא חוקי.
DefaultCredentialsError	google.auth.exceptions.DefaultCredentialsError	האימות נכשל. צריך לבדוק שוב את מפתח ה-API ולנסות שוב.
RetryError	google.api_core.exceptions.RetryError	מצב כזה עשוי לקרות כשמשתמשים בשרת proxy שלא תומך ב-gRPC. אפשר לנסות להשתמש בתעבורה של REST עם genai.configure(..., transport="rest").

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

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

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

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

כדאי לבדוק אם נמצא הדגם הנכון

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

בעיות בטיחות

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

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

בעיה בהפנייה

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

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

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

אם יש לכם מאות דוגמאות לצמדי קלט/פלט טובים, תוכלו כדאי לשקול כוונון של המודלים.

הסבר על המגבלות של האסימונים

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

בעיות מוכרות

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

דיווח על באג

מצטרפים לדיון בפורום למפתחים של Google AI יש לכם שאלות?