Membangun agen untuk memperkaya metadata Anda

Knowledge Catalog (sebelumnya dikenal sebagai Dataplex Universal Catalog) mengelola metadata untuk aset data di seluruh organisasi. Metadata ini memberikan konteks yang digunakan agen untuk menemukan, memahami, dan membuat kueri data yang diperlukan untuk menjawab pertanyaan pengguna.

Meskipun Knowledge Catalog mengelola resource secara otomatis, melacak skema teknis, serta membuat deskripsi dan profil data, konteks bisnis yang berharga sering kali berada di lokasi lain, seperti:

  • Dokumen dan wiki internal
  • Repositori kode
  • Saluran komunikasi seperti Google Chat dan Slack

Anda dapat membuat agen AI untuk mengekstrak konteks dari sumber ini dan terus memperkaya metadata Anda dalam skala besar. Tutorial ini menggunakan kode contoh dari repositori knowledge-catalog untuk menunjukkan cara membuat agen yang melakukan hal berikut:

  • Mengekstrak konteks: Mengekstrak konteks bisnis dari pusat informasi, dokumen, kode, atau chat untuk memperkaya metadata teknis.
  • Membuat dokumentasi: Membuat dokumentasi untuk tabel BigQuery berdasarkan konteks yang diekstrak dan sumber informasi lainnya.
  • Meningkatkan penelusuran dan penemuan: Memublikasikan dokumentasi yang dibuat ke Knowledge Catalog, sehingga entri lebih mudah ditemukan dan dipahami melalui penelusuran.

Sebelum memulai

Untuk menjalankan agen pengayaan Knowledge Catalog, Anda harus memenuhi persyaratan berikut:

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menggunakan agen pengayaan, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda: Google Cloud iam.gserviceaccount.com

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 pengayaan. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan agen pengayaan:

  • bigquery.projects.get/createDatasets
  • dataplex.projects.search
  • dataplex.entryGroups.get/updateEntries
  • 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 pengayaan Knowledge Catalog, aktifkan API berikut di project Anda:

  • BigQuery API
  • Knowledge Catalog API
  • Vertex AI API
  • Service Usage API

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Aktifkan API

Menginstal dependensi

Anda memerlukan paket dan alat Python berikut untuk menjalankan contoh:

  • google-adk (Agent Development Kit (ADK))
  • google-cloud-dataplex Knowledge Catalog Python Client
  • google-auth mengelola Kredensial Default Aplikasi
  • mcp[cli] untuk membuat server MCP contoh
  • gcloud untuk autentikasi dan konfigurasi. Untuk menginstal Google Cloud CLI, lihat dokumentasi Google Cloud SDK.

Menyiapkan lingkungan

  1. Konfigurasi gcloud dan login:

    gcloud auth application-default login
gcloud config set core/project PROJECT_ID

    Ganti kode berikut:

    • PROJECT_ID dengan ID project Anda

  2. Buat clone repositori knowledge-catalog dan buka direktori sumber contoh:

    git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/src

  3. Untuk menginstal dependensi, gunakan skrip yang disediakan yang menyiapkan lingkungan virtual Python dan variabel lingkungan yang diperlukan:

    source env.sh --install

  4. Untuk membuat set data BigQuery contoh bernama kc_sample_analytics di region us project cloud Anda, jalankan skrip create_data.py:

    python3 ../sample/data/create_data.py

    Contoh ini juga menyertakan sejumlah dokumen di direktori sample/docs. Dokumen ini membentuk pusat informasi lokal. Agen pengayaan menggunakan pusat informasi ini untuk mengekstrak informasi dan membuat dokumentasi.

Download metadata

Mulai dengan menjalankan alat download untuk mengekstrak snapshot metadata dari Knowledge Catalog untuk set data BigQuery dan tabelnya. Tindakan ini akan membuat artefak metadata lokal.

Argumen --dir menentukan direktori tempat file metadata ditulis.

python3 -m enrichment.download \
  --dir ../sample/metadata.initial \
  --dataset ${KC_ENRICH_SAMPLE_PROJECT}.kc_sample_analytics

Skrip ini membuat satu file Markdown per tabel di direktori sample/metadata menggunakan konvensi penamaan berikut: <project_id>.<dataset_id>.<table_id>.md.

Memperkaya metadata

Setelah membuat file Markdown lokal, jalankan agen pengayaan. Agen akan melakukan iterasi pada setiap file, menemukan informasi yang relevan dengan tabel, dan meringkas temuan beserta kutipan untuk membuat file Markdown yang diperbarui.

  • --dir: Menentukan direktori yang berisi file metadata lokal.
  • --output-dir: Menentukan direktori target untuk file metadata yang diperbarui.
  • --config-dir: Menentukan direktori yang berisi petunjuk agen, alat MCP, dan kemampuan.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Meninjau metadata

File metadata yang diperkaya berisi dokumentasi yang dibuat agen. Tinjau dan ubah file sesuai kebutuhan sebelum memublikasikan perubahan ke Knowledge Catalog.

git diff --no-index ../sample/metadata.initial ../sample/metadata.new

