מעקב ופתרון בעיות

בדף הזה מוסבר איך לקבל מידע על שגיאות שהתרחשו בייבוא קטלוגים ואירועים של משתמשים, ובפעולות אחרות של API ב-AI Commerce Search.

לקבלת עזרה בהגדרת התראות, אפשר לעיין במאמר הגדרת התראות ב-Cloud Monitoring.

מבוא

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

הצגת שגיאות מצטברות בשילוב

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

בדף הזה מוצגות כל השגיאות שקשורות ל-AI Commerce Search API. אתם יכולים לראות שגיאות שקשורות לקטלוג המוצרים, לאירועי משתמשים, לתחזיות של המלצות, לתוצאות חיפוש ולמודלים. המערכת גם רושמת שגיאות מייבוא, כמו שורה עם פורמט שגוי בקובץ Cloud Storage. המערכת מתעדת עד 100 שגיאות בכל קובץ ייבוא. אתם יכולים להגדיר את התקופה שבה השגיאות יוצגו ולסנן לפי סוג השגיאה.

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

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

במקרה של שגיאות JSON לא תקין, אפשר להרחיב את השדה status כדי לקבל מידע נוסף על הבעיה.

הצגת הסטטוס של פעולת שילוב ספציפית

אפשר לראות את הסטטוס של פעולת שילוב ספציפית בחלון סטטוס הפעילות:

  1. עוברים לדף Data במסוף AI Commerce Search ב-Gemini Enterprise for Customer Experience.

    מעבר לדף Data

  2. לוחצים על סטטוס הפעילות.

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

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

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

צפייה ביומנים ב-Cloud Logging

כדי לפתוח את קובצי היומן ישירות ב-Cloud Logging, משתמשים בהליך הבא. כדי לצפות ביומנים, צריך להיות לכם התפקיד 'צפייה ביומנים' (roles/logging.viewer).

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

  2. בוחרים את הפרויקט של AI Commerce Search מתוך רשימת הפרויקטים.

  3. לוחצים על התפריט הנפתח Resource (משאב) ובוחרים באפשרות Consumed API (API בשימוש) > Cloud Retail (קמעונאות בענן).

מידע נוסף על Logs Explorer זמין במאמר הצגת יומנים באמצעות Logs Explorer.

לדוגמה, הקישור הזה פותח יומנים של כל השגיאות ב-AI Commerce Search בשעה האחרונה:

פתיחת יומנים של AI Commerce Search

כדי להגדיר אילו יומנים של API ייכתבו, קראו את המאמר הגדרת רישום ביומן.

הגדרת רישום ביומן

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

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

כדי לעדכן את הגדרות הרישום ביומן, צריך את תפקיד העורך של AI Commerce Search.

אפשר להשתמש במסוף או ב-LoggingConfig API כדי להגדיר את Logging.

המסוף

כדי לעדכן את הגדרות הרישום ביומן במסוף, פועלים לפי השלבים הבאים:

  1. עוברים לדף Monitoring במסוף AI Commerce Search ב-Gemini Enterprise for Customer Experience.

    כניסה לדף Monitoring

  2. לוחצים על הגדרת רישום ביומן.

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

  4. כדי להגדיר הגדרות ברמת השירות, בוחרים שירות לעדכון ובוחרים את רמת הרישום שלו. ההגדרה הזו מבטלת את הגדרות הרישום הגלובליות.

curl

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

  1. כדי לראות את הגדרות הרישום הנוכחיות, משתמשים בפקודה loggingConfig.Get.

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig"
    • ‫PROJECT_ID: מזהה הפרויקט.

  2. כדי לעדכן את הגדרות הרישום ביומן, משתמשים בשיטה loggingConfig.Patch. מידע נוסף מופיע בLoggingConfig הפניית API.

    בדוגמה הזו נעשה שימוש ב-loggingConfig.Patch כדי להגדיר את ההגדרה הגלובלית של הרישום ביומן ל-LOG_WARNINGS_AND_ABOVE. היא גם מגדירה שתי הגדרות ברמת השירות: CatalogService מוגדר ל-LOG_WARNINGS_AND_ABOVE ו-ControlService מוגדר ל-LOG_ALL.

    curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig" \
  --data '{
    "name": "projects/PROJECT_ID/loggingConfig",
    "default_log_generation_rule": {"logging_level": "LOG_ERRORS_AND_ABOVE"},
    "service_log_generation_rules": [
      {
        "service_name": "CatalogService",
        "log_generation_rule": {
          "logging_level": "LOG_WARNINGS_AND_ABOVE"
          }
      },
      {
        "service_name": "ControlService",
        "log_generation_rule": {
            "logging_level": "LOG_ALL", "info_log_sample_rate": "0.1"
            }
        }
      ]
    }'

רמות רישום ביומן

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

אם לא מוגדרת שיטת תיעוד ברמת השירות עבור שיטת API, נעשה שימוש בהגדרה הגלובלית של רמת התיעוד.

הגדרת ברירת המחדל של רמת הרישום ביומן היא LOG_WARNINGS_AND_ABOVE.

