מדריך למפתחים של סוכנים בממשק שיחה

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

המסנן conversationalFilteringMode ב-Conversational API מבהיר את ההבדלים בין סוכן בממשק שיחה לבין סינון מוצרים בממשק שיחה.

הגדרת ה-API ורצף הקריאות

‫Conversational API תומך בסוכן בממשק שיחה:

• ‫gRPC: conversationalSearchService
• ‫REST: conversationalSearch

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

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

כדי להחזיר תוצאות חיפוש, צריך להפעיל את Conversational API במקביל ל-AI Commerce Search API מדור קודם.

שליחת שאילתה ממשתמש הקצה

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

שליחת בקשה ל-AI Commerce Search

יש שתי נקודות קצה שונות ל-API:

1. כדי לאחזר את ממשק הצ'אט עם AI, צריך להשתמש ב-Conversational API.
2. כדי לאחזר תוצאות חיפוש, צריך להשתמש ב-Search API הליבה.

נקודת קצה 1: בקשת API ל-Conversational

• כדי ליצור בקשה לסוכן שיכול לנהל שיחה, צריך להגדיר את הקלט של המשתמש כשאילתה.
• הבקשה צריכה להישלח כבקשת HTTP POST לנקודת הקצה projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

שיטת HTTP ונקודת קצה

  POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
  

בקשת API בממשק שיחה:

שאילתה ראשונית

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}

• ‫placement: שם המשאב של מיקום המודעה (למשל projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). זהו פרמטר של נתיב וחובה.
• ‫query: שאילתת החיפוש הגולמית מהמשתמש. זהו שדה חובה.
• ‫branch: שם המשאב של הענף, למשל projects/P/locations/L/catalogs/C/branches/B. אם לא מוגדר, נעשה שימוש ב-default_branch. זהו שדה חובה.
• ‫visitorId: מזהה ייחודי למעקב אחרי מבקרים. זהו שדה חובה.
• ‫conversationId: מזהה ייחודי למעקב אחרי סשנים של שיחות. בשביל הבקשה הראשונה בשיחה חדשה, השדה הזה צריך להיות ריק. בבקשות הבאות באותה שיחה, צריך להגדיר את הערך של conversation_id שמתקבל בבקשה הקודמת ConversationalSearchResponse.
• ‫searchParams: (אופציונלי) פרמטרים סטנדרטיים של חיפוש ליבה, כמו filter,‏ canonicalFilter,‏ sortBy ו-boostSpec. חשוב מאוד שהפרמטרים האלה ישקפו את ההגדרה שבה נעשה שימוש בקריאות ל-Core Search API, כדי להבטיח עקביות בין התשובות של מודל שפה גדול לבין תוצאות החיפוש של המוצר שמוצגות.
• ‫userInfo: (אופציונלי) פרטי משתמש להתאמה אישית משופרת. יכול לכלול userId, user_agent, direct_user_request (בוליאני).
• ‫conversationalFilteringSpec: (אופציונלי) מציין את מצב הסינון של השיחה. אם לא מגדירים את ההגדרה הזו, ברירת המחדל היא DISABLED.

  ‫mode: אפשר לשלב את Conversational API באמצעות אחד משלושת המצבים האלה כדי לשלוט בסינון מוצרים בממשק שיחה:

• ‫DISABLED: במצב הזה, הלקוח מטמיע רק חיפוש באמצעות ממשק צ'אט עם AI. זהו המצב המועדף במדריך ההטמעה הזה בנושא חיפוש סוכנים שיכולים לנהל שיחה.

דוגמה לבקשת API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }
      

דוגמה לתגובה מה-API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

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

במדריך הנוסף מוסבר איך לשלב בין שני המוצרים לשיחות.

דוגמה לבקשת API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }
      

דוגמה לתגובה מה-API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
      

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

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

נקודת קצה 2: בקשת Core Search API

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

אפשרות 1: הצגת תוצאות החיפוש תמיד

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

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

אם עיצוב חוויית המשתמש שלכם דינמי יותר ואתם רוצים להציג תוצאות חיפוש רק בהתאם לתגובה של Conversational API, למשל רק עבור שאילתות SIMPLE_PRODUCT_SEARCH או בכל פעם שמוצעות הצעות refined_search, צריך להמתין לתגובה של Conversational API לפני ששולחים שאילתות ל-Google Product Search API הראשי. אם יש תגובה, משתמשים בשאילתת refined_search שסופקה כדי לאחזר תוצאות של מוצרים.

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

שיטת HTTP ונקודת קצה

    POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
    

בקשת API של חיפוש מוצרים מרכזי:

שאילתה ראשונית

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
    

• ‫placement (חובה): שם המשאב של הגדרת ההצגה של AI Commerce Search או של מיקום מודעה מדור קודם. דוגמה: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• ‫query: שדה חובה. שאילתת החיפוש. זה יכול להיות הקלט הגולמי של המשתמש, כמו עזרה בתכנון מסיבה, או קלט מותאם יותר refinedSearch.query (כמו ציוד לתכנון מסיבה, קישוטים) שהתקבל מהתגובה של Conversational Commerce API.
• ‫visitorId: שדה חובה. מזהה ייחודי למעקב אחרי מבקרים. הערך הזה צריך להיות זהה לערך של visitorId שנשלח אל Conversational Commerce API עבור אותו משתמש קצה.
• ‫branch (חובה): שם המשאב של הסניף, למשל projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• ‫pageSize (אופציונלי): המספר המקסימלי של מוצרים שצריך להחזיר.
• filter (אופציונלי): משמש לסינון תוצאות החיפוש. כאן תוכלו להחיל מסננים שמשקפים את מה שאתם שולחים ב-`searchParams` ל-Conversational Commerce API, כדי לשמור על עקביות.
• orderBy (אופציונלי): מציין את הסדר שבו המוצרים מוחזרים (למשל לפי רלוונטיות או לפי מחיר).
• userInfo (אופציונלי): פרטי משתמש להתאמה אישית, צריכים להיות זהים לפרטים שמועברים בקריאה ל-Conversational Commerce API.
• ‫searchMode (אופציונלי): מגדיר את התנהגות החיפוש. ‫PRODUCT_SEARCH נפוץ בשאילתות כלליות לגבי מוצרים.

