對話式商務代理程式開發人員指南

本指南詳細說明如何整合對話式 API，為顧客提供動態的 AI 輔助即時通訊體驗。瞭解不同查詢類型並善用 API 回應，即可提供相關產品搜尋結果、回答顧客問題，以及引導使用者完成購物歷程。

對話式 API 中的 conversationalFilteringMode 可清楚區分對話式商務代理和對話式產品篩選功能。

設定

Conversational API 支援對話式商務代理功能：

透過 Conversational API，使用者可以傳送查詢，系統則會回傳文字回覆、查詢類型分類，以及可能的精確搜尋選項，提供對話體驗。

這項 API 屬於串流服務，可及早偵測查詢意圖。對話中的後續互動必須附上 conversation_id。

如要傳回搜尋結果，必須與 Conversational API 同時呼叫舊版 Retail API。

傳送來自使用者的查詢

本節說明如何啟動對話式商務代理程式體驗。舉例來說，使用者可能會在搜尋欄位中輸入「幫我規劃派對」。

將要求傳送至 Vertex AI Search 電子商務套件

API 端點分為以下兩種：

  1. 必須使用對話式 API 擷取對話式服務。
  2. 必須使用核心 Search API 擷取搜尋結果。

端點 1：對話式 API 要求

  • 您應將使用者的輸入內容設為 query，藉此建立 Conversational Commerce 代理程式要求。
  • 要求應以 HTTP POST 要求的形式傳送至 projects/*/locations/*/catalogs/*/placements/*:conversationalSearch 端點。

HTTP 方法和端點

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

對話式 API 要求：

初始查詢

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/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：追蹤訪客的專屬 ID。這是必填欄位。
  • conversationId：追蹤對話工作階段的專屬 ID。如果是新對話中的初始要求，這個欄位應為空白。在同一項對話中，後續要求必須設為先前 ConversationalSearchResponse 中收到的 conversation_id。
  • searchParams：(選用) 標準核心搜尋參數，例如 filter、canonicalFilter、sortBy 和 boostSpec。請務必確保這些參數與核心 Search API 呼叫中使用的設定相符，以確保 LLM 回覆與顯示的任何產品搜尋結果一致。
  • userInfo：(選用) 用於強化個人化的使用者資訊。可包含 userId、user_agent、direct_user_request (布林值)。
  • conversationalFilteringSpec：(選用) 指定對話過濾模式。如果未設定，預設值為 DISABLED。

    mode：使用下列三種模式之一整合 Conversational API，控管對話式產品篩選功能：

    • DISABLED：在此模式下，用戶端只會實作對話式商務代理搜尋功能。這是本對話式商務代理程式搜尋實作指南的偏好模式。

      • 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：核心搜尋 API 要求

在網頁介面中顯示搜尋結果時，主要有兩種做法。

選項 1：一律顯示搜尋結果

如果使用者體驗設計規定無論對話輸出內容為何，都應一律顯示搜尋結果 (例如在聊天旁邊的專屬搜尋結果區域)，請在呼叫 Conversational API 時，將使用者的原始查詢傳送至核心 Product Search API。確保產品資訊能立即顯示。

選項 2：根據對話輸出內容顯示搜尋結果

如果使用者體驗設計較為動態，且您只想根據 Conversational API 的回應顯示搜尋結果 (例如只針對 SIMPLE_PRODUCT_SEARCH 查詢，或在提供 refined_search 建議時)，請先等待 Conversational API 的回應，再將任何查詢傳送至核心 Product Search API。如有回應，請使用提供的 refined_search 查詢擷取產品結果。

無論選擇哪種使用者介面選項，如要擷取實際產品結果，都可以呼叫 Retail API。詳情請參閱「瞭解查詢類型和零售商動作」。

HTTP 方法和端點

    POST https://retail.googleapis.com/v2beta/{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 (必要)：Retail Search 服務設定或舊版刊登位置的資源名稱。範例：projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search。
  • query：必填。搜尋查詢。這可以是使用者的原始輸入內容，例如「幫我規劃派對」，也可以是從 Conversational Commerce API 回應取得的更精確refinedSearch.query (例如「派對用品、裝飾」)。
  • visitorId：必填。用於追蹤訪客的專屬 ID。這應與傳送至 Conversational Commerce API 的 visitorId 一致。
  • 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。

Vertex AI Search for Commerce 的回應

這段程式碼範例會示範 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：您可以將這個專屬 ID 儲存在瀏覽器工作階段儲存空間或類似的用戶端儲存空間，與伺服器維持對話工作階段。這項資訊對於區分單一購物者的多個進行中對話至關重要。模型會保留特定 conversation_id 的脈絡。傳送新的「conversation_id」會開始新的工作階段。建議您定義工作階段時間長度，例如閒置 30 分鐘。
  • refined_search：這是建議的精確搜尋查詢清單，用於擷取相關搜尋結果。如果是 SIMPLE_PRODUCT_SEARCH，則一律為單一查詢。如果是其他尋求 LLM 回覆的查詢，則為一或多個。refined_search 查詢可用於呼叫核心 Search API (SearchService.Search)，也可以向使用者顯示為建議。
  • conversational_text_response：向使用者顯示這段文字，做為查詢的主要 AI 生成回覆。
  • followup_question：選用。系統會顯示 followup_question。
  • state：這個欄位會指出回應生成狀態 ("STREAMING" 或 "SUCCEEDED")。您可以將這項資訊用於使用者體驗意見回饋，例如顯示載入指標，直到 "SUCCEEDED" 為止。詳情請參閱下一節。

瞭解串流 API

對話式商務 API 是串流 API，也就是說，使用者會收到多個區塊的回應，而不是單一完整的酬載。

第一段回應包含 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，您的系統可以使用在第一個區塊中收到的 refined_search 查詢，立即直接呼叫核心搜尋 API。這有助於確保搜尋結果以最短延遲時間顯示，符合一般搜尋體驗服務水準協議。
  • 對於會傳回對話式文字回應的查詢類型 (例如 INTENT_REFINEMENT、PRODUCT_DETAILS、PRODUCT_COMPARISON、BEST_PRODUCT)：
    • 您會在初始區塊中收到 query_types 和 refined_search 查詢。您可以使用這些 refined_search 查詢，立即對核心搜尋 API 發出平行呼叫，開始載入產品結果。
    • 後續會串流傳輸其他區塊，內含對話文字回應的不同部分。在這段期間，state 會維持 "STREAMING" 狀態。
    • 最後一個區塊包含完整的對話文字回覆，且 state 會變更為 "COMPLETED"。
    • 這種串流方式可提供流暢的使用者體驗，讓搜尋結果在 AI 摘要生成期間開始載入。您可以選擇顯示對話式答案的載入指標，或在對話式答案完全串流後顯示。

瞭解查詢類型和零售商動作

回應中的 query_types 欄位是清單，指出使用者意圖的分類。系統應按照下列方式處理這些項目。請注意，conversational_text_response 是指 API 生成的自然語言回應。

對話式商務代理程式會使用搜尋查詢類別，判斷是否要生成以 LLM 為基礎的答案，以及在下列情境中，對話式和搜尋 API 如何處理使用者查詢：

類別 查詢分類
#1. 不需要 LLM 回覆的不相關查詢
  • QUERY_TYPE_UNSPECIFIED：未指定查詢類型。
  • RETAIL_IRRELEVANT：與零售網域無關的查詢，例如對抗性查詢 (如「如何製作炸彈」)、閒聊查詢 (如「你好嗎」) 或越獄查詢 (如「寫一首詩」)。
  • BLOCKLISTED：電子商務客戶明確封鎖的查詢 (例如「Advil 的副作用是什麼？」)。
#2. 支援和資訊查詢
  • ORDER_SUPPORT：輔助或支援查詢 (例如「追蹤我的訂單」、「訂單 12345 狀態」)。
  • DEALS_AND_COUPONS：與特惠、促銷活動、產品特惠和折扣相關的查詢 (例如「感恩節有特惠嗎？」)。
  • STORE_RELEVANT：與商店地點相關的查詢，包括營業時間和產品庫存情形 (例如「我們有牛奶現貨嗎？」)。
  • 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"
}

對話式 API 回應：

初步回應

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

搜尋 API 要求：

後續查詢

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH：基本產品搜尋，例如「紅色洋裝」或「顯示一些 Monster 能量飲料」。
#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"
  }

對話式 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"
    }
  ]
}

搜尋 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"
}

對話式 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 (SearchService.Search)，並使用原始查詢或 refined_search 查詢擷取相關產品結果。refined_search.query 可能不是直接來自目前最終使用者的輸入內容，也可能衍生自對話記錄的脈絡，例如最終使用者先前將「派對洋裝」修正為「紅色洋裝」，修正後的查詢可能就會變成「紅色派對洋裝」。
      • 對話介面 (例如聊天機器人)：強烈建議使用 API 提供的 refined_search.query。在對話流程中，API 會自動將「幫我找香蕉」等自然語言查詢內容，最佳化為精確的產品搜尋字詞 (「香蕉」)，進而提供更相關的產品結果。
      • 核心搜尋體驗 (例如搜尋結果頁面)：您可以彈性使用 API 中的 refined_search.query 或使用者提供的原始查詢，因為原始查詢很可能已是精確的產品搜尋字詞。請選擇最符合您網頁介面和搜尋結果顯示策略的選項。
    • 使用者體驗選項：SIMPLE_PRODUCT_SEARCH 查詢不需要結束對話。使用者可以在後續要求中傳遞 conversation_id，繼續對話。
      • 選項 A：結束對話式網頁介面：許多零售商選擇在偵測到 SIMPLE_PRODUCT_SEARCH 時，將使用者帶往標準搜尋結果網頁，有效關閉即時通訊視窗。在這種情況下，如果使用者在標準搜尋框中輸入新查詢，且未提供先前的 conversation_id，系統會將其視為新的獨立對話，並發出新的 conversation_id。
      • 方法 B：繼續使用對話式網頁介面：零售商可以選擇讓對話視窗保持開啟狀態。使用者可以藉此返回對話模式。實作選項 A 或 B 完全取決於零售商偏好的使用者體驗。

    如要將搜尋查詢準確歸因於對話互動，並在商家適用的 Vertex AI Search 中使用完整分析功能，請務必正確標記事件：

    1. 擷取 conversation_id。當您發出 conversationalSearch API 呼叫時，系統會傳回 ConversationalSearchResponse.conversation_id。
    2. 標記使用者事件。如果對話式回覆會產生搜尋查詢 (例如系統根據 SIMPLE_PRODUCT_SEARCH 的精簡查詢自動執行搜尋)，您必須使用 ConversationalSearchResponse 中收到的相同 conversation_id，標記後續的搜尋使用者事件 (UserEvent)。

只要正確標記 UserEvent.conversation_id，數據分析就能準確地將搜尋查詢歸因於先前的對話互動，進而提供寶貴的洞察資料，協助您瞭解使用者的行為和轉換路徑。

第 4 類。尋求 LLM 回覆的查詢

對於這類查詢，API 會生成 conversational_text_response (LLM 回覆)，也可能會提供一或多個 refined_search 查詢。對話不會結束，使用者可以繼續對話。

  • PRODUCT_DETAILS：
    • 動作：conversational_text_response 提供所要求的產品詳細資料。系統應清楚向使用者顯示這項資訊。
    • 回覆內容也包含 refined_search (一或多個建議搜尋查詢，已排序和排名)，應使用這些查詢透過核心搜尋 API 擷取搜尋結果。
  • PRODUCT_COMPARISON：
    • 動作：conversational_text_response 會比較指定產品。系統應清楚向使用者顯示這項資訊。
    • 回覆內容包含 refined_search (一或多個建議搜尋查詢，已排序和排名)，應使用這些查詢透過核心搜尋 API 擷取搜尋結果。
  • BEST_PRODUCT：
    • 動作：conversational_text_response 會提供最符合查詢的產品建議或資訊。系統應會顯示這項資訊。
    • 回覆內容包含 refined_search (一或多個建議搜尋查詢，已排序和排名)，應使用這些查詢透過核心搜尋 API 擷取搜尋結果。

類別 5。意圖修正

  • INTENT_REFINEMENT：
    • 動作：回應包含 conversational_text_response、followup_question 和 refined_search (一或多個建議搜尋查詢)。建議的顯示順序如下：
      1. conversational_text_response
      2. refined_search 建議：這些建議會排序和排名，因此請務必按照回應的順序顯示。
      3. Followup_question
    • 回覆內容包含 refined_search (一或多個建議搜尋查詢，已排序和排名)，應使用這些查詢透過核心搜尋 API 擷取搜尋結果。
    • 如要進行後續互動，請連同 conversation_id 一併傳送使用者的答案。

顯示產品的建議查詢

以下說明如何設定 Google 搜尋，在對話式商務代理程式中顯示問題和產品建議。

當 Conversational API 傳回 refinedSearch 查詢時，這些查詢代表絕佳機會，可引導使用者前往相關產品。這對第 4 類 (尋求 LLM 答案的查詢) 和第 5 類 (INTENT_REFINEMENT) 尤其有價值。

建議

  • 顯示：向使用者顯示前 N (1 到 3 個，具體數量取決於網頁介面的理想數量測試) refinedSearch 查詢。
  • 機制：這些建議查詢應在背景或使用者互動時，透過核心搜尋 API (SearchService.Search) 執行。
  • 呈現方式：以互動式輪轉介面或可點選的資訊卡顯示結果，讓使用者瀏覽相關產品類別或特定項目。這項功能可立即提供價值，並縮短對話互動與產品探索之間的差距。

Search API 要求：

後續查詢

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

要傳送至 Vertex AI Search 電子商務套件的事件

請務必使用正確的事件標記，將搜尋查詢準確歸因於對話互動，並在 Vertex AI Search for Commerce 中使用完整分析功能：

  1. 擷取 conversation_id。當您發出 conversationalSearch API 呼叫時，系統會傳回 ConversationalSearchResponse.conversation_id。
  2. 標記使用者事件。如果對話式回覆會產生搜尋查詢 (例如顯示 refined_search 建議，且使用者點選該建議)，或是系統根據修正後的查詢自動執行搜尋，您必須使用 ConversationalSearchResponse 中收到的相同 conversation_id，為後續搜尋使用者事件 (UserEvent) 加上標記。

正確標記 UserEvent.conversation_id 後，您的 Analytics 就能準確將搜尋查詢歸因於先前的對話互動，進而提供有價值的洞察資料，協助您瞭解使用者行為和轉換路徑。

延續對話

本節說明 Conversational API 如何維護對話式商務代理程式工作階段，並在最後一個步驟中繼續進行。

Conversational API 會使用 conversation_id 管理進行中的對話。為確保 LLM 回答與搜尋結果一致，後續的 Conversational API 要求必須包含 SearchParams，以反映核心 Search API 呼叫的設定。

工作階段處理

  • 發起新對話：
    • 說明：如要開始新的對話，用戶端會從 API 要求中省略 conversationId。
    • 何時應開始新的對話：在幾種常見的使用者體驗情境中，用戶會想開始新的對話，藉此從 API 回應取得新的 conversationId：
      • 新分頁或工作階段：顧客在新瀏覽器分頁中開啟您的網站，或啟動全新的工作階段。
      • 新的原始查詢：在某些使用者體驗設計中，如果顧客輸入新的不相關查詢，您可能會選擇重新啟動對話流程，確保提供最相關的背景資訊。
      • 重新啟動對話按鈕：如果網頁介面提供明確的「開始新的對話」或「重設對話」按鈕，點選這個按鈕會觸發新的對話工作階段。
    • 對話式 API 整合：API 回應包含新的 conversationId，用於後續要求。
  • 繼續對話：
    • 說明：Conversational API 會在 API 回應中傳回 conversation_id。後續要求必須傳送這個 ID，才能繼續同一段對話。這有助於確保對話式商務代理程式根據該工作階段內的對話記錄回覆使用者的查詢，涵蓋使用者query、conversational_text_response和followup_question。
    • 對話式 API 整合：用戶端會在 ConversationalSearchRequest 中傳遞先前回應中的 conversation_id。
  • 確保搜尋結果一致性：
    • 說明：為確保 LLM 回覆內容與顯示給使用者的搜尋結果一致，用戶端必須在 Conversational API 要求中使用 searchParams。這些搜尋參數應與用於擷取產品結果的 Search API 呼叫具有相同的設定，例如篩選器、排序順序。
    • 對話式 API 整合：ConversationalSearchRequest 中的 searchParams 物件應與用於核心產品搜尋的 SearchRequest 相同。

將要求傳送至 Vertex AI Search 電子商務套件

您可以從工作階段儲存空間擷取 conversation_id。要求應包含新客戶 query，這可能是對先前回應中問題的回覆。如果使用者根據修正後的查詢採取行動，要求也應包含先前回應中的最新 refined_search.query。否則，應包含完全不相關的新查詢，以及 conversationId。請務必一律加入一致的 searchParams。

  • 情境 1：單一搜尋列和持續對話：如果搜尋介面只有一個主要搜尋列或持續對話視窗，即使使用者輸入看似不相關的新查詢，也不會重設 conversationId。系統會使用現有的對話記錄 (與 conversationId 相關聯)，提供符合情境的回覆。
  • 情境 2：對話視窗和查詢視窗分開：如果搜尋介面設有獨立的對話聊天視窗，以及分開的標準搜尋查詢列 (例如全站搜尋方塊)，在標準搜尋列中輸入新查詢可能會隱含開始新搜尋的意圖，因此可能導致該特定搜尋動作的 conversationId 重設。不過，在專屬的對話視窗中，conversationId 應一律維持不變，確保對話連貫。

最終，決定何時要重複使用或重設 conversationId 是設計選擇，目的是為顧客提供最佳對話體驗。

HTTP 方法和端點 (與初始查詢相同)

POST https://retail.googleapis.com/v2alpha/{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\")"
  }
}

對話式 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：這個欄位包含更新後的查詢，其中納入了使用者的最新輸入內容。您應相應更新目前查詢的用戶端控制台 (例如，顯示使用者查詢已從「裝飾品」變更為「生日派對裝飾品」或「生日派對用品」)。精簡搜尋查詢可用於呼叫核心 Search API (SearchService.Search)，也可以向使用者顯示為建議。
  • conversational_text_response：顯示與最新對話輪次相關的 AI 生成文字回覆。
  • followup_question：如果需要繼續對話以進一步修正，系統會提供新的 followup_question。

要傳送至 Vertex AI Search 電子商務套件的事件

事件標記非常重要，因為這有助於將搜尋查詢準確歸因於對話互動，並使用 Vertex AI Search for Commerce 的分析功能。

事件標記程序分為兩個步驟：

  1. 擷取 conversation_id。當您發出 conversationalSearch API 呼叫時，系統會傳回 ConversationalSearchResponse.conversation_id。
  2. 標記使用者事件。如果對話式回覆會產生搜尋查詢 (例如顯示 refined_search 建議)，或是系統根據經過修正的查詢自動執行搜尋，您必須使用 ConversationalSearchResponse 中收到的相同 conversation_id，標記後續的搜尋使用者事件 (UserEvent)。

正確標記 UserEvent.conversation_id 後，您的 Analytics 就能準確地將搜尋查詢歸因於先前的對話互動，進而深入瞭解使用者行為和轉換路徑。

整合代理程式與對話式產品篩選功能

本指南說明如何整合對話式 API 和對話式產品篩選功能，提供 AI 輔助的購物體驗。如果將 conversationalFilteringSpec.mode 設為 ENABLED，系統就能直接在開放式對話互動和引導式產品篩選之間轉換，提供精緻的使用者歷程。

瞭解互動方式

同時啟用對話式商務代理程式和對話式產品篩選功能時，系統會充分發揮兩者的優勢。對話式商務服務專員會處理廣泛的查詢、提供 AI 生成的回覆，並修正初始意圖，而對話式產品篩選功能則會透過簡化的晶片或圖塊互動模型，引導使用者選取特定產品屬性。

當對話式商務 API 的分類結果為以產品為導向的搜尋 (具體來說是 SIMPLE_PRODUCT_SEARCH)，就會出現互動點，並在這兩種模式之間進行潛在轉換。此時，API 可以直接提供搜尋查詢，或在使用者意圖可進一步精確判斷的情況下，透過對話式產品篩選功能觸發引導式篩選流程。

這項整合功能的主要原則是，所有自由輸入的文字都由 Conversational Commerce API 處理，而點選以動態磚形式顯示的建議答案，則由對話式產品篩選功能處理。

傳送使用者查詢

使用者輸入內容範例：幫我規劃一場派對

如要同時啟用對話式商務代理和對話式產品篩選功能，請確保 ConversationalSearchRequest 包含以下設定：

對話式商務 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：在 conversationalFilteringSpec 中將這個欄位設為 ENABLED，可讓 API 瞭解系統可處理對話式產品篩選，進而提供相關的篩選專屬回應。

首要回應：意圖修正

userQueryTypes 欄位仍是瞭解使用者意圖的關鍵。如果是初步的廣泛查詢 (例如「幫我規劃派對」)，如果無法立即判斷是否為更具體的產品搜尋，API 可能會將其分類為 INTENT_REFINEMENT。

Google 回覆

對話式商務 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 建議，例如「裝飾」、「零食」。或者，您也可以使用 refined_search 查詢並行呼叫 Commerce Search API，在對話過程中顯示相關產品結果，例如「裝飾品、零食」的輪轉介面。
  3. 顯示 followupQuestion：「你打算舉辦哪種派對？」
  4. 允許使用者輸入任意內容，繼續對話。

事件代碼和數據分析

為確保初始對話互動的分析和歸因準確無誤，請採取下列做法：

  • 擷取 conversation_id。從 ConversationalSearchResponse 擷取 conversation_id。這個 ID 至關重要，可將所有後續動作連結至這個特定對話工作階段。
  • 標記使用者事件。如果對話式回覆會產生搜尋查詢 (例如系統根據 refined_search 查詢自動執行搜尋)，或使用者點按 refined_search 建議，您必須使用相同的 conversation_id 標記後續搜尋使用者事件 (UserEvent)。

後續查詢

使用者回覆 followupQuestion 後，對話就會變得更精確。

使用者輸入內容範例：生日派對

意圖修正 | 程式碼片段

對話式商務 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"
  }
}

對話式商務 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。確認先前 ConversationalSearchResponse 中的 conversation_id 已傳遞至目前的 ConversationalSearchRequest。
  • 標記使用者事件。如果對話式回覆導致新的搜尋查詢 (例如使用者點選 refined_search 建議，或系統發出並行搜尋呼叫)，請使用相同的 conversation_id 標記後續搜尋使用者事件 (UserEvent)。這有助於追蹤多輪對話歷程。

改用對話式產品篩選功能

隨著對話內容越來越具體，系統可能會將意圖分類為 SIMPLE_PRODUCT_SEARCH，並在適當情況下觸發對話式產品篩選。

使用者輸入內容範例：公主主題

對話式商務 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": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

動作

這項查詢現在已歸類為 SIMPLE_PRODUCT_SEARCH。系統會啟動對話式產品篩選功能。不過，系統可能不會觸發對話式產品篩選功能。

  • 優先使用對話式產品篩選網頁介面：填入 conversationalFilteringResult 時，表示你已進入產品篩選模式。網頁介面應強調 followupQuestion，這會在使用者介面上顯示為「您要找哪種公主裝飾？」，以及 suggestedAnswers，例如「氣球」、「彩帶」、「桌巾」等可點選的按鈕。
  • 顯示產品結果：立即使用 refined_search.query (公主生日裝飾) 呼叫 Retail Search API，顯示初始產品結果和篩選選項。
  • 建議的使用者體驗做法：整個體驗應只有一個持續顯示的自由文字輸入列。即使在對話式產品篩選流程中，這個工具列也會持續顯示。 當 conversationalFilteringResult 處於啟用狀態，且您將建議答案顯示為可點選的動態磚時，使用者會有兩個明確的選項：
    • 按一下建議答案，繼續篩選流程。
    • 在有效文字列中輸入新查詢，開始新的對話回合。這項新輸入內容一律會觸發對 Conversational Commerce API 的新呼叫，有效結束目前的篩選流程。

結果 2：未觸發篩選

如果查詢已夠具體，或不適合進一步篩選，回應就不會包含 conversationalFilteringResult 欄位。在這種情況下，請繼續進行標準搜尋。

動作

  • 將互動視為對話流程的結尾，並使用 refined_search 查詢呼叫 Retail Search API，然後顯示標準產品結果頁面。

事件代碼和數據分析

對話轉為產品篩選時：

  • 擷取 conversation_id。繼續使用相同的 conversation_id。
  • 標記使用者事件。如果轉換會立即進行搜尋，請使用 conversation_id 標記 UserEvent。重要事項：當使用者與 suggestedAnswers 互動時 (例如點選「氣球」)，這項動作也應觸發 UserEvent，例如 filter 事件或新的 search 事件，並標記相同的 conversation_id。這樣一來，系統就能在對話流程中歸因篩選動作。

繼續使用對話式產品篩選功能

使用者選取 suggestedAnswer 時，請傳送新的 ConversationalSearchRequest。

使用者輸入內容範例 (點選建議答案)：氣球

簡單的產品搜尋 | 程式碼片段

Conversational Commerce 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"
  }
}

對話式商務 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) 直接呼叫 Retail Search API。
  • 向使用者顯示最終產品結果。此時對話可以結束，使用者也可以輸入新查詢來開始新一輪對話。

事件代碼和數據分析

在產品篩選程序的每個步驟中：

  • 擷取 conversation_id。在篩選工作階段中，所有要求一律使用相同的 conversation_id。
  • 標記使用者事件。使用者與 suggestedAnswer 互動時 (例如點擊)，應觸發相關的 UserEvent，例如 filter 事件，或是在形成新查詢時觸發新的 search 事件。這個 UserEvent 必須標記 conversation_id，才能準確追蹤篩選歷程，以及對轉換的影響。

使用者介面建議和設計選項

對話式商務代理和對話式產品篩選功能之間的互動非常靈活。如要打造流暢直覺的體驗，請注意以下幾項重要的使用者體驗考量：

  • 單一輸入列：整個體驗只能有一個任意文字輸入列。對話式產品篩選功能沒有專屬的輸入列，這可簡化使用者介面，並確保互動方式一致。
  • 流暢的轉換：設計網頁介面時，請確保對話回覆、建議查詢和篩選選項之間的轉換自然直覺。
  • 明確的指引：使用視覺提示 (例如建議回覆的按鈕樣式與一般輸入內容不同)，並提供清楚的指示，引導使用者在每個階段進行互動。
  • 平衡控制權：使用者應能隨時掌控對話方向。
    • 篩選與任意形式：單一任意文字輸入列會持續啟用。使用者可以選擇點選建議答案，繼續修正搜尋內容，也可以在文字列中輸入新查詢，發起新一輪對話。這項設計可確保即使在篩選流程中，使用者也能在需求改變時轉向其他主題。
    • 重設選項：提供清楚的「開始新對話」或「重設篩選器」選項，讓使用者重新開始搜尋或篩選程序。

  • 視覺化持續性：即使轉換至產品篩選程序，在對話視窗中保留對話記錄 (例如顯示先前的問題和答案)，也能提升情境脈絡和使用者體驗。

其他注意事項與最佳做法

實作對話式商務代理程式介面時，必須考量其他事項並採用最佳做法：

  • 訪客 ID 一致性：確保系統在每次要求中，都會為特定使用者傳送專屬 visitor_id。這對準確提供個人化體驗和訓練模型至關重要。理想情況下，這個 ID 應在工作階段和登入/登出狀態之間保持一致。
  • 分店管理：雖然 default_branch 很常見，但如果產品目錄包含多個分店，請務必使用正確的分店 ID。
  • Search API 互動：如果是 SIMPLE_PRODUCT_SEARCH 和提供 refined_search 的任何情況，請記得使用 refined_search 欄位中的 query 或原始查詢，對核心 Search API (SearchService.Search) 進行個別呼叫，以取得實際的產品資訊。對話式 API 主要著重於對話體驗和瞭解使用者意圖，而非直接傳回產品結果。
  • 使用者介面設計：設計網頁介面，以直覺方式清楚呈現 conversational_text_response、followup_question 和 refined_search 選項，引導使用者操作。

後續步驟

如需其他支援資源，請參閱對話功能常見問題。