使用智能体检索功能流式传输答案

本页介绍了智能检索，并说明了如何将其与 stream answers 方法搭配使用。

智能体检索简介

与 stream answers 方法搭配使用的 agentic 检索可以在某些使用情形下获得更好的结果，例如，为具有多个数据存储区的应用启用多遍检索，或针对不同类别的查询自定义答案生成。

使用智能体检索会增加应用的复杂性，但作为回报，可让您更好地控制结果。

Agent Search 包含一个预定义的代理，您可以使用该代理自定义搜索引擎的行为。与通过应用“配置”界面或流式回答方法（不含智能体检索）相比，这种方法可实现更高的自定义程度。

使用和不使用代理式检索的混合搜索

Agentic 检索对于混合搜索应用尤为有用。如果不使用智能检索，搜索会使用单次扇出，一次性查询所有数据存储区。相比之下，智能体检索支持多轮搜索。代理会按顺序规划和执行搜索，并为每个步骤选择最佳工具。它可以合并来自多个 Agent Search 数据存储区的结果，并使用 Google 搜索和 Google 地图等工具。

例如，您有单独的数据存储区来存储全球公司政策和区域办事处详细信息。用户问：“我们东京办事处的合规性规则是什么？”：

  • 不使用 Agent Retrieval：同时使用完整查询字符串查询政策存储区和地区办事处存储区。这可能会返回不完整的结果。

  • 使用智能体检索：智能体规划执行。它首先从区域商店检索有关东京办事处的详细信息。然后，它会使用该特定上下文在政策存储区中执行第二次有针对性的搜索。

    智能体将这些发现结果整合为一个连贯且更准确的回答。

借助智能体检索，您还可以在混合搜索应用中执行多轮搜索查询（后续问题）。如果不使用智能体检索，多轮搜索仅适用于单数据存储区应用。如需在多轮对话中保持对话上下文，您可以选择将智能体检索与代理平台会话配对。

自定义查询分类

回答和流式回答方法提供两种查询分类类型：ADVERSARIAL_QUERY 和 NON_ANSWER_SEEKING_QUERY。

借助智能体检索，您可以定义其他分类类型，以匹配您的业务工作流。系统使用分类器来确定用户意图，并将请求路由到相应的代理配置。

例如，从查询中，您可以确定查询的意图是跟踪订单，并且您已指定 TRACK_ORDER 分类。系统不会在所有数据存储区中运行宽泛搜索，而是会加载一个专门的代理，该代理配备了检索配送状态所需的工具和数据。

启用和使用代理式检索的方法

您可以通过以下两种方式启用代理式检索：

  • 预定义的 Google 回答代理：如果您已在 Agent Search 中拥有搜索应用，则可以在向该应用发送查询时，通过在 API 请求中设置 enable_agent_invocation=true 来启用代理检索。在这种情况下，您将保留现有的搜索服务配置。

  • 自定义 AI 模式应用：创建 Agent Search 应用时，您需要定义另一种服务配置，即 default_agent_answer 服务配置。这也可以称为自定义 AI 模式引擎，因为在 Agent Search 中，“应用”和“引擎”可以互换使用。

准备工作

在使用代理检索之前，请执行以下操作：

为多轮会话设置推理引擎

如需在多轮对话中保持对话上下文，您需要在 Gemini Enterprise Agent Platform 上创建 Agent Runtime 引擎（也称为推理引擎）。