הסבר על התשובה

בדוגמת קוד זו מוצגת תשובה מ-Conversational Commerce API.

התגובה מה-API‏ (ConversationalSearchResponse) כוללת את האפשרויות query_types, conversational_text_response (אם רלוונטי) ו-refined_search, ויכול להיות שהיא תכלול גם followup_question או conversational_filtering_result. ההרשאה conversation_id חיונית להמשך הסשן.

תשובה מ-AI Commerce Search

דוגמת הקוד הזו מדגימה תגובה של Conversational API:

מענה ראשוני

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }
    

מה הקמעונאים צריכים לעשות עם התשובה (כללי)

צריך לעבד את השדות האלה מהתגובה:

• ‫user_query_types: בשדה הזה מופיעה הסיווגים של כוונת המשתמש. למידע על פעולות מפורטות שמבוססות על הסוגים האלה, אפשר לעיין במאמר הסבר על סיווג כוונות המשתמש ופעולות הקמעונאים.
• ‫conversation_id: אפשר לאחסן את המזהה הייחודי הזה באחסון של סשן הדפדפן או באחסון דומה בצד הלקוח, כדי לשמור על הסשן של השיחה עם השרת. ההגדרה הזו חשובה כדי להבחין בין כמה שיחות שמתנהלות עם אותו קונה. המודל שומר את ההקשר של conversation_id מסוים. שליחת conversation_id חדש מתחילה סשן חדש. מומלץ להגדיר את משך הסשן, למשל 30 דקות של חוסר פעילות.
• ‫refined_search: רשימה של שאילתות חיפוש מוצעות ומדויקות יותר, שמשמשות לאחזור תוצאות החיפוש הרלוונטיות. ב-SIMPLE_PRODUCT_SEARCH, תמיד מדובר בשאילתה אחת. לגבי שאילתות אחרות שנועדו לקבל תשובות מ-LLM, התשובה היא אחת או יותר. אפשר להשתמש בשאילתות refined_search לקריאות ל-API הליבה של החיפוש (SearchService.Search) או להציג אותן למשתמש כהצעות.
• ‫conversational_text_response: הטקסט הזה יוצג למשתמש כתשובה העיקרית לשאילתה שלו שנוצרה על ידי AI.
• ‫followup_question: אופציונלי. האפשרות followup_question מוצגת.
• ‫state: השדה הזה מציין את מצב תהליך יצירת התשובות ("STREAMING" או "SUCCEEDED"). אפשר להשתמש בו כדי לקבל משוב על חוויית השימוש, למשל להציג אינדיקטור טעינה עד שמקבלים את הערך "SUCCEEDED". פרטים נוספים על כך מופיעים בקטע הבא.

הסבר על ה-API של הסטרימינג

ה-Conversational Commerce API פועל כשירות סטרימינג. כלומר, המשתמש מקבל חלקים מהתשובה בכמה נתחים ולא במטען ייעודי (payload) אחד מלא.

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

• מכיל שאילתות userQueryTypes ו-refinedSearch.
• state: "STREAMING"
• חלקים עוקבים:

• כוללות חלקים מconversationalTextResponse בזמן שהן נוצרות.
• החלק האחרון:

• מכיל את conversationalTextResponse המלא.
• state: "SUCCEEDED"
• תובנה פרקטית: אתם יכולים לקבוע את כוונת המשתמש באופן מיידי מהחלק הראשון ולהתחיל לאחזר תוצאות של מוצרים במקביל בזמן שטקסט התשובה של ה-AI עדיין נטען.

החלק הראשון של התשובה כולל את השאילתות query_types ו-refined_search, וה-state שלו מצוין כ-STREAMING. הזיהוי המוקדם של הכוונה והזמינות המיידית של שיפורים בחיפוש מאפשרים למודל לקבל החלטות מהירות לגבי אופן הטיפול בשאילתה של המשתמש וניהול חוויית המשתמש בנוגע לזמן האחזור של תשובות מ-LLM:

• לסוגי שאילתות שלא מצפים לתשובה בצורת טקסט שיחה, כמו SIMPLE_PRODUCT_SEARCH, ‏ RETAIL_IRRELEVANT, ‏ BLOCKLISTED, ‏ QUERY_TYPE_UNSPECIFIED, ‏ ORDER_SUPPORT, ‏ DEALS_AND_COUPONS, ‏ STORE_RELEVANT:
• מכיוון שהתווים query_types נמצאים בחלק הראשון, המערכת יודעת מיד שלא תתקבל תשובה מ-LLM. אתם יכולים להמשיך עם הטיפול המוגדר מראש לסוגים האלה, למשל להציג הודעה סטטית או להפנות לתמיכה, בלי לחכות לפלט נוסף של השיחה.
• במקרה של SIMPLE_PRODUCT_SEARCH, המערכת יכולה לשלוח מיד קריאה ישירה ל-Search API הראשי באמצעות שאילתת refined_search שהתקבלה בחלק הראשון. כך אפשר להבטיח שתוצאות החיפוש יוצגו עם עיכוב מינימלי, בהתאם להסכמי רמת השירות (SLA) של חוויית החיפוש הרגילה.
• לגבי סוגי שאילתות שכן מצפים לתשובה טקסטואלית בממשק שיחה, כמו INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
• שאילתות query_types ו-refined_search מתקבלות בחלק הראשוני. אתם יכולים להשתמש בשאילתות refined_search האלה כדי להתחיל לטעון תוצאות של מוצרים, ולהפעיל מיד קריאה מקבילה ל-API הראשי של חיפוש Google.
• אחרי כן, נשלחים נתונים של חלקים נוספים, שמכילים קטעים שונים של התשובה הטקסטואלית מהשיחה. במהלך הזמן הזה, הסמל state נשאר "STREAMING".
• לבסוף, החלק האחרון כולל את התשובה המלאה בצורת טקסט של שיחה, והשינוי שלה מ-state ל-"COMPLETED".
• הגישה הזו של סטרימינג מאפשרת חוויית משתמש חלקה, שבה תוצאות החיפוש מתחילות להיטען בזמן שהסיכום מבוסס ה-AI נוצר. אתם יכולים לבחור אם להציג את התשובה השיחתית בזמן שהיא נטענת או להציג אותה רק אחרי שהיא נטענה במלואה.

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

