ייבוא נתונים של השלמה אוטומטית לחיפוש

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

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

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

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

לפני שמתחילים

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

כדי לבצע את הייבוא, צריך להיות לכם תפקיד IAM של עורך Retail.

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

כשמייבאים נתונים של השלמה אוטומטית, חשוב להקפיד על השיטות המומלצות הבאות:

• כדאי לעיין בסכימת BigQuery שמפורטת בקטעים הבאים ובמסמכי התיעוד של ה-API.

• אל תשתמשו בערכים זמניים לשמירת מקום (placeholder).

• חשוב למלא כמה שיותר שדות.

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

• אסור לייבא נתונים מפרויקט אחר.

ייבוא נתונים של השלמה אוטומטית

ייבוא נתונים של השלמה אוטומטית מ-BigQuery

AI Commerce Search תומכת בייבוא נתונים מ-BigQuery לרשימת המילים האסורות, לרשימת המילים שאסור להסיר ולרשימת מונחי ההצעה. פרטים נוספים זמינים במאמר בנושא השלמה אוטומטית.

כדי לייבא נתונים להשלמה אוטומטית בפורמט הנכון מ-BigQuery, צריך להשתמש בסכימת ההשלמה האוטומטית של AI Commerce Search כדי ליצור טבלה ב-BigQuery בפורמט הנכון ולטעון את הטבלה עם נתוני ההשלמה האוטומטית. לאחר מכן, מעלים את הנתונים ל-AI Commerce Search.

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

מיקום מערך הנתונים ב-BigQuery

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

איכלוס נתונים ב-BigQuery

כדי להעלות את נתוני ההשלמה האוטומטית ל-BigQuery, צריך להשתמש בסכימת ההשלמה האוטומטית של AI Commerce Search.

‫BigQuery יכול להשתמש בסכימה כדי לאמת אם נתונים בפורמט JSON מכילים שמות וסוגים נכונים של שדות (כמו STRING,‏ INTEGER ו-RECORD), אבל הוא לא יכול לבצע אימותים כמו קביעה של:

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

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

הגדרת גישה למערך הנתונים ב-BigQuery

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

1. פותחים את הדף IAM במסוף Google Cloud .

   כניסה לדף IAM

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

3. בדף IAM & Admin, לוחצים על  Grant Access.

4. בקטע New principals (ישויות חדשות), מזינים את [e-mail] ובוחרים את התפקיד BigQuery > BigQuery Data Viewer (BigQuery > מציג נתונים ב-BigQuery).

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

5. לוחצים על Save.

הפעלת ייבוא נתונים ל-AI Commerce Search

המסוף

1. כניסה לדף Controls

2. עוברים לכרטיסייה אמצעי בקרה להשלמה אוטומטית.

3. בקטע Term Lists (רשימות מונחים), מוצאים את סוג הרשימה שרוצים לייבא (Deny list (רשימת מונחים לאישור), Do Not Remove list (רשימת מונחים שלא להסרה) או Suggested terms list (רשימת מונחים מוצעים)) ולוחצים על Import (ייבוא) או על Replace (החלפה).

   נפתחת החלונית ייבוא.

4. מזינים את הנתיב של מיקום הנתונים ב-BigQuery או בוחרים באפשרות עיון כדי לבחור את המיקום.

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

5. בחלונית ייבוא, לוחצים על ייבוא.

   הייבוא מתחיל. אתם יכולים לצאת מהדף בלי להפריע לייבוא.

cURL

1. יוצרים קובץ נתונים עם פרמטרי הקלט לייבוא. ערכי פרמטר הקלט משתנים בהתאם למקור הייבוא: Cloud Storage או BigQuery.

   משתמשים באובייקט BigQuerySource כדי להפנות למערך הנתונים ב-BigQuery.

   • ‫dataset-id: המזהה של מערך הנתונים ב-BigQuery.
   • ‫table-id: המזהה של הטבלה ב-BigQuery שמכילה את הנתונים.
   • ‫data-schema: בשביל המאפיין dataSchema, משתמשים בערך suggestions (ברירת מחדל), allowlist או denylist. משתמשים בסכימת ההשלמה האוטומטית של חיפוש מסחר אלקטרוני מבוסס-AI.

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }

2. כדי לייבא את פרטי ההשלמה האוטומטית אל AI Commerce Search, צריך לשלוח POST בקשה אל CompletionData:import בשיטת REST ולציין את שם קובץ הנתונים (שמוצג כ-input.json בדוגמה שלמטה).

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"

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

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }

   השדה name הוא המזהה של אובייקט הפעולה. כדי לבקש את הסטטוס של האובייקט הזה, מחליפים את השדה name בערך שמוחזר על ידי שיטת הייבוא. כשהייבוא מסתיים, השדה done מחזיר את הערך true:

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"

   כשהפעולה מסתיימת, הערך של done באובייקט שמוחזר הוא true, והוא כולל אובייקט Status שדומה לדוגמה הבאה:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }

פורמט נתונים של השלמה אוטומטית

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

שדות החובה המינימליים להצעות:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

או:

{
  "suggestion": "ABC",
  "frequency": "100"
}

משך הזמן של ייבוא הנתונים להשלמה אוטומטית

בדרך כלל, ייבוא אחד מ-BigQuery נמשך כמה דקות עד שעה.

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

שמירה על עדכניות של מערך הנתונים להשלמה אוטומטית

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

חבילת עדכונים

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

מעקב אחר תקינות הייבוא

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

סכימת השלמה אוטומטית של AI Commerce Search

כשמייבאים מערך נתונים של השלמה אוטומטית מ-BigQuery, צריך להשתמש בסכימה שלמטה של AI Commerce Search כדי ליצור טבלאות ב-BigQuery בפורמט הנכון ולטעון אותן עם נתוני ההשלמה האוטומטית.

סכימה להצעות

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

‫JSON של סכימת הצעות להשלמה אוטומטית ב-AI Commerce Search

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

סכימה של רשימת הישויות שנחסמו

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

‫JSON של סכימת רשימת ההחרגות של השלמה אוטומטית ב-AI Commerce Search

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

סכמה לרשימת היתרים

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

‫JSON של סכימת רשימת ההיתרים להשלמה אוטומטית של AI Commerce Search

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]