Membangun agen untuk menemukan data Anda

Agen penemuan Katalog Pengetahuan adalah asisten yang didukung AI yang meningkatkan relevansi penelusuran untuk kueri natural language yang kompleks berdasarkan kemampuan penelusuran Katalog Pengetahuan. Dengan mengoptimalkan pemahaman dan perumusan kueri, API ini memberikan hasil yang lebih akurat daripada Knowledge Catalog Search API standar. Kemampuan ini sangat penting, terutama untuk kueri yang kompleks atau panjang.

Kasus penggunaan

Agen penemuan memberikan pengalaman percakapan yang kaya untuk skenario seperti:

  • Inten dan batasan yang kompleks atau gabungan: Menangani permintaan penelusuran dengan beberapa kriteria, seperti menemukan set data di us-central1 tetapi mengecualikan resource di BigQuery.
  • Penelusuran berorientasi bisnis: Menemukan aset data berdasarkan maksud dan konteks bisnis, bukan mencocokkan istilah teknis yang persis.
  • Eksplorasi bolak-balik: Memperbaiki penelusuran Anda melalui dialog percakapan untuk mempersempit hasil.

Agen penemuan dibangun di atas penelusuran semantik Katalog Pengetahuan yang menyediakan penelusuran campuran siap pakai. Anda dapat terus menggunakan penelusuran semantik Knowledge Catalog secara langsung saat perlu memproses penelusuran dengan niat tinggi (saat Anda mengetahui resource atau kolom tertentu), persyaratan latensi rendah, atau penelusuran hibrida tanpa penyiapan.

Cara kerjanya

Agen penemuan melakukan langkah-langkah berikut untuk merespons kueri penelusuran:

  1. Menganalisis input untuk memahami maksud kueri, membuat beberapa variasi penelusuran, dan memetakan istilah ke filter metadata.
  2. Menelusuri resource menggunakan penelusuran semantik Knowledge Catalog.
  3. Menentukan peringkat hasil gabungan berdasarkan relevansi.

Diagram berikut memberikan detail prosesnya:

Proses agen penemuan untuk permintaan penelusuran.
Jalur pemrosesan untuk permintaan penelusuran di agen penemuan.

Agen mengandalkan Knowledge Catalog Search API untuk mengambil Google Cloud resource yang relevan. Cuplikan kode berikut menunjukkan cara agen memanggil penelusuran semantik 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}

Sebelum memulai

Untuk menjalankan agen penemuan Knowledge Catalog, pastikan Anda memenuhi persyaratan berikut:

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan agen penemuan, minta administrator untuk memberi Anda peran IAM berikut di Google Cloud project iam.gserviceaccount.comAnda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menggunakan agen penemuan. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan agen penemuan:

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

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mengaktifkan API

Untuk menggunakan agen penemuan Knowledge Catalog, aktifkan API berikut di project Anda: Knowledge Catalog API, Vertex AI API, dan Service Usage API.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Aktifkan API

Menyiapkan lingkungan

Untuk menyiapkan lingkungan pengembangan agen penemuan, lakukan hal berikut:

  1. Buat clone repositori dataplex-labs.

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

  2. Ubah ke direktori agen:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Buat dan aktifkan Lingkungan Virtual Python, lalu instal dependensi yang tercantum dalam file requirements.txt:

    • google-adk (Agent Development Kit)
    • google-cloud-dataplex (Klien Python Knowledge Catalog)
    • google-api-core
      python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Siapkan variabel lingkungan dengan perintah berikut:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Ganti kode berikut:

    • PROJECT_ID dengan ID project Anda

Menjalankan agen penemuan sebagai agen root

Untuk menjalankan agen penemuan secara langsung sebagai agen root, lakukan hal berikut:

  1. Di file agent.py yang ada di folder knowledge_catalog_discovery_agent, ganti nama variabel discovery_agent menjadi root_agent.

  2. Jalankan agen menggunakan perintah adk run:

    adk run path/to/agent/parent/folder

    Ganti kode berikut:

    • path/to/agent/parent/folder dengan direktori induk yang berisi folder dengan agen Anda. Misalnya, jika agen Anda berada di knowledge_catalog_discovery_agent/, jalankan adk run dari direktori agents/.

Menjalankan agen penemuan sebagai sub-agen

Untuk mengintegrasikan agen penemuan ke dalam agen kustom yang lebih besar, seperti my_custom_agent, lakukan hal berikut:

  1. Siapkan struktur project Anda untuk memuat modul agen penemuan:

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

  2. Dalam file agent.py agen kustom Anda, impor agen penemuan dan gunakan sebagai alat agen. Lihat contoh:

    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. Jalankan agen menggunakan perintah adk run:

    adk run path/to/agent/parent/folder

    Ganti kode berikut:

    • path/to/agent/parent/folder dengan direktori induk yang berisi folder my_custom_agent/ Anda. Misalnya, jika agen Anda berada di agents/my_custom_agent/, jalankan adk run dari direktori agents/.

Langkah berikutnya