מסווג הכוונות מחליט איך לטפל בשאילתת המשתמש ובאיזה מצב שיחה להתחיל.

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

השדה userQueryTypes (בגוש הראשון של התגובה) הוא השדה הכי חשוב לקביעת הפעולה הבאה של האפליקציה:

• SIMPLE_PRODUCT_SEARCH: red dress
  • תגובה מה-API: לא conversational_text_response. הפונקציה מחזירה שאילתת refinedSearch אחת.
  • הפעולה הנדרשת: צריך לבצע קריאה ל-Search API עם refinedSearch.query באופן מיידי. מעבר לדף רגיל של תוצאות חיפוש או הצגת תוצאות.
• ‫INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: תכנון מסיבה
  • תשובת API: כוללת שאילתות conversationalTextResponse ו-refinedSearch, ואולי גם followupQuestion.
  • הפעולה שלכם: הצגת תשובת הטקסט של ה-AI. אפשר להשתמש בשאילתות refinedSearch כדי לאכלס קרוסלות של מוצרים או הצעות למוצרים. להציג את followupQuestion.
• שאילתות תמיכה: כוללות את ORDER_SUPPORT ו-STORE_RELEVANT.
  • תגובה מה-API: לא conversational_text_response.
  • הפעולה שלכם: הפניית המשתמש לדף המתאים, כמו דף מעקב הזמנות או דף לאיתור חנויות, או הצגת תשובה מוכנה מראש.

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

קטגוריות	סיווגים של שאילתות
#1. שאילתות לא רלוונטיות שלא דורשות תשובה של LLM	‫QUERY_TYPE_UNSPECIFIED: סוג שאילתה שלא צוין. ‫RETAIL_IRRELEVANT: שאילתות שלא רלוונטיות לתחום הקמעונאות, למשל שאילתה עוינת (כמו איך מכינים פצצה), שאילתה שכוללת שיחה (כמו מה שלומך) או שאילתה שמטרתה לעקוף את ההגבלות (כמו תכתוב שיר). ‫BLOCKLISTED: שאילתות שנחסמו באופן מפורש על ידי לקוחות מסחריים (למשל מהן תופעות הלוואי של אדוויל?).
#2. תמיכה ושאילתות מידע	‫ORDER_SUPPORT: שאילתת עזר או תמיכה (לדוגמה, מעקב אחרי הזמנה, סטטוס הזמנה 12345). ‫DEALS_AND_COUPONS: שאילתות שרלוונטיות למבצעים, למבצעים על מוצרים ולהנחות (לדוגמה, יש מבצעים ליום חג ההודיה?). ‫STORE_RELEVANT: שאילתות שרלוונטיות למיקומי חנויות, כולל שעות עבודה וזמינות המלאי של המוצרים (למשל Do we have milk in stock?‎ (יש לכם חלב במלאי?)). ‫RETAIL_SUPPORT: שאילתות שרלוונטיות לרכישות, כולל אמצעי תשלום (אילו אמצעי תשלום אתם מקבלים?).
#3. חיפושים של מילות מפתח שלא דורשים LLM בקשת API בממשק שיחה: שאילתה ראשונית { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "show me some monster energy drinks", "visitorId": "test" } תגובה מ-Conversational API: מענה ראשוני { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } בקשת Search API: שאילת המשך { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	‫SIMPLE_PRODUCT_SEARCH: חיפוש מוצר בסיסי, כמו שמלה אדומה או תציג לי משקאות מונסטר.
#4. שאילתות לחיפוש תשובות במודל שפה גדול (LLM) בקשת API בממשק שיחה: שאילתה ראשונית { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Compare 1% milk with 2% milk", "visitorId": "test" } תגובה מ-Conversational API: מענה ראשוני { "userQueryTypes": ["PRODUCT_COMPARISON"], "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.", "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba", "refinedSearch": [ { "query": "1% milk" }, { "query": "2% milk" } ] } בקשת Search API: שאילת המשך { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	‫PRODUCT_DETAILS: המשתמש מחפש פרטים ומפרטים של מוצרים, כמו תראה לי את המפרטים של [שם המוצר], מה תכולת החלבון בחלב 2%? ‫PRODUCT_COMPARISON: השוואת מוצרים, למשל השוואה בין [שם מוצר] לבין [שם מוצר], השוואה בין חלב 1% לבין חלב 2%. ‫BEST_PRODUCT: שאילתות עם הדפוס התואם ביותר, כמו What is the healthiest cookie?, איזה מותג חלב הוא הכי טוב?
#5. חידוד הכוונה בקשת API בממשק שיחה: שאילתה ראשונית { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Help me plan a party", "visitorId": "test" } תגובה מ-Conversational API: מענה ראשוני { "userQueryTypes": ["INTENT_REFINEMENT"], "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.", "followupQuestion": { "followupQuestion": "What kind of party are you planning?" }, "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", "refinedSearch": [ { "query": "Decorations" }, { "query": "Snacks" }, { "query": "Party Supplies" }, { "query": "Drinks" }, { "query": "Cake" } ], "state": "SUCCEEDED" }	‫INTENT_REFINEMENT: הסוג לא ברור, ויכול להיות שיידרש המשך שיחה או שיפור כדי להבהיר את הסוג, למשל עזרה בתכנון מסיבה. ברוב המקרים זו הכוונה הכי פופולרית בשיחות.

קטגוריה 1. שאילתות לא רלוונטיות שלא דורשות תשובה מ-LLM