发出 streamAnswer 请求时，您需要将 Agent Runtime 资源的名称作为 streamAnswer 请求中的 reasoningEngine 字段进行传递。

  1. 在您的 Google Cloud 项目中启用Agent Platform。

  2. 使用 Agent Engine REST API（或智能体开发套件）创建 Agent Runtime 实例（也称为推理引擎）。该实例托管 streamAnswer 方法使用的会话。

    实例资源名称的格式为：

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. 向 Discovery Engine 服务账号授予 roles/aiplatform.reasoningEngineServiceAgent 角色，从而向 Discovery Engine 服务代理授予对推理引擎的访问权限：

    service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com

    其中，PROJECT_NUMBER 是托管推理引擎的项目的编号。此权限允许流式回答后端代表您创建、读取和向会话追加事件。

  4. 查看适用的配额。由 Agent Runtime 支持的会话会消耗 Agent Platform API 的配额。 相关配额如下：

    • aiplatform.googleapis.com/session_write_requests - 每分钟创建、删除或更新的 Agent Runtime 会话数。

    • aiplatform.googleapis.com/session_event_append_requests - 每分钟向 Agent Runtime 会话附加的事件数。

    如需了解详情，请参阅 Gemini Enterprise Agent Platform Agent Engine 配额。

  5. 记下 Agent Runtime 资源名称，因为您需要将其作为 streamAnswer 请求中的 reasoningEngine 字段进行传递。

可选：设置自定义 AI 模式应用

