对话式商务代理开发者指南

本指南详细介绍了如何与 Conversational API 集成，以便为客户提供动态的 AI 赋能聊天体验。通过了解不同的查询类型并利用 API 的响应，您可以提供相关的商品搜索结果、回答客户的咨询，并引导最终用户完成购物历程。

对话式 API 中的 conversationalFilteringMode 清楚地说明了对话式商务代理与对话式商品过滤之间的区别。

设置

对话式 API 支持对话式商务代理功能：

• gRPC：conversationalSearchService
• REST：conversationalSearch

借助 Conversational API，用户可以发送查询，系统会返回文本响应、分类的查询类型和潜在的优化搜索选项，从而实现聊天体验。

此 API 作为流式传输服务运行，可尽早检测到查询意图。对话中的后续互动需要附加 conversation_id。

对于返回搜索结果，必须并行调用旧版 Retail API 和 Conversational API。

最终用户发送查询

本部分介绍了如何启动对话式商务代理体验。例如，用户可能会在搜索字段中输入帮我策划派对。

向 Vertex AI Search for Commerce 发送请求

有两个不同的 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：用于跟踪访问者的唯一标识符。这是必填字段。
• 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。如需了解详情，请参阅第 2c 步。了解搜索查询类型和零售商操作。

HTTP 方法和端点

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

核心 Product 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：必需。用于跟踪访问者的唯一标识符。此值应与针对同一最终用户发送到 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 商务解决方案的回答

此代码示例展示了 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）。您可以将其用于界面反馈，例如显示加载指示器，直到状态变为 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 位于第一个 chunk 中，因此您的系统会立即知道不会有 LLM 回答。您可以继续执行针对这些类型的预定义处理，例如显示静态消息、重新路由到支持服务，而无需等待进一步的对话输出。
• 对于 SIMPLE_PRODUCT_SEARCH，您的系统可以使用在第一个块中收到的 refined_search 查询立即直接调用核心 Search API。这有助于确保搜索结果以最短的延迟显示，从而满足典型的搜索体验 SLA。
• 对于确实需要对话式文本回答的查询类型（例如 INTENT_REFINEMENT、PRODUCT_DETAILS、PRODUCT_COMPARISON、BEST_PRODUCT）
• 您会在初始块中收到 query_types 和 refined_search 查询。您可以使用这些 refined_search 查询立即启动对核心 Search API 的并行调用，开始加载商品结果。
• 后续块会以流式传输方式传入，其中包含对话文本响应的不同部分。在此期间，state 仍为 "STREAMING"。
• 最后，最后一个 chunk 包含完整的对话文本回答，其 state 会更改为 "COMPLETED"。
• 这种流式传输方法可带来流畅的最终用户体验，让搜索结果在 AI 摘要生成的同时开始加载。您可以选择显示对话式回答的加载指示器，也可以在对话式回答完全流式传输后显示。

了解查询类型和零售商操作

响应中的 query_types 字段是一个列表，用于指明用户意图的分类。您的系统应按如下方式处理这些情况。请注意，conversational_text_response 是指 API 生成的自然语言回答。

对话式商务代理使用搜索查询类别来确定是否生成基于 LLM 的回答，以及在以下场景中，对话式 API 和搜索 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：与模式最匹配的查询，例如哪种饼干最健康？哪个牛奶品牌最好？）。
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 查询。此优化后的查询充当建议的搜索字词。直接调用核心 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，Google Analytics 可以准确地将搜索查询归因于之前的对话互动，从而深入了解用户的行为和转化路径。

类别 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) 在后台或在用户互动时运行。
• 展示：以互动式轮播界面或可点击的卡片形式展示结果，让用户浏览相关产品类别或特定商品。这可立即提供价值，并有助于弥合对话式互动与商品发现之间的差距。

搜索 API 请求：

后续查询

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

要发送给 Vertex AI Search for Commerce 的事件

请务必正确地将搜索查询归因于对话互动，并使用 Vertex AI Search for Commerce 中的完整分析功能，方法是使用正确的事件标记：

