Membangun agen untuk memperkaya metadata Anda

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

Meskipun Knowledge Catalog otomatis mengelola resource, 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 membangun 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 membangun 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 dihasilkan 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 Anda perlukan untuk menggunakan agen pengayaan, 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 yang telah ditetapkan 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
  • Dataplex 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 Klien Python Knowledge Catalog
  • google-auth mengelola Kredensial Default Aplikasi
  • mcp[cli] untuk membangun contoh server MCP
  • 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 dalam direktori sample/docs. Dokumen ini membentuk pusat informasi lokal. Agen pengayaan menggunakan pusat informasi ini untuk mengekstrak informasi dan membuat dokumentasi.

Download metadata

Mulailah 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 menghasilkan 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 keahlian.
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 dihasilkan 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 tahu tempat untuk 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 untuk 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 contoh kode Knowledge Catalog

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 menyesuaikan 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 EntryGroup Katalog.
  • 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 dihasilkan ke aspek Ringkasan untuk tabel dan memperbarui 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