Membangun agen untuk memperkaya metadata Anda

Knowledge Catalog (sebelumnya 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, melacak skema teknis, serta membuat deskripsi dan profil data secara otomatis, 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 dataplex-labs 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.
  • Buat dokumentasi: Membuat dokumentasi untuk tabel BigQuery berdasarkan konteks yang diekstrak dan sumber informasi lainnya.
  • Meningkatkan penelusuran dan penemuan: Memublikasikan dokumentasi yang dihasilkan ke Katalog Pengetahuan, sehingga entri lebih mudah ditemukan dan dipahami melalui penelusuran.

Sebelum memulai

Untuk menjalankan agen penambahan informasi Katalog Pengetahuan, 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 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 peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. 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 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 dataplex-labs dan buka direktori sumber contoh:

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/knowledge_catalog_enrichment_agent/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 sampel 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

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 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 keahlian.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

Meninjau metadata

File metadata yang telah dipertkaya berisi dokumentasi yang dihasilkan agen. Tinjau dan ubah file sesuai kebutuhan sebelum memublikasikan perubahan ke Katalog Pengetahuan.

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

Memublikasikan metadata

Jalankan alat publikasi untuk men-deploy metadata yang telah di-enrich 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 basis pengetahuan 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: Melengkapi petunjuk dasar agen dengan detail yang relevan dengan organisasi Anda, seperti memintanya 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 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 lokasi untuk set data.
  • ListEntries untuk mencantumkan tabel BigQuery dalam EntryGroup Katalog.
  • GetEntry untuk mengambil metadata tertentu untuk setiap tabel BigQuery.

Kode berikut menunjukkan cara menelusuri set data untuk menemukan grup entri, mencantumkan semua tabel yang ada di dalamnya, 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