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

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

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

API 设置和调用流程

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

借助 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/v2/{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。如需了解详情，请参阅了解用户意图分类和零售商操作。

HTTP 方法和端点

    POST https://retail.googleapis.com/v2/{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 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 作为流式传输服务运行。这意味着，您的用户会收到多个块的响应，而不是单个完整的载荷。

  • 为什么要直播？LLM 生成文本可能需要一些时间。借助流式传输，您可以更快地采取行动。
  • 第一个响应块（即时）：
  • 包含 userQueryTypes 和 refinedSearch 查询。
  • state："STREAMING"
  • 后续数据块：
  • 包含生成过程中的 conversationalTextResponse 部分。
  • 最终数据块：
  • 包含完整、完整的 conversationalTextResponse。
  • state："SUCCEEDED"
  • 可据以采取行动的数据洞见：您可以立即从第一个块中确定用户意图，并在 AI 文本响应仍在加载时并行开始提取商品结果。

响应的第一个 chunk 包含 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，您的系统可以使用在第一个 chunk 中收到的 refined_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 生成的自然语言回答。

userQueryTypes 字段（在第一个响应块中）是确定应用下一步操作的最重要字段：

  • SIMPLE_PRODUCT_SEARCH：红裙
    • API 响应：无 conversational_text_response。返回单个 refinedSearch 查询。
    • 您的操作：立即使用 refinedSearch.query 调用 Search API。过渡到标准搜索结果页或显示结果。
  • INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT：策划派对
    • API 响应：提供 conversationalTextResponse、refinedSearch 查询，可能还提供 followupQuestion。
    • 您的操作：显示 AI 文字回答。使用 refinedSearch 查询来填充商品轮播界面或建议。显示 followupQuestion。
  • 支持查询：包括 ORDER_SUPPORT 和 STORE_RELEVANT。
    • API 响应：无 conversational_text_response。
    • 您的操作：将用户重定向到相应页面，例如“订单跟踪”“实体店查询”页面，或显示预设的回答。

对话式商务代理会使用搜索查询类别来确定是否生成基于 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。
    • 操作：通过显示适当的消息来处理此问题，例如 I can't answer that question（我无法回答这个问题）或 I am a shopping assistant, how can I help you?（我是购物助理，我可以为您提供哪些帮助？），具体取决于应用的设计。
  • 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：结束对话式 Web 界面：许多零售商选择在检测到 SIMPLE_PRODUCT_SEARCH 后，将用户转到标准搜索结果页，从而有效地关闭聊天窗口。在这种情况下，如果最终用户随后在标准搜索框中输入不含之前 conversation_id 的新查询，系统会将其视为新的单独对话，并发出新的 conversation_id。
      • 选项 B：继续使用对话式网页界面：零售商可以选择保持聊天窗口处于打开状态。这样，用户就可以恢复到对话模式。选择实施方案 A 还是方案 B 完全取决于零售商偏好的用户体验。

    为了准确地将搜索查询归因于对话互动，并在 Vertex AI Search for commerce 中使用完整的分析功能，正确标记事件至关重要：

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

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 商务解决方案中使用完整的分析功能：

  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 请求中省略 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。

  • 情形 1：单个搜索栏和持续对话：如果您的搜索界面只有一个主搜索栏或一个持续对话窗口，即使最终用户输入看似无关的新查询，您也不会重置 conversationId。系统会使用现有的对话记录（与 conversationId 相关联）来提供与上下文相关的回答。
  • 情形 2：单独的对话窗口和查询窗口：如果您的搜索界面提供单独的对话式聊天窗口和单独的标准搜索查询栏（例如网站范围的搜索框），那么在标准搜索栏中输入新查询可能会隐式表明您打算开始新的无关搜索，从而可能导致 conversationId 针对该特定搜索操作重置。不过，在专用对话窗口中，应始终保持 conversationId 以确保对话的连贯性。

最终，决定何时重用与重置 conversationId 是一项设计选择，旨在为客户优化对话体验。

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\")"
  }
}

对话式 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 中收到的相同 onversation_id 来标记后续的搜索用户事件 (UserEvent)。

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

将代理与对话式商品过滤功能集成

本指南概述了如何与 Conversational API 和对话式商品过滤功能集成，以提供依托 AI 技术的购物体验。当 conversationalFilteringSpec.mode 设置为 ENABLED 时，您的系统可以直接在开放式对话互动和引导式产品过滤之间转换，从而提供高度精细的用户体验。

了解相互作用

如果同时启用了对话式商务代理和对话式产品过滤，系统会充分利用两者的优势。对话式商务代理可处理广泛的查询，提供 AI 生成的回答，并优化初始意图，而对话式产品过滤功能则使用简化的基于功能块或平铺的互动模型引导用户选择特定的产品属性。

当对话式商务 API 的分类导致以产品为导向的搜索（具体来说是 SIMPLE_PRODUCT_SEARCH）时，就会出现这两种模式之间的互动点和潜在过渡。此时，API 可以提供直接搜索查询，或者，如果可以进一步细化用户意图，则通过对话式产品过滤功能触发引导式过滤流程。

此集成的一个关键原则是，所有自由文本输入均由对话式商务 API 处理，而对以 chip 形式显示的建议答案的点击则由对话式商品过滤处理。

发送用户查询

用户输入示例：帮我策划一场派对

如需同时启用对话式商务代理和对话式产品过滤，请确保您的 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 您的系统可以处理对话式商品过滤，从而使 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. 继续对话流程，提示 Gemini 提供更多细节。

活动代码和分析

当用户继续对话时：

  • 检索 conversation_id。确保上一个 ConversationalSearchResponse 中的 conversation_id 已传递到当前 ConversationalSearchRequest 中。
  • 标记用户事件。如果对话式回答导致了新的搜索查询（例如，由于用户点击了 refined_search 建议或您的系统发出了并行搜索调用），请使用相同的 conversation_id 标记后续的搜索用户事件 (UserEvent)。这有助于跟踪多轮对话历程。

改用对话式产品过滤

随着对话变得更加具体，系统可能会将 intent 分类为 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 事件），该 UserEvent 带有相同的 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"
  }
}

对话式商务 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 进行标记，以便准确跟踪过滤历程及其对转化的影响。

参考架构

这是 Google Cloud上 Vertex AI Search for Commerce 的参考架构设计。此参考架构描绘了对话式商务代理的数据和服务流。该图显示了用户事件、商品目录数据和运营日志如何处理、转换并集成到生成式 AI 索引和 Retail Adapter 服务中，以处理搜索操作并实现用户意图，从而返回搜索结果。该架构连接了各种项目，可实现全面的 AI 赋能型商业搜索功能。

Commerce AI 参考架构

后续步骤

如需其他支持资源，请参阅有关对话功能的问题解答。