הערכים הבאים קבילים בשדה logging_level:

  • LOGGING_DISABLED: לא נכתב יומן.
  • ‫LOG_ERRORS_AND_ABOVE: רישום שגיאות בלבד.
  • ‫LOG_WARNINGS_AND_ABOVE: יומן שכולל רק שגיאות ואזהרות.
  • ‫LOG_ALL: מתעד הכול, כולל יומנים מוצלחים כמו יומני INFO.

תדירות הדגימה של יומנים מוצלחים

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

כדי לציין קצב דגימה, מגדירים את info_log_sample_rate לערך float תקין שגדול מ-0 וקטן מ-1 או שווה לו. תדירות הדגימה קובעת את הסבירות לכך שיומן INFO ייכתב ב-Logging. ערך ברירת המחדל הוא 1 (כל היומנים של INFO נכתבים).

הגדרות ברמת השירות

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

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

הערכים הבאים קבילים בשדה service_name:

  • CompletionService
  • ControlService
  • MerchantCenterStreaming
  • ModelService
  • PredictionService
  • ProductService
  • ServingConfigService
  • UserEventService

סוגי שגיאות

בקטע הזה מוגדרים סוגי השגיאות שיכולים להופיע ביומני הרישום:

  • ‫MISSING_FIELD: לא מוגדר ערך בשדה חובה. לדוגמה, חסר שם לפריט בקטלוג.
  • ‫INVALID_TIMESTAMP: חותמת הזמן לא תקינה, למשל אם היא רחוקה מדי בעתיד או שהפורמט שלה שגוי.
  • ‫FIELD_VALUE_TOO_SMALL: הערך בשדה נמוך מהערך המינימלי הנדרש. לדוגמה, מחיר שלילי.
  • ‫INCORRECT_JSON_FORMAT: ה-JSON בבקשה לא מעוצב בצורה נכונה, למשל חסרה סוגר מסולסל {.
  • ‫INVALID_LANGUAGE_CODE: הפורמט של קוד השפה שגוי.
  • ‫FIELD_VALUE_EXCEEDED: הערך בשדה גבוה מהמקסימום המותר.
  • ‫INVALID_RESOURCE_ID: מזהה המשאב לא חוקי. לדוגמה, catalog_id לא קיים בשם המשאב.
  • ‫FIELD_SIZE_EXCEEDED: מספר הערכים בשדה חורג מהמגבלה המקסימלית.
  • ‫UNEXPECTED_FIELD: שדה שאמור להיות ריק מכיל ערך. לדוגמה, טרנזקציה לאירוע צפייה בדף פרטים.
  • ‫INVALID_FORMAT: השדה לא בפורמט הנכון, למשל מחרוזת לא תקינה
  • ‫RESOURCE_ALREADY_EXISTS: ניסית ליצור משאב שכבר קיים, כמו פריט קטלוג שנוצר בעבר.
  • ‫INVALID_API_KEY: מפתח ה-API לא תואם לפרויקט שצוין בבקשה.
  • ‫INSUFFICIENT_PERMISSIONS: אין לך הרשאה להפעיל את הבקשה. בדרך כלל השגיאה הזו קשורה לחוסר בהרשאת IAM הנדרשת.
  • ‫UNJOINED_WITH_CATALOG: הבקשה כוללת מזהה פריט בקטלוג שלא קיים בקטלוג. מוודאים שהקטלוג מעודכן.
  • ‫BATCH_ERROR: הבקשה מכילה כמה שגיאות. לדוגמה, ייבוא מוטבע עם 10 פריטים שנכשלים באימות מסיבות שונות.
  • ‫INACTIVE_RECOMMENDATION_MODEL: שלחתם שאילתה למודל שלא פעיל להצגת תשובות.
  • ‫ABUSIVE_ENTITY: מזהה המבקר או מזהה המשתמש שמשויך לבקשה שלח מספר חריג של אירועים בפרק זמן קצר.

  • ‫FILTER_TOO_STRICT: המסנן של בקשת החיזוי חסם את כל תוצאות החיזוי. פריטים פופולריים גנריים (לא מותאמים אישית) מוחזרים, אלא אם הפונקציה strictFiltering הוגדרה כ-false, ובמקרה כזה לא מוחזרים פריטים. חלק מהסיבות הנפוצות לבעיה הזו:

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

הצגת מדדים של טעינת נתונים

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

  1. בדף מעקב אפשר לראות מדדי שגיאות לגבי הקטלוג והטמעת נתוני אירועים של משתמשים.

    כניסה לדף Monitoring

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

    מעבר לדף Data

  3. כדי ליצור התראות שיעדכנו אתכם אם משהו לא בסדר בהעלאות הנתונים, פועלים לפי ההוראות במאמר הגדרת התראות ב-Cloud Monitoring.

סיכום נתוני הקטלוג

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

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

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

סטטיסטיקות של הקלטת אירועים של משתמשים

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

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

מדדים של איכות הנתונים

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

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

רשימה של כל מדדי איכות הנתונים בקטלוג זמינה במאמר בנושא מדדי איכות הנתונים בקטלוג.

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

אירועים ללא התאמה

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

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

שגיאות API

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

מעקב אחר פעילות של שיטת API

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

כדי לראות פרטים נוספים על כל תרשים:

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

המאמרים הבאים