构建代理以发现数据

Knowledge Catalog 发现智能体是一款 AI 赋能的助理，可基于 Knowledge Catalog 搜索功能，提高复杂自然语言查询的搜索相关性。通过优化查询理解和制定，它可提供比标准 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 Viewer (roles/dataplex.viewer)
• Vertex AI User (roles/aiplatform.user)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含使用发现代理所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

使用发现代理需要以下权限：

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

您也可以使用自定义角色或其他预定义角色来获取这些权限。

启用 API

如需使用知识目录发现代理，请在项目中启用以下 API：Knowledge Catalog API、Vertex AI API 和 Service Usage API。

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin 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（智能体开发套件）
   • 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。

后续步骤

• 了解知识目录的搜索语法。
• 详细了解智能体开发套件。