• QUERY_TYPE_UNSPECIFIED:
• לא צוין conversational_text_response.
• הפעולה: צריך לטפל בבעיה כברירת מחדל או כטעות. יכול להיות שתבקשו מהמשתמש הבהרה או שתפנו אותו למקום שבו הוא יכול לקבל עזרה כללית.
• RETAIL_IRRELEVANT:
• לא צוין conversational_text_response.
• פעולה: הצגת הודעה מתאימה, כמו אין לי תשובה לשאלה הזו או אני עוזר קניות, איך אוכל לעזור לך?, בהתאם להגדרות העיצוב של האפליקציה.
• BLOCKLISTED:
• לא צוין conversational_text_response.
• פעולה: צריך לטפל בבקשה בהתאם למדיניות של רשימת החסימה, בדרך כלל על ידי הצגת הודעה כללית לא ניתן לבצע את הבקשה הזו.

קטגוריה 2. שאילתות לגבי תמיכה ומידע

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

• ORDER_SUPPORT:
• פעולת ברירת המחדל: לא מסופק conversational_text_response. ממשק האינטרנט שלכם צריך להציג הודעה סטנדרטית, קישורים רלוונטיים או להפנות את השאילתה ל-API ייעודי לתמיכה או לערוץ שירות לקוחות משלכם.
• DEALS_AND_COUPONS:
• פעולת ברירת המחדל: לא מסופק conversational_text_response. ממשק האינטרנט צריך להציג הודעה סטנדרטית, קישורים רלוונטיים או להפנות את השאילתה למערכת המבצעים או העסקאות שלכם.
• STORE_RELEVANT:
• פעולת ברירת המחדל: לא מסופק conversational_text_response. ממשק האינטרנט צריך להציג הודעה סטנדרטית, קישורים רלוונטיים או להפנות את השאילתה למאתר החנויות או למערכת המידע שלכם.
• RETAIL_SUPPORT:
• פעולת ברירת המחדל: לא מסופק conversational_text_response. ממשק האינטרנט צריך להציג הודעה סטנדרטית, קישורים רלוונטיים או להפנות את השאילתה למערכת השאלות הנפוצות והמידע שלכם.

קטגוריה 3. חיפושים לפי מילות מפתח שלא דורשים תשובות מ-LLM

• SIMPLE_PRODUCT_SEARCH:
• לא נוצרה תשובה טקסטואלית לשיחה.
• פעולה: תגובת ה-API תמיד מחזירה שאילתת refined_search אחת. השאילתה המדויקת הזו משמשת כהצעה למונח חיפוש. שולחים קריאה ישירה ל-API הליבה של חיפוש Google‏ (SearchService.Search) ומאחזרים תוצאות רלוונטיות של מוצרים באמצעות השאילתה המקורית או השאילתה refined_search. יכול להיות שההצעה refined_search.query לא תהיה ישירות מהקלט הנוכחי של משתמש הקצה, אלא תהיה נגזרת מההקשר של היסטוריית הצ'אט. לדוגמה, אם משתמש קצה צמצם בעבר את החיפוש שמלות למסיבה לשמלות אדומות, יכול להיות שהשאילתה המצומצמת תהפוך לשמלות אדומות למסיבה.
• לממשקי צ'אט (כמו צ'אטבוטים): מומלץ מאוד להשתמש ב-refined_search.query שמופיע ב-API. במהלך שיחה, שאילתות בשפה טבעית כמו "תמצא לי בבקשה בננות" עוברות אופטימיזציה אוטומטית על ידי ה-API למונח חיפוש מדויק של מוצר ("בננות"), וכך מובילות לתוצאות מוצר רלוונטיות יותר.
• במקרים של חוויות חיפוש בסיסיות (כמו דף תוצאות החיפוש): אפשר להשתמש ב-refined_search.query מ-API או בשאילתה המקורית שסיפק משתמש הקצה, כי סביר יותר שהשאילתה המקורית היא כבר מונח חיפוש מדויק של מוצר. בוחרים את האפשרות שהכי מתאימה לממשק האינטרנט ולשיטת הצגת תוצאות החיפוש.
• אפשרויות חוויית משתמש: לא צריך לסיים את השיחה כדי לשלוח שאילתות SIMPLE_PRODUCT_SEARCH. המשתמש יכול להמשיך את השיחה על ידי העברת conversation_id בבקשות הבאות.
• אפשרות א': סיום ממשק אינטרנט שיחה: קמעונאים רבים בוחרים להעביר את המשתמש לדף תוצאות חיפוש רגיל ברגע שמזוהה SIMPLE_PRODUCT_SEARCH, וכך למעשה חלון הצ'אט נסגר. בתרחיש הזה, אם משתמש הקצה יזין שאילתה חדשה בתיבת החיפוש הרגילה בלי conversation_id הקודם, המערכת תתייחס לזה כאל שיחה חדשה ונפרדת, ותנפיק conversation_id חדש.
• אפשרות ב': המשך השיחה בממשק האינטרנט: קמעונאים יכולים לבחור להשאיר את חלון הצ'אט פתוח. כך המשתמש יכול לחזור למצב שיחה. ההחלטה אם להטמיע את אפשרות א' או ב' תלויה לחלוטין בחוויית המשתמש המועדפת של הקמעונאי.

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

1. שחזור conversation_id. כשמבצעים קריאה ל-API‏ conversationalSearch, מוחזר ConversationalSearchResponse.conversation_id.
2. תיוג אירועים של משתמשים. במקרים שבהם התשובה השיחתית מובילה לשאילתת חיפוש, למשל אם המערכת שלכם מבצעת חיפוש באופן אוטומטי על סמך השאילתה המדויקת של SIMPLE_PRODUCT_SEARCH, חובה לתייג את אירוע המשתמש הבא של החיפוש (UserEvent) עם אותו conversation_id שהתקבל ב-ConversationalSearchResponse.

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

קטגוריה 4. שאילתות לחיפוש תשובות ב-LLM

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