1. 检索 conversation_id：当您发出 conversationalSearch API 调用时，系统会返回 ConversationalSearchResponse.conversation_id。
2. 标记用户事件：如果对话式回答导致了搜索查询（例如通过显示最终用户点击的 refined_search 建议），或者您的系统根据优化后的查询自动执行搜索，您必须使用 ConversationalSearchResponse 中收到的相同 conversation_id 标记后续搜索用户事件 (UserEvent)。

通过正确标记 UserEvent.conversation_id，Google Analytics 可以准确地将搜索查询归因于之前的对话互动，从而提供有关用户行为和转化路径的宝贵数据洞见。

继续对话

本部分介绍了 Conversational API 如何维护对话式商务代理会话，并在最后一步中继续进行。

对话式 API 使用 conversation_id 来管理正在进行的对话。为确保 LLM 回答与搜索结果保持一致，后续 Conversational API 请求必须包含与核心搜索 API 调用的配置相对应的 SearchParams。

查看表

会话处理	说明	对话式 API 集成
发起新对话	如需开始新的对话，客户端会在 API 请求中省略 conversation_id。	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 会在 API 响应中返回 conversation_id。此 ID 可在后续请求中发送，以继续进行同一对话。这有助于确保对话式商务代理根据相应会话中的对话历史记录来回答用户的查询。	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 回答与显示的搜索结果一致，客户端必须在对话 API 请求中使用 SearchParams。这些搜索参数应具有与核心 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" } } }

会话处理

• 发起新对话：
  • 说明：如需开始新对话，客户端会在 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 for Commerce 发送请求

您可以从会话存储空间中检索 conversation_id。请求应包含新客户 query，这可能是对上一个响应中问题的回答。如果最终用户根据优化后的查询采取行动，则请求还应包含上一个响应中的最新 refined_search.query。否则，应包含一个完全无关的新查询，以及 conversationId。请务必始终包含一致的 searchParams。

注意： conversationId 是为新的最终用户查询保留还是重置，取决于您的具体用户体验选择和所选的用户体验。conversationId 可充当指定对话会话的系统内存。

• 情形 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 for Commerce 的事件

事件标记对于准确地将搜索查询归因于对话互动，以及使用 Vertex AI Search for Commerce 中的分析功能至关重要。

事件标记过程分为两个步骤：

1. 检索 conversation_id：当您发出 conversationalSearch API 调用时，系统会返回 ConversationalSearchResponse.conversation_id。
2. 标记用户事件：如果对话式回答导致了搜索查询（例如通过显示 refined_search 建议），或者如果您的系统根据优化后的查询自动执行搜索，您必须使用 ConversationalSearchResponse 中收到的相同 conversation_id 标记后续的搜索用户事件 (UserEvent)。

通过正确标记 UserEvent.conversation_id，Google Analytics 可以准确地将搜索查询归因于之前的对话互动，从而提供有关最终用户行为和转化路径的宝贵数据洞见。

其他注意事项和最佳实践

在实现对话式商务代理界面时，您必须考虑其他注意事项和最佳实践：

• 访问者 ID 一致性：有助于确保为给定最终用户的每个请求始终发送唯一的 visitor_id。这对于准确的个性化和模型训练至关重要。理想情况下，此标识符应在最终用户的不同会话以及登录或退出状态下保持一致。
• 分支管理：虽然 default_branch 很常见，但如果您的产品目录包含多个分支，请确保您使用的是正确的分支 ID。
• Search API 互动：对于 SIMPLE_PRODUCT_SEARCH 和提供 refined_search 的任何情况，请务必使用 refined_search 字段中的 query 或原始查询单独调用核心 Search API (SearchService.Search)，以获取实际的产品详情。Conversational API 主要侧重于对话体验和用户意图理解，而不是直接返回商品结果。
• 界面设计：设计界面时，应以直观的方式清晰呈现 conversational_text_response、followup_question 和 refined_search 选项，以便引导用户。

后续步骤

如需获取其他支持资源，请参阅对话功能常见问题解答。