使用代理式檢索功能串流顯示答案

本頁面將介紹代理程式檢索功能，並說明如何搭配 stream answers 方法使用這項功能。

關於代理檢索

搭配串流答案方法使用的代理程式檢索功能，可針對特定用途取得更出色的結果，例如為具有多個資料儲存區的應用程式啟用多重檢索，或為不同類別的查詢自訂答案生成程序。

使用代理程式擷取功能會增加應用程式的複雜度，但可進一步控管結果。

Agent Search 內含預先定義的代理程式，可供您自訂搜尋引擎的行為。與透過應用程式設定使用者介面或串流答案方法提供的自訂選項相比，這項功能可提供更多自訂選項，且無須代理程式擷取。

混合搜尋 (有/無代理檢索)

代理式檢索特別適合用於混合搜尋應用程式。如果沒有代理程式擷取功能，搜尋功能會使用單次擴散傳遞功能，一次查詢所有資料儲存庫。相較之下，代理式檢索可進行多階段搜尋。代理程式會依序規劃及執行搜尋作業，並為每個步驟選擇最佳工具。這項功能可以合併多個 Agent Search 資料儲存空間的結果，並使用 Google 搜尋和 Google 地圖等工具。

舉例來說，您有全球公司政策和區域辦公室詳細資料的個別資料儲存空間。使用者問：「我們東京辦公室的法規遵循規定為何？」：

  • 不使用代理功能擷取：同時查詢政策儲存庫和區域辦公室儲存庫，並使用完整查詢字串。這可能會傳回片段結果。

  • 使用代理式檢索：代理會規劃執行作業。系統會先從區域商店擷取東京辦公室的詳細資料，然後，根據該特定情境，在政策儲存庫中執行第二次目標搜尋。

    代理會將這些發現統整成單一、連貫且更準確的答案。

代理式擷取功能也支援對混合搜尋應用程式執行多輪搜尋查詢 (後續問題)。如果沒有代理程式擷取功能，多輪搜尋只能搭配單一資料儲存庫應用程式使用。如要在多個回合中保留對話脈絡，可以選擇將代理程式檢索與代理程式平台工作階段配對。

自訂查詢分類

answer 和streaming answer 方法提供兩種查詢分類類型：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 專案中啟用代理程式平台。

  2. 使用 Agent Engine REST API (或 Agent Development Kit) 建立 Agent Runtime 執行個體 (也稱為推論引擎)。這個執行個體會代管 streamAnswer 方法使用的工作階段。

    執行個體資源名稱的格式如下：

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. 將 roles/aiplatform.reasoningEngineServiceAgent 角色授予 Discovery Engine 服務帳戶，讓 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 模式應用程式。每個自訂意圖 (或框架) 都會聲明代理程式將查詢分類為意圖的條件，以及代理程式用來處理查詢的指令和工具。

  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：專案的 ID。 Google Cloud
    • 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：用於追蹤訪客的專屬 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 CloudSDK 可協助處理錯誤和驗證，並提供自動重試、分頁處理和長時間執行的作業管理等功能。

由於代理程式檢索功能位於允許清單中，因此您需要使用的 SDK 與一般可用的 Discovery Engine 用戶端程式庫不同。

如要取得 Discovery Engine SDK 預覽版，請按照下列步驟操作：

  1. 請與支援團隊聯絡，取得預覽版 SDK Google 雲端硬碟資料夾的存取權。

  2. 下載適用於你所用語言的套件。

API 變更

由於這項功能位於許可清單中，因此 串流回答方法頁面的 API 參考文件，不會顯示所有可用的欄位，以及使用串流回答方法進行代理功能檢索時所需的欄位。缺少欄位如下。

要求主體欄位

  • enableAgentInvocation (布林值) - 將 true 設為切換至代理程式處理，並使用現有的搜尋服務設定。如果您要使用自訂 AI 模式應用程式指定 answer_agent 服務設定，這個欄位為選填。

  • reasoningEngine (字串) - 裝載代理程式工作階段的 Agent Runtime 資源名稱，格式為 projects/*/locations/*/reasoningEngines/*。

回覆欄位

啟用代理式擷取功能後，每個生成的 Answer.Reference 都包含：

  • queries (重複字串) - 代理程式為產生參照而發出的查詢清單。

工作階段服務

Session 服務 REST API 不支援 create 或 update 方法。但支援其他方法：list、get 和 delete。

工作階段服務 RPC API 不支援對用於多輪對話的工作階段資源執行 Update 或 Create 作業。不過，這項服務支援其他服務：用於多輪對話的會話資源上的 List、Get 和 Delete 作業。