建構代理程式來探索資料

Knowledge Catalog 探索代理是 AI 輔助助理，可根據 Knowledge Catalog 搜尋功能，提升複雜自然語言查詢的搜尋關聯性。這項 API 會盡量瞭解及擬定查詢，因此提供的結果比標準 Knowledge Catalog 搜尋 API 更準確。這項功能對於複雜或冗長的查詢特別重要。

用途

探索代理程式可為下列情境提供豐富的對話體驗：

• 複雜或合併的意圖和限制：處理具有多項條件的搜尋要求，例如在 us-central1 中尋找資料集，但排除 BigQuery 中的資源。
• 以業務為導向的搜尋：根據意圖和業務情境探索資料資產，而非比對確切的技術用語。
• 多輪探索：透過對話式對談縮小搜尋範圍，找出更精確的結果。

探索代理是以 Knowledge Catalog 語意搜尋為基礎建構，可提供開箱即用的混合搜尋功能。如需處理高意願搜尋 (您知道特定資源或資料欄)、低延遲需求或零設定混合搜尋，可以繼續直接使用 Knowledge Catalog 語意搜尋。

運作方式

探索代理程式會執行下列步驟，回覆搜尋查詢：

1. 分析輸入內容的意圖，瞭解查詢內容、產生多種搜尋變化版本，並將字詞對應至中繼資料篩選器。
2. 使用 Knowledge Catalog 語意搜尋功能搜尋資源。
3. 根據關聯性排序合併結果。

下圖詳細說明瞭這個程序：

探索代理程式中搜尋要求的處理路徑。

代理程式會依據 Knowledge Catalog Search API 擷取相關 Google Cloud 資源。下列程式碼片段顯示代理程式如何呼叫 Knowledge Catalog 語意搜尋：

      # Configure the request parameters for the
      # call to Knowledge Catalog Semantic Search API.
      endpoint = "dataplex.googleapis.com"

      client = dataplex_v1.CatalogServiceClient(
          client_options={"api_endpoint": endpoint}
      )

      location = "global"
      consumer_project_id = "my-gcp-project"
      parent_name = f"projects/{consumer_project_id}/locations/{location}"

      # Call Knowledge Catalog Semantic Search API.
      response = client.search_entries(
          request={
              "name": parent_name,
              "query": query,
              "page_size": 50,
              "semantic_search": True,
          }
      )

      # Extract useful metadata to share with the agent.
      entries = [
          {
              "entry_name": result.dataplex_entry.name,
              "system": result.dataplex_entry.entry_source.system,
              "resource_id": result.dataplex_entry.entry_source.resource,
              "display_name": result.dataplex_entry.entry_source.display_name,
          }
          for result in response.results
      ]

      return {"results": entries}

事前準備

如要執行 Knowledge Catalog 探索代理程式，請確認您符合下列條件：

必要的角色

如要取得使用探索代理程式所需的權限，請要求管理員在 Google Cloud 專案 iam.gserviceaccount.com中授予您下列 IAM 角色：

• Dataplex 檢視器 (roles/dataplex.viewer)
• Vertex AI 使用者 (roles/aiplatform.user)
• 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備使用探索代理程式所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要使用探索代理程式，必須具備下列權限：

• dataplex.projects.search
• aiplatform.endpoints.predict
• serviceusage.services.use

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

啟用 API

如要使用 Knowledge Catalog 探索代理程式，請在專案中啟用下列 API： Knowledge Catalog API、Vertex AI API 和 Service Usage API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

設定環境

如要設定探索代理程式的開發環境，請按照下列步驟操作：

1. 複製 dataplex-labs 存放區。

   git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
   

2. 切換至代理程式目錄：

   cd dataplex-labs/knowledge_catalog_discovery_agent
   

3. 建立並啟用 Python 虛擬環境，然後安裝 requirements.txt 檔案中列出的依附元件：

   • google-adk (Agent Development Kit)
   • google-cloud-dataplex (Knowledge Catalog Python 用戶端)
   • google-api-core

     python3 -m venv /tmp/kcsearch
   
     source /tmp/kcsearch/bin/activate
   
     pip3 install -r requirements.txt
   

4. 使用下列指令設定環境變數：

   
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_GENAI_USE_VERTEXAI=True
   

   更改下列內容：

   • 將 PROJECT_ID 替換為專案的 ID

以根代理身分執行探索代理

如要直接以根代理程式身分執行探索代理程式，請按照下列步驟操作：

1. 在 knowledge_catalog_discovery_agent 資料夾中的 agent.py 檔案中，將 discovery_agent 變數重新命名為 root_agent。

2. 使用 adk run 指令執行代理程式：

   adk run path/to/agent/parent/folder
   

   更改下列內容：

   • path/to/agent/parent/folder，其中包含代理程式所在的資料夾。舉例來說，如果您的代理程式位於 knowledge_catalog_discovery_agent/，請從 agents/ 目錄執行 adk run。

以子代理身分執行探索代理

如要將探索代理程式整合至較大的自訂代理程式 (例如 my_custom_agent)，請按照下列步驟操作：

1. 設定專案結構，內含探索代理程式模組：

   my_custom_agent/
   ├── agent.py
   └── knowledge_catalog_discovery_agent/
       ├── SKILL.md
       ├── agent.py
       ├── tools.py
       └── utils.py
   

2. 在自訂代理程式的 agent.py 檔案中，匯入探索代理程式並做為代理程式工具使用。請參閱以下範例：

   root_agent = llm_agent.Agent(
       model=google_llm.Gemini(model=GEMINI_MODEL),
       name="my_custom_agent",
       instruction=(
           "You are a Custom Agent. Your goal is to help users understand"
           " their data landscape, evaluate data assets, and derive insights"
           " from available resources. **IMPORTANT**: You should use the"
           " `knowledge_catalog_discovery_agent` to search for and discover"
           " data assets. For best results, pass in the Natural Language user'"
           " query as is to the `knowledge_catalog_discovery_agent`. Once assets"
           " are found, you should analyze their metadata, compare them, and"
           " provide recommendations or summaries to the user to help them make"
           " decisions. Focus on general metadata summary and comparison."
       ),
       tools=[
           agent_tool.AgentTool(discovery_agent),
       ],
   )
   

3. 使用 adk run 指令執行代理程式：

   adk run path/to/agent/parent/folder
   

   更改下列內容：

   • path/to/agent/parent/folder，其中包含 my_custom_agent/ 資料夾的上層目錄。舉例來說，如果您的代理程式位於 agents/my_custom_agent/，請從 agents/ 目錄執行 adk run。

後續步驟

• 瞭解 Knowledge Catalog 的搜尋語法。
• 進一步瞭解 Agent Development Kit。