默认情况下，智能体检索使用预定义的 Google 回答智能体。此方法将查询分类为意图 DEFAULT_ANSWER_SEEKING 和 DO_NOT_ANSWER。如果您想自定义工具或添加对新类别的查询意图的支持，可以创建自定义 AI 模式应用。每个自定义 intent（或 frame）都会声明智能体将查询归类为相应 intent 的条件，以及智能体用于处理该 intent 的指令和工具。

  1. 通过 engines.create REST 方法和 engine_config.answer_agent 块创建引擎。

    配置结构如下：

    engine {
 name: "YOUR_AI_MODE_ENGINE"
 display_name: "YOUR_AI_MODE_ENGINE_DISPLAY_NAME"
 engine_config {
   answer_agent {
     frames {
       vertical_intent: "YOUR_CUSTOM_INTENT"
       vertical_intent_prompt {
         instructions: "Instructions for when to classify a user query as YOUR_CUSTOM_INTENT."
       }
       initial_prompt {
         instructions: "Instructions for the agent on how to process a user query classified as YOUR_CUSTOM_INTENT."
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_1"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 1."
         }
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_2"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 2."
         }
       }
     }
   }
 }
}
engine_id: "SAMPLE_MULTI_SEARCH_RETRIEVAL"

  2. 创建引擎后，通过其 default_agent_answer 服务配置来路由请求：

    projects/*/locations/*/collections/*/engines/YOUR_AI_MODE_ENGINE/servingConfigs/default_agent_answer

  3. 如需在设计或注册自定义 AI 模式应用方面获得帮助，请与支持团队联系。

使用智能体检索功能流式传输答案

以下命令展示了如何在启用代理检索的情况下调用 streaming answer 方法。与不使用智能检索的输出类似，此调用会以一系列 JSON 响应的形式流式传输生成的答案。

如果您已设置推理引擎，请在 reasoningEngine 字段中添加其资源名称，以便在对话轮次之间保持会话状态。

REST

如需搜索并获取包含流式生成的答案的结果，请执行以下操作：

  1. 运行以下 curl 命令：

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/SERVING_CONFIG_ID:streamAnswer" \
  -d '{
        "query": { "text": "QUERY" },
        "session": "SESSION",
        "enableAgentInvocation": true,
        "userPseudoId": "USER_PSEUDO_ID",
        "reasoningEngine": "projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID"
      }'

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的 ID。
    • APP_ID：您要查询的 Agent Search 应用的 ID。
    • SERVING_CONFIG_ID：如需使用自定义 AI 模式应用，请将此值设置为 default_agent_answer。 如需使用预定义的 Google 回答代理，请将此属性设置为 default_search。
    • PROJECT_NUMBER：托管推理引擎的项目的编号。
    • QUERY：包含问题或搜索查询的自由文本字符串。
    • SESSION：如果继续进行多轮对话，则这是上一轮对话的响应中返回的会话资源名称，例如 projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID。 如果不继续对话，请将此值设置为 -（连字符）。
    • USER_PSEUDO_ID：用于跟踪访问者的唯一标识符。
    • LOCATION_ID：推理引擎的位置，例如 us-central1。
    • REASONING_ENGINE_ID：您创建的 Agent Engine 实例的 ID。

Python

如需了解详情，请参阅 Agent Search Python API 参考文档。

如需向 Agent Search 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例使用 Discovery Engine Python 客户端 (v1alpha) 在启用代理调用的情况下调用 stream_answer_query。传递多轮会话的 reasoning_engine 字段。

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1alpha


def run_stream_answer_query():
    PROJECT_ID = "YOUR_PROJECT_ID"
    LOCATION = "global"  # or a specific region
    COLLECTION_ID = "default_collection"
    ENGINE_ID = "YOUR_ENGINE_ID"
    # Use "default_search" for the predefined Google answer agent, or
    # "default_agent_answer" if you have configured a custom AI_MODE app.
    SERVING_CONFIG_ID = "default_search"
    USER_ID = "user-id"
    QUERY_TEXT = "YOUR_QUERY_TEXT"
    REASONING_ENGINE_ID = "YOUR_REASONING_ENGINE_ID"
    # Use "-" to start a new session, or pass the sessionId returned in
    # the previous turn's response to continue an existing session.
    SESSION_ID = "-"

    SESSION_REF = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/sessions/{SESSION_ID}"
    )
    SERVING_CONFIG_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/servingConfigs/{SERVING_CONFIG_ID}"
    )
    REASONING_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/"
        f"reasoningEngines/{REASONING_ENGINE_ID}"
    )

    client_options = ClientOptions(
        api_endpoint="discoveryengine.googleapis.com"
    )

    client = discoveryengine_v1alpha.ConversationalSearchServiceClient(
        client_options=client_options
    )

    request = discoveryengine_v1alpha.AnswerQueryRequest(
        query=discoveryengine_v1alpha.Query(text=QUERY_TEXT),
        serving_config=SERVING_CONFIG_ENGINE,
        user_pseudo_id=USER_ID,
        enable_agent_invocation=True,
        session=SESSION_REF,
        reasoning_engine=REASONING_ENGINE,
    )

    print(f"Starting StreamAnswerQuery agentic session with: {request}")
    stream = client.stream_answer_query(request)

    try:
        for response in stream:
            print(f"Received response: {response}")
    except Exception as e:
        print(f"Error during streaming: {e}")


if __name__ == "__main__":
    run_stream_answer_query()

获取 Discovery Engine SDK 的预览版

借助 Discovery Engine SDK，您可以更轻松地从应用与 Google Cloud服务进行互动。该 SDK 可帮助进行错误处理和身份验证，并提供自动重试、分页处理和长时间运行的操作管理等功能。

由于代理检索功能位于许可名单中，因此您需要使用的 SDK 与正式发布的 Discovery Engine 客户端库不同。

如需获取 Discovery Engine SDK 的预览版，请执行以下操作：

  1. 请与支持团队联系，以获取对预览版 SDK Google 云端硬盘文件夹的访问权限。

  2. 下载相应语言的软件包。

API 变更

由于此功能位于许可名单中，因此 streaming answer 方法页面上的 API 参考文档并未显示所有可用的字段，而这些字段是使用流式回答方法进行代理检索所必需的。缺失字段的说明如下。

请求正文字段

  • enableAgentInvocation（布尔值）- 设置为 true 可切换到使用现有搜索服务配置的智能体处理。如果您要指定具有自定义 AI 模式应用的 answer_agent 服务配置，则此字段为可选字段。

  • reasoningEngine（字符串）- 托管代理会话的 Agent Runtime 的资源名称，格式为 projects/*/locations/*/reasoningEngines/*。

响应字段

启用代理检索后，每个生成的 Answer.Reference 都包含：

  • queries（重复的字符串）- 代理为了生成参考而发出的查询列表。

会话服务

会话服务 REST API 不支持 create 或 update 方法。不过，它支持其他方法：list、get 和 delete。

会话服务 RPC API 不支持对用于多轮对话的会话资源执行 Update 或 Create 操作。不过，它确实支持其他服务：对用于多轮对话的会话资源执行 List、Get 和 Delete 操作。