Memublikasikan metadata

Jalankan alat publikasi untuk men-deploy metadata yang diperkaya ke Knowledge Catalog.

python3 -m src.enrichment.publish --dir ../sample/metadata.new

Menyesuaikan untuk data Anda

Pada langkah sebelumnya, Anda menggunakan argumen --config-dir untuk mengarahkan agen ke direktori ../sample/config untuk konfigurasinya. Dengan cara ini, agen mengetahui tempat menemukan informasi dan cara berinteraksi dengan berbagai sumber.

Contoh ini dilengkapi dengan konfigurasi default yang menginstruksikan agen untuk menggunakan server MCP lokal guna mengakses file di pusat informasi lokal (sample/docs). Untuk menerapkan alur kerja ini di lingkungan Anda, Anda dapat menyesuaikan file konfigurasi ini untuk menghubungkan agen ke wiki internal, repositori kode, Google Drive, atau sistem lainnya.

Direktori sample/config/ berisi file berikut:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • instructions.md: Menambahkan petunjuk dasar agen dengan detail yang relevan dengan organisasi Anda, seperti memberi tahu agen untuk menelusuri pusat informasi tertentu.
  • mcp.json: Mengonfigurasi server MCP yang dapat digunakan agen untuk mengakses alat bagi sumber informasi Anda, seperti alat untuk membaca file dari direktori lokal.
  • SKILL.md: Menjelaskan cara agen harus menggunakan alat tertentu untuk berinteraksi dengan sumber informasi, seperti menggunakan list_contents, read_file, dan search_content untuk menemukan informasi dalam dokumen lokal.

Mempelajari kode Knowledge Catalog contoh

Alat download dan publish di bagian alur pengayaan menggunakan Knowledge Catalog API untuk membaca dan menulis metadata.

Bagian ini membahas cara kerja API ini sehingga Anda dapat mengadaptasi contoh untuk integrasi Anda sendiri.

Menelusuri dan mengambil metadata

Contoh ini menggunakan API berikut untuk menelusuri dan mengambil metadata:

  • SearchEntries untuk mengambil metadata entri dan metadata lokasi untuk set data.
  • ListEntries untuk menghitung tabel BigQuery dalam Catalog EntryGroup.
  • GetEntry untuk mengambil metadata spesifik untuk setiap tabel BigQuery.

Kode berikut menunjukkan cara menelusuri set data untuk menemukan grup entrinya, mencantumkan semua tabel yang ada, dan mengambil metadata spesifiknya:

import google.cloud.dataplex_v1 as dataplex

BIGQUERY_TABLE_TYPE = "projects/dataplex-types/locations/global/entryTypes/bigquery-table"
OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"

catalog = dataplex.CatalogServiceClient()

dataset_reference = '...'   # project_id.dataset_id
project_id, dataset_id = dataset_reference.split('.')

# 1. Search for dataset to determine its location
search_response = catalog.search_entries(
    request=dataplex.SearchEntriesRequest(
        name=f"projects/{project_id}/locations/global",
        query=f"type=dataset name={dataset_id}",
        page_size=1
    )
)
dataset_entry = search_response.results[0].dataplex_entry
location_id = dataset_entry.entry_source.location

# 2. List resources in the underlying group
entry_group_name = f"projects/{project_id}/locations/{location_id}/entryGroups/@bigquery"
entry_filter = f'parent_entry="{dataset_entry.name}"'
list_response = catalog.list_entries(
    request=dataplex.ListEntriesRequest(
        parent=entry_group_name,
        entry_filter=entry_filter,
    )
)

# 3. Retrieve metadata for each table in the list
for table_entry in list_response.entries:
    entry = catalog.get_entry(
        request=dataplex.GetEntryRequest(
            name=table_entry.name,
            view="CUSTOM",
            aspect_types=[OVERVIEW_ASPECT_TYPE]
        )
    )

Mengupdate metadata tabel

Kode berikut menunjukkan cara memublikasikan dokumentasi yang dibuat ke aspek Ringkasan untuk tabel dan mengupdate metadatanya:

import google.cloud.dataplex_v1 as dataplex
import google.protobuf.field_mask_pb2 as field_mask_pb2
import google.protobuf.json_format as jsonpb

OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"
OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview"

catalog = dataplex.CatalogServiceClient()

table_reference = "..."    # project_id.dataset_id.table_id
project_id, dataset_id, table_id = table_reference.split('.')

entry_data = {
    "name": f"bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}",
    "aspects": {
        OVERVIEW_ASPECT_KEY: {
            "aspectType": OVERVIEW_ASPECT_TYPE,
            "data": {
                "content": "...", # content parsed from local markdown file
                "contentType": "MARKDOWN"
            }
        }
    }
}

entry = dataplex.Entry()
jsonpb.ParseDict(entry_data, entry._pb)

catalog.update_entry(
    request=dataplex.UpdateEntryRequest(
        entry=entry,
        update_mask=field_mask_pb2.FieldMask(paths=["aspects"]),
        aspect_keys=[OVERVIEW_ASPECT_KEY],
    )
)

Langkah berikutnya