• PRODUCT_DETAILS:
• פעולה: conversational_text_response מספק את פרטי המוצר המבוקשים. המידע הזה צריך להיות מוצג למשתמש בצורה ברורה במערכת.
• התגובה כוללת גם refined_search (שאילתת חיפוש מוצעת אחת או יותר, מסודרות ומדורגות) שצריך להשתמש בהן כדי לאחזר תוצאות חיפוש באמצעות ה-API המרכזי של חיפוש Google.
• PRODUCT_COMPARISON:
• פעולה: conversational_text_response מספק השוואה בין המוצרים שצוינו. המידע הזה צריך להיות מוצג למשתמש בצורה ברורה במערכת.
• התגובה כוללת refined_search (שאילתת חיפוש מוצעת אחת או יותר, מסודרות ומדורגות) שצריך להשתמש בהן כדי לאחזר תוצאות חיפוש באמצעות ה-API המרכזי של חיפוש Google.
• BEST_PRODUCT:
• פעולה: conversational_text_response מספק המלצות או מידע על מוצרים שהכי מתאימים לשאילתה. הפרטים האלה אמורים להופיע במערכת.
• התגובה כוללת refined_search (שאילתת חיפוש מוצעת אחת או יותר, מסודרות ומדורגות) שצריך להשתמש בהן כדי לאחזר תוצאות חיפוש באמצעות ה-API המרכזי של חיפוש Google.

קטגוריה 5. שיפור הכוונה

• INTENT_REFINEMENT:
• פעולה: התשובה כוללת את conversational_text_response, followup_question ו-refined_search (שאילתת חיפוש מוצעת אחת או יותר). סדר התצוגה המומלץ הוא:
1. conversational_text_response
2. refined_search הצעות: ההצעות מסודרות ומדורגות, ולכן חשוב להציג אותן באותו סדר כמו בתשובה.
3. Followup_question
• התגובה כוללת refined_search (שאילתת חיפוש מוצעת אחת או יותר, מסודרות ומדורגות) שצריך להשתמש בהן כדי לאחזר תוצאות חיפוש באמצעות ה-API המרכזי של חיפוש Google.
• באינטראקציות הבאות, תשלח את התשובה של המשתמש יחד עם conversation_id.

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

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

כש-Conversational API מחזיר refinedSearch שאילתות, השאילתות האלה מייצגות הזדמנויות מצוינות להפנות את משתמש הקצה למוצרים רלוונטיים. האפשרות הזו שימושית במיוחד לקטגוריה 4 (שאילתות שמטרתן למצוא תשובות במודלים מסוג LLM) ולקטגוריה 5 (INTENT_REFINEMENT).

המלצה

• תצוגה: הצגת N (1-3, בהמתנה לבדיקה של המספר האידיאלי לממשק האינטרנט שלכם) refinedSearch שאילתות מובילות למשתמש.
• מנגנון: צריך להריץ את השאילתות המוצעות האלה דרך ה-API המרכזי של חיפוש Google‏ (SearchService.Search) ברקע או באינטראקציה עם המשתמש.
• הצגה: הצגת התוצאות כקרוסלות אינטראקטיביות או ככרטיסים שאפשר ללחוץ עליהם, כדי לאפשר למשתמש לעיין בקטגוריות מוצרים קשורות או בפריטים ספציפיים. התכונה הזו מספקת ערך מיידי ועוזרת לגשר על הפער בין אינטראקציה שיחתית לבין גילוי מוצרים.

בקשת Search API:

שאילת המשך

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}
  

אירועים לשליחה אל AI Commerce Search

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

1. שחזור conversation_id. כשמבצעים קריאה ל-API‏ conversationalSearch, מוחזר ConversationalSearchResponse.conversation_id.
2. תיוג אירועים של משתמשים. במקרים שבהם התשובה לשיחה מובילה לשאילתת חיפוש, למשל אם מוצגת refined_search הצעה שמשתמש הקצה לוחץ עליה, או אם המערכת מבצעת חיפוש באופן אוטומטי על סמך השאילתה המדויקת, צריך לתייג את אירוע המשתמש הבא של החיפוש (UserEvent) באותו conversation_id שהתקבל ב-ConversationalSearchResponse.

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

המשך השיחה

בקטע הזה מוסבר איך Conversational API שומר על סשנים של סוכנים לשיחה וממשיך אותם בשלב האחרון הזה.

ה-API של ממשק שיחה משתמש ב-conversation_id כדי לנהל שיחות מתמשכות. כדי להבטיח עקביות בין תשובות של LLM לבין תוצאות חיפוש, בקשות Conversational API עוקבות צריכות לכלול SearchParams שמשקפות את ההגדרה של קריאות ה-API הבסיסיות של חיפוש Google.

הצג טבלה

טיפול בסשנים	תיאור	שילוב של Conversational API
התחלת שיחה חדשה	כדי להתחיל שיחה חדשה, הלקוח משמיט את conversation_id מבקשת ה-API.	דוגמה לבקשת API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" דוגמה לתגובה מה-API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
המשך השיחה	ה-Conversational API מחזיר conversation_id כחלק מהתגובה של ה-API. אפשר לשלוח את המזהה הזה בבקשות המשך כדי להמשיך את אותה שיחה. כך אפשר לוודא שהסוכן בממשק שיחה יגיב לשאילתות של המשתמשים על סמך היסטוריית השיחות באותו סשן.	דוגמה לבקשת API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" דוגמה לתגובה מה-API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
שמירה על עקביות בתוצאות החיפוש	כדי לוודא שהתשובות של מודל ה-LLM עקביות עם תוצאות החיפוש שמוצגות, הלקוח צריך להשתמש בפרמטר SearchParams בבקשת API של Conversational. ההגדרות של פרמטרי החיפוש האלה צריכות להיות זהות להגדרות של Search API.	דוגמה לבקשת API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

טיפול בסשנים

