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

本指南詳細說明如何整合對話式 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，藉此建立對話式商務代理程式要求。
  • 要求應以 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)。請務必確保這些參數與核心搜尋 API 呼叫中使用的設定一致，這樣 LLM 回覆和顯示的任何產品搜尋結果才會一致。
  • userInfo：(選用) 用於強化個人化的使用者資訊。可包含 userId、user_agent、direct_user_request (布林值)。
  • conversationalFilteringSpec：(選用) 指定對話過濾模式。如果未設定，預設值為 DISABLED。

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

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

      • 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 要求

在 UI 中顯示搜尋結果主要有兩種方法：

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

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

  • 方法 2：根據對話輸出內容顯示搜尋結果

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

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

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：這個欄位提供使用者意圖的分類。如需根據這些類型採取的詳細動作，請參閱 [瞭解查詢類型和零售商動作](#step-2c)。
  • 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)。您可以將此欄位用於 UI 回饋，例如顯示載入指標，直到 SUCCEEDED 為止。詳情請參閱步驟 2b。瞭解串流 API

瞭解串流 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 查詢，立即對核心 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。您的 UI 必須顯示一些標準訊息、相關連結，或將查詢重新導向至您自己的常見問題和資訊系統。

第 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 或使用者提供的原始查詢，因為原始查詢很可能已是精確的產品搜尋字詞。請選擇最符合 UI 和搜尋結果顯示策略的選項。
    • 使用者體驗選項：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 類 (尋找大型語言模型答案的查詢) 和第 5 類 (INTENT_REFINEMENT) 特別有價值。

建議

  • 顯示：向使用者顯示前 N (1 到 3 個，理想數量待 UI 測試結果而定) refinedSearch 查詢。
  • 機制：這些建議查詢應在背景或使用者互動時，透過核心搜尋 API (SearchService.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 後，數據分析就能準確地將搜尋查詢歸因於先前的對話互動，進而提供有價值的洞察資料，瞭解使用者行為和轉換路徑。

延續對話

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

對話式 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 中的分析功能。

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

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

正確標記 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 主要著重於對話體驗和瞭解使用者意圖，而非直接傳回產品結果。
  • 使用者介面設計：設計 UI 時，請以直覺的方式清楚呈現 conversational_text_response、followup_question 和 refined_search 選項，引導使用者操作。

後續步驟

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