פתרון בעיות במאגרי נתונים של Gemini Enterprise

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

כדי לקבל תמונה מלאה של שגיאה, חשוב להבין איך כלי הניטור של Google Cloudפועלים יחד:

• ‫Cloud Monitoring: מזהה מתי יש בעיה. אפשר להשתמש בו כדי לראות מגמות ברמה גבוהה, שיעורי שגיאות ולהגדיר התראות למאגרי הנתונים.
• ‫Cloud Trace: מאפשר לגלות איפה הבעיה מתרחשת. אפשר להשתמש בו כדי לראות את מחזור החיים של בקשה, לנתח את טווחי הזמן ולזהות בדיוק איזה שלב גרם לזמן טעינה ארוך או לכישלון.
• ‫Cloud Logging: הסבר למה הבעיה מתרחשת. אפשר להשתמש בו כדי לקרוא את הודעות השגיאה המדויקות ואת נתוני ה-payload שמשויכים לבקשה שנכשלה.
• יומני ביקורת ב-Cloud: מזהים מי או איזו מדיניות חסמה את הפעולה. אפשר להשתמש בו כדי לעקוב אחרי תאימות לאבטחה, שינויים בהרשאות ופעולות ניהול שעשויות לגרום לסירוב גישה.

ניפוי באגים בתהליך העבודה

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

1. בדיקת מגמות של שיעורי שגיאות
2. איתור הבקשה הספציפית שנכשלה
3. צפייה במטען הייעודי (payload) של השגיאה
4. הצלבת נתונים ביומני ביקורת

בדיקת מגמות של שיעור השגיאות

1. נכנסים לדף Metrics Explorer במסוף Google Cloud .

   לדף Metrics Explorer

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

חיפוש הבקשה הספציפית שנכשלה

1. נכנסים לדף Trace explorer במסוף Google Cloud :

   כניסה אל Trace explorer

   אפשר גם להשתמש בסרגל החיפוש כדי למצוא את הדף הזה.

2. בודקים את תרשים הפיזור כדי לראות אם יש עקבות עם סמל שגיאה (סימן קריאה אדום) או חביון גבוה באופן חריג.
3. לוחצים על מעקב כדי לראות את תרשים גאנט שלו.
4. בודקים את יחידה לוגית למעקב invoke_connector כדי לראות איפה התהליך נתקע או נכשל.
5. בנוסף, תוכלו למצוא את אסימון העזרה הייחודי שמשויך לבקשה ספציפית. אם אתם צריכים להעביר בעיה מורכבת לטיפול ברמה גבוהה יותר ב Google Cloud תמיכה, תוכלו לשתף את אסימון העזרה הזה כדי לזרז את הבדיקה.

הצגת מטען הייעודי (payload) של השגיאה

1. לוחצים על הטווח שנכשל בכלי לבדיקת נתונים.
2. בחלונית הפרטים, לוחצים על הצגת יומנים.
3. הפעולה הזו מעבירה אתכם אוטומטית אל Cloud Logging, עם סינון לפי הבקשה הספציפית הזו. כאן אפשר לקרוא את מטען הנתונים של היומן כדי לזהות את חתימת השגיאה המדויקת (למשל RESOURCE_EXHAUSTED או PERMISSION_DENIED).

הצלבת נתונים של יומני ביקורת שימוש

אם מטען הייעודי (payload) של היומן מציין בעיה ב-IAM, היקף חסר או דחיית הרשאה, צריך להצליב נתונים עם יומני הביקורת של Cloud:

1. נכנסים לדף Logs Explorer במסוף Google Cloud .

   כניסה לדף Logs Explorer

2. בודקים את היסטוריית הניהול. בודקים אם האדמין שינה לאחרונה מסנן פעולות או ביטל הרשאה נדרשת.

דוגמה: מעקב אחרי בקשה למאגר נתונים שנכשלה

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

1. בדיקת מגמות שגיאות: לפני חיפוש שגיאות בודדות, חשוב לדעת עד כמה הבעיה נפוצה. פתחו את Metrics Explorer ב-Cloud Monitoring וסננו את מדדי בקשות מאגר הנתונים לפי tool_id: get_issue. ייתכן שתראה עלייה חדה ופתאומית בשגיאות של RESOURCE_EXHAUSTED. זה מאשר שמדובר בבעיה מערכתית, ולא רק טעות הקלדה חד פעמית של המשתמש.
2. איתור הבקשה שנכשלה: פתח את Trace Explorer והגדר את מסנן הזמן לשעה האחרונה. בתרשים הפיזור, תבחינו באשכול של עקבות עם סמל שגיאה אדום המציין כשלים. לחץ על אחת מהעקבות האחרונות כדי לחקור.
3. בחינת תרשים גאנט: תרשים גאנט מציג באופן ויזואלי את מסלול הבקשה. אתה רואה טווח אב מוצלח עבור ניתוב הסוכן הראשוני, אך מתחתיו מקוננת טווח invoke_connector כושל המכוון ספציפית למאגר הנתונים של Jira Cloud.
4. מעבר ליומנים: לחץ על טווח ה-invoke_connector הכושל. בחלונית פרטי המעקב, לחץ על הצג יומנים.

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

   
   "message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"
   
   

   בהודעת השגיאה של המטען, ניתן לראות את הכלי הספציפי (get_issue) שנכשל ואת ההודעה המפורשת המציינת כי למשתמש שמבצע את הבקשה אין גישה למשאב הספציפי במערכת היעד.

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

שגיאות נפוצות

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

שגיאות אימות וגישה

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

טוקן OAuth לא חוקי או שתוקפו פג

• חתימת שגיאה: HTTP request failed with status code 401 / 401 Unauthorized
• הגורם הבסיסי: פג התוקף של טוקן ה-OAuth או שהוא לא תקין.
• פתרון: צריך להעניק מחדש הרשאה למאגר הנתונים בהגדרות של Gemini Enterprise כדי ליצור טוקן חדש.

הכלי נחסם על ידי מסנן פעולות

• חתימת שגיאה: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
• הגורם הבסיסי: האדמין חסם את הכלי באמצעות מסנן פעולות.
• פתרון: האדמין צריך לעדכן את רשימת ההיתרים של הפעולה או הכלי.

חסרים היקפי הרשאות OAuth

• חתימות שגיאה: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted או Cause: Insufficient Permission
• סיבת השורש: ברישום האפליקציה בפלטפורמת הצד השלישי חסרים היקפי ההרשאות הנדרשים.
• פתרון: אדמין צריך להעניק את ההיקפים המדויקים שמופיעים ביומן ולאשר מחדש את האפליקציה.

חסרות הרשאות IAM בפרויקט

• חתימת שגיאה: Access Denied: User does not have [permission] / mcp.tools.call permission
• הגורם הבסיסי: למבצע הקריאה או לחשבון השירות חסרות הרשאות IAM הנדרשות בפרויקט היעד Google Cloud .
• פתרון: צריך לתת למבצע הקריאה החוזרת את הרשאת ה-IAM שצוינה.

שגיאות שקשורות לביצועים ולהגבלת קצב הבקשות

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

הגבלת קצב בקשות (Throttling) של API של צד שלישי עם קוד השגיאה 429

• חתימת שגיאה: Cause: Request has been rate limited
• סיבת השורש: אתם שולחים בקשות מהר יותר ממה שממשק ה-API של הצד השלישי מאפשר.
• פתרון: צריך להקטין את קצב הבקשות, להטמיע אסטרטגיות של נסיגה או לבקש מספק הצד השלישי להגדיל את המכסה.

שגיאות שקשורות לחשיפה ולמשאבים

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

הגבלת ניראות של צד שלישי

• חתימת שגיאה: 422 ... you do not have permission to view [Resource/Users]
• סיבה בסיסית: הגבלת נראות או מדיניות ארגונית בפלטפורמת צד שלישי מונעים אחזור נתונים.
• פתרון: התאם את החברות שלך בארגון צד שלישי, או צמצם את מגבלת היקף השאילתה שלך.

גישה חסרה למשאבי משתמש קצה

• חתימת שגיאה: permission denied: [user] does not have access to [Resource]
• סיבה בסיסית: למשתמש הקצה שמבצע את הבקשה אין גישה לרכיב או למשאב הספציפי במערכת היעד.
• פתרון: הענקת גישה למשתמש למשאב ישירות בתוך מערכת היעד.

שגיאות בצד המערכת ובצד השרת

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

נקודת קצה של צד שלישי איטית או עמוסה מדי

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

תצורה שגויה של קישור אישורי שרת MCP

• חתימת שגיאה: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
• סיבה בסיסית: ישנה בעיית מדיניות בצד השרת שבה קישור פרטי הגישה של שרת ה-MCP מוגדר באופן שגוי. זה לא ניתן לפעולה מצד הלקוח.
• הַחְלָטָה: מַגָע Google Cloud תְמִיכָה.

פנייה לתמיכה

אם נתקלת בשגיאה חוזרת של context deadline exceeded או CredsPermissionException, ייתכן שתצטרך להגיש פנייה לתמיכה של Google Cloud .

כדי לזרז את הפתרון, אנא אספו את הפריטים הבאים מכלי התצפית שלכם לפני פתיחת כרטיס:

• מתוך Cloud Logging: עותק יומן ה-JSON המלא של השגיאה.
• מ-Cloud Trace: אסימון הסיוע ופרטי טווח ספציפיים (כולל מזהה מעקב) המשויכים לבקשה שנכשלה.
• מיומני ביקורת שימוש: כל חותמות זמן רלוונטיות של שינויי IAM או שינויי מדיניות שייתכן והפעילו את הבעיה.