• כדי להתחיל שיחה חדשה:
  • תיאור: כדי להתחיל שיחה חדשה, הלקוח משמיט את conversationId מבקשת ה-API.
  • מתי כדאי להתחיל שיחה חדשה: לקוח ירצה להתחיל שיחה חדשה – וכך לקבל conversationId חדש מתגובת ה-API – בכמה תרחישים נפוצים של חוויית משתמש:
    • כרטיסייה או סשן חדשים: כשלקוח פותח את האתר שלכם בכרטיסייה חדשה בדפדפן או מתחיל סשן חדש לגמרי.
    • שאילתה מקורית חדשה: בחלק מעיצובי חוויית המשתמש, אם לקוח מזין שאילתה חדשה שלא קשורה לנושא השיחה, יכול להיות שתבחרו להפעיל מחדש את רצף השיחה כדי לוודא שההקשר הכי רלוונטי.
    • כפתור להפעלת השיחה מחדש: אם בממשק האינטרנט יש כפתור מפורש של התחלת שיחה חדשה או איפוס השיחה, לחיצה עליו תפעיל סשן שיחה חדש.
  • שילוב של API לשיחות: תגובת ה-API כוללת את conversationId החדש שמשמש לבקשות הבאות.
• המשך השיחה:
  • תיאור: הפונקציה Conversational API מחזירה conversation_id כחלק מתגובת ה-API. המזהה הזה צריך להישלח בבקשות המשך כדי להמשיך את אותה שיחה. כך אפשר לוודא שהסוכן הדיגיטלי יענה לשאילתות של המשתמש על סמך היסטוריית השיחות בסשן הזה, ויכלול את query, את conversational_text_response ואת followup_question.
  • שילוב של Conversational API: הלקוח מעביר את conversation_id מהתגובה הקודמת ב-ConversationalSearchRequest.
• מוודאים שתוצאות החיפוש עקביות:
  • תיאור: כדי לוודא שהתשובות של מודל ה-LLM עקביות עם תוצאות החיפוש שמוצגות למשתמש, הלקוח חייב להשתמש ב-searchParams בבקשת Conversational API. פרמטרי החיפוש האלה צריכים להיות מוגדרים באופן זהה (למשל, מסננים, סדר מיון) לפרמטרים של קריאות ה-Search API שמתבצעות כדי לאחזר תוצאות של מוצרים.
  • שילוב של API לשיחות: האובייקט searchParams בתוך ConversationalSearchRequest צריך להיות זהה ל-SearchRequest שמשמש לחיפוש מוצרים בסיסי.

שליחת בקשה ל-AI Commerce Search

אפשר לאחזר את conversation_id מאחסון הסשן. הבקשה צריכה לכלול את הלקוח החדש query, שיכול להיות תגובה לשאלה מהתשובה הקודמת. הבקשה צריכה לכלול גם את refined_search.query האחרון מהתשובה הקודמת, אם משתמש הקצה פועל לפי שאילתה משופרת. אחרת, צריך לכלול שאילתה חדשה לגמרי שלא קשורה לשאילתה הקודמת, ואת conversationId. חשוב לזכור לכלול תמיד את הערך העקבי searchParams.

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

• תרחיש 1: סרגל חיפוש יחיד ושיחה מתמשכת: אם לממשק החיפוש יש רק סרגל חיפוש ראשי אחד או חלון שיחה מתמשך, לא תאפסו את conversationId, גם אם משתמש הקצה יקליד שאילתה חדשה שנראית לא קשורה. המערכת משתמשת בהיסטוריית השיחות הקיימת (שמשויכת ל-conversationId) כדי לספק תשובות רלוונטיות לפי ההקשר.
• תרחיש 2: חלון שיחה נפרד וחלון שאילתה נפרד: אם ממשק החיפוש כולל חלון צ'אט נפרד לשיחה וסרגל שאילתות חיפוש נפרד ורגיל (למשל תיבת חיפוש באתר), הזנת שאילתה חדשה בסרגל החיפוש הרגיל עשויה להעיד באופן משתמע על כוונה להתחיל חיפוש חדש שלא קשור לחיפוש הקודם. לכן, יכול להיות שconversationId יאופס עבור פעולת החיפוש הספציפית הזו. עם זאת, בחלון השיחה הייעודי, צריך לשמור על conversationId תמיד כדי לשמור על רצף.

בסופו של דבר, ההחלטה מתי לעשות שימוש חוזר ב-conversationId ומתי לאפס אותו היא בחירה עיצובית שמטרתה לייעל את ממשק הצ'אט עם AI של הלקוחות.

שיטת ה-HTTP ונקודת הקצה (אותן כמו בשאילתה הראשונית)

POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
    

בקשת API בממשק שיחה:

שאילת המשך

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}
  

תגובה מ-Conversational API:

תשובת המשך

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}
  

דוגמאות למשתמשי קצה שממשיכים לקבל שאלות:

• שאלה של משתמש: תעזור לי לתכנן מסיבה.
• תשובה של המערכת: איזה סוג מסיבה אתה מתכנן?
• תשובת המשתמש: מסיבת יום הולדת.

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

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

• ‫refined_search: השדה הזה מכיל שאילתות מעודכנות שמשלבות את הקלט האחרון של משתמש הקצה. צריך לעדכן את מסוף הלקוח בהתאם לשאילתה הנוכחית (למשל, להציג את השאילתה שפונה למשתמש אחרי שהיא השתנתה מ'קישוטים' ל'קישוטים למסיבת יום הולדת' או ל'ציוד למסיבת יום הולדת'). אפשר להשתמש בשאילתות של חיפוש משופר לקריאות ל-API הליבה של חיפוש Google ‏ (SearchService.Search) או להציג אותן למשתמש הקצה כהצעות.
• ‫conversational_text_response: הצגת תשובת טקסט חדשה שנוצרה על ידי AI, שרלוונטית לתור האחרון.
• ‫followup_question: אם צריך להמשיך את השיחה כדי לשפר את התוצאה, תקבלו followup_question חדש.

אירועים לשליחה אל AI Commerce Search

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

תהליך התיוג של אירועים כולל שני שלבים:

1. שחזור conversation_id. כשמבצעים קריאה ל-API‏ conversationalSearch, מוחזר ConversationalSearchResponse.conversation_id.

2. תיוג אירועים של משתמשים. במקרים שבהם התשובה לשיחה מובילה לשאילתת חיפוש, למשל אם מוצגת refined_search הצעה, או אם המערכת שלכם מבצעת חיפוש באופן אוטומטי על סמך השאילתה המדויקת, אתם צריכים לתייג את אירוע המשתמש של החיפוש הבא (UserEvent) באותו onversation_id שהתקבל בConversationalSearchResponse.

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

שילוב הסוכן עם סינון מוצרים בשיחה

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

הסבר על האינטראקציה

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

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

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

שליחת שאילתת משתמש

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

כדי להפעיל גם את הנציג לשיחות וגם את סינון המוצרים לשיחות, צריך לוודא שההגדרה הבאה כלולה ב-ConversationalSearchRequest:

בקשת Conversational Commerce API – שאילתה ראשונית

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

ההגדרות העיקריות הן:

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

מענה ראשוני: שיפור הכוונה

השדה userQueryTypes ממשיך להיות מרכזי להבנת הכוונה של המשתמש. לשאילתה רחבה ראשונית כמו Help me plan a party (עזור לי לתכנן מסיבה), סביר להניח שה-API יסווג אותה כ-INTENT_REFINEMENT אם לא ברור מייד שמדובר בחיפוש מוצר ספציפי יותר.

תשובה מ-Google

תשובה מ-Conversational Commerce API – שאילתה ראשונית

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

פעולה

1. להציג את conversationalTextResponse.
2. הצגת refinedSearch ההצעות כצ'יפים שאפשר ללחוץ עליהם, כמו קישוטים, חטיפים. אפשרות אחרת היא להתקשר אל Commerce Search API במקביל באמצעות שאילתות refined_search כדי להציג תוצאות רלוונטיות של מוצרים, למשל קישוטים, חטיפים כקרוסלה, לצד ההחלפה השיחתית.
3. להציג את followupQuestion: What kind of party are you planning?
4. המשתמשים יכולים להזין קלט של משתמשים חופשי כדי לקדם את השיחה.

תיוג אירועים וניתוח נתונים

כדי להבטיח ניתוח נתונים ושיוך מדויקים לאינטראקציה הראשונית בשיחה:

• שחזור conversation_id. מצלמים את conversation_id מ-ConversationalSearchResponse. המזהה הזה חיוני לקישור כל הפעולות הבאות לסשן השיחה הספציפי הזה.
• תיוג אירועים של משתמשים. אם התשובה בשיחה מובילה לשאילתת חיפוש, למשל אם המערכת שלכם מבצעת חיפוש באופן אוטומטי על סמך refined_search שאילתה, או אם המשתמש לוחץ על refined_search הצעה, אתם צריכים לתייג את אירוע המשתמש הבא בחיפוש (UserEvent) באותו conversation_id.

שאילת המשך

כשהמשתמש מגיב ל-followupQuestion, השיחה משתפרת.

דוגמה לקלט של משתמשים: מסיבת יום הולדת

שיפור הכוונות | קטעי קוד

בקשת Conversational Commerce API – שאילתת המשך

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

תשובה של Conversational Commerce API – שאילתת המשך

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

פעולה

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

תיוג אירועים וניתוח נתונים

כשהמשתמש ממשיך את השיחה:

• שחזור conversation_id. מוודאים שהערך conversation_id מה-ConversationalSearchResponse הקודם מועבר אל ה-ConversationalSearchRequest הנוכחי.
• תיוג אירועים של משתמשים. אם התשובה בשיחה מובילה לשאילתת חיפוש חדשה, למשל אם משתמש לוחץ על refined_search הצעה או שהמערכת שלכם מבצעת קריאה מקבילה לחיפוש, צריך לתייג את אירוע המשתמש הבא בחיפוש (UserEvent) באותו conversation_id. כך תוכלו לעקוב אחרי מסלול ההמרה של שיחה רב-שלבית.

מעבר לסינון מוצרים באמצעות שיחה

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

קלט של משתמשים לדוגמה: עיצוב של נסיכה

בקשת Conversational Commerce API – שאילתת המשך

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

תוצאות אפשריות של חיפוש מוצרים מרכזי

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

תוצאה 1: מופעל סינון

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

תגובה מ-API של מסחר שיחותי – מעבר לסינון מוצרים:

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Balloons"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Streamers"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Tablecloths"
        }
      }
    ]
  },
  "state": "SUCCEEDED"
}

פעולה

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

• תעדוף של ממשק האינטרנט לסינון מוצרים באמצעות שיחה:כשהשדה conversationalFilteringResult מאוכלס, זה מציין שהזנתם את מצב סינון המוצרים. בממשק האינטרנט צריך להדגיש את followupQuestion, שמופיע בממשק המשתמש כשאלה כמו איזה סוג ספציפי של קישוט נסיכות אתה מחפש?, ואת suggestedAnswers, כמו כפתורים שאפשר ללחוץ עליהם עם האפשרויות בלונים, סרטים, מפות שולחן.
• הצגת תוצאות של מוצרים: קוראים מיד ל-AI Commerce Search API באמצעות refined_search.query (princess birthday decorations) כדי להציג תוצאות ראשוניות של מוצרים לצד אפשרויות הסינון.
• שיטה מומלצת לחוויית משתמש: צריך להיות סרגל קבוע אחד להזנת טקסט חופשי לאורך כל חוויית השימוש. הסרגל הזה נשאר פעיל בכל שלב, כולל במהלך תהליך סינון מוצרים בשיחה. כשהתכונה conversationalFilteringResult פעילה ואתם מציגים הצעות לתשובות כצ'יפים שאפשר ללחוץ עליהם, למשתמשים יש שתי אפשרויות ברורות:
• כדי להמשיך בתהליך הסינון, לוחצים על אחת מהתשובות המוצעות.
• כדי להתחיל תור חדש בשיחה, מקלידים שאילתה חדשה בסרגל הטקסט הפעיל. הקלט החדש הזה תמיד מפעיל קריאה חדשה ל-Conversational Commerce API, וכך מסתיים למעשה תהליך הסינון הנוכחי.

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

תוצאה 2: לא מופעל סינון

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

פעולה

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

תיוג אירועים וניתוח נתונים

כשהשיחה עוברת לסינון מוצרים:

• שחזור conversation_id. להמשיך להשתמש באותו conversation_id.
• תיוג אירועים של משתמשים. אם המעבר מוביל לחיפוש מיידי, צריך לתייג את UserEvent באמצעות conversation_id. חשוב לדעת: כשמשתמש יוצר אינטראקציה עם suggestedAnswers, למשל כשמשתמש קצה לוחץ על Balloons, הפעולה הזו צריכה להפעיל גם UserEvent, למשל אירוע filter או אירוע search חדש, שתויג עם אותו conversation_id. כך אפשר לשייך פעולות סינון בתוך רצף השיחה.

המשך הסינון של מוצרים בשיחה

כשהמשתמש בוחר suggestedAnswer, שולחים ConversationalSearchRequest חדש.

דוגמה לקלט של משתמשים (קליק על תשובה מוצעת): בלונים

חיפוש פשוט של מוצרים | קטעי קוד

בקשת API של מסחר בממשק שיחה – המשך סינון

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

תשובה מ-Conversational Commerce API – המשך סינון

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

פעולה

ה-API מגיב עם שאילתת SIMPLE_PRODUCT_SEARCH אבל בלי השדה conversationalFilteringResult, מה שמצביע על כך שתהליך הסינון המודרך הסתיים.

• משתמשים בשאילתה הסופית refinedSearch (princess birthday balloons) כדי לבצע קריאה ישירה ל-AI Commerce Search API.
• הצגת תוצאות המוצרים הסופיות למשתמש. בשלב הזה, השיחה יכולה להסתיים או שהמשתמש יכול להזין שאילתה חדשה כדי להתחיל תור חדש.

תיוג אירועים וניתוח נתונים

לכל שלב בתהליך סינון המוצרים:

• שחזור conversation_id. תמיד צריך להשתמש באותו conversation_id לכל הבקשות בסשן הסינון.
• תיוג אירועים של משתמשים. כל אינטראקציה של משתמש עם suggestedAnswer, כמו קליק, צריכה להפעיל UserEvent רלוונטי, כמו אירוע filter או אירוע search חדש אם נוצרת שאילתה חדשה. צריך לתייג את UserEvent באמצעות conversation_id כדי לעקוב בצורה מדויקת אחרי תהליך הסינון וההשפעה שלו על ההמרה.

תרשים עזר לארכיטקטורה

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

תכונות בתצוגה מקדימה: הפעלה של סוכן ומנוע חשיבה רציונלית

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

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

תכונות חדשות

• שילוב של מנוע נימוקים: נעשה שימוש בסשנים של Vertex AI Conversational agent engine כדי לנהל סשנים מתמשכים. התכונה הזו מאפשרת לסוכן השיחה לשמור על ההקשר בשיחות רב-שלביות באמצעות התמדה של סשן Agent Runtime.
• תמיכה בכלי MCP: נוספה תמיכה בהפעלת כלים של Model Context Protocol‏ (MCP), שמאפשרת לסוכן לשיחה לאחזר מידע ממקורות חיצוניים ולבצע פעולות מעבר ליכולות החיפוש הרגילות של מוצרים קמעונאיים.

שינויים ב-API

הודעות ConversationalSearchRequest ו-ConversationalSearchResponse עודכנו כדי לתמוך בתכונות הבאות: שדות בקשה:

• ‫enableAgentInvocation (boolean): אם הערך מוגדר כ-true, השירות מאפשר את תהליך העבודה של הפעלת הסוכן לשיחה עבור הבקשה.
• ‫reasoningEngine (string): שם המשאב של מנוע ההסקה (מנוע הסוכן לשיחות) שמארח את הסשנים של הסוכן לשיחות, בפורמט projects/*/locations/*/reasoningEngines/*.

שדות התשובה:

• ‫agentInvocations: מכיל פרטים על הפעלת סוכן שיחה, כולל תגובות מכלי MCP.

דרישות מוקדמות

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

הגדרת סשנים מתמשכים

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

1. מפעילים את Vertex AI API בפרויקט (פרטים נוספים).
2. נותנים הרשאות IAM: מקצים לחשבון השירות [e-mail] את התפקיד משתמש ב-Vertex AI בפרויקט.
3. יצירת מנוע סוכנים: צריך ליצור מופע של מנוע נימוקים כדי לטפל בסשנים. אפשר לפעול לפי דוגמאות ממסמכי התיעוד של Vertex AI או להשתמש בסקריפט Python הבא, שמבצע אתחול.

import vertexai

from vertexai.preview import reasoning_engines

PROJECT_ID = "your-project-id"
LOCATION = "us-central1"
DISPLAY_NAME = "Session-Engine"
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
my_agent_engine_instance = client.agent_engines.create(
    config={
        "display_name": DISPLAY_NAME
    }
)

print(f"Successfully created Agent Engine: {my_agent_engine.resource_name}")

הגדרת כלי MCP

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

1. כתובת שרת ה-MCP.
2. שיטת האימות של שרת ה-MCP.
3. הכלי שאחראי לחיפוש.

דוגמה לשימוש ב-API

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

{
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Help me plan a party",
  "visitorId": "your_visitor_id",
  "enableAgentInvocation": true,
  "reasoningEngine": "projects/{project_id}/locations/{location_id}/reasoningEngines/{reasoning_engine_id}"
}

ערכות SDK בגרסת טרום-השקה פרטית

כאן אפשר לגשת לערכות ה-SDK הפרטיות של התכונות האלה: קישור ל-Google Drive.

אם אין לכם גישה לתיקייה, אתם יכולים לבקש גישה באמצעות Google Drive.

הרשמה

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

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

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