Membangun fondasi data dengan metadata Knowledge Catalog

1. Pengantar

Model AI generatif adalah penganalisis yang andal, tetapi tidak memiliki konteks institusional. Jika seorang eksekutif bertanya kepada agen AI, "Berapa pendapatan Q1 kita?", agen tersebut mungkin menemukan lusinan tabel bernama "pendapatan" di seluruh data lake Anda. Beberapa di antaranya adalah laporan keuangan yang ketat, yang lain adalah perkiraan pemasaran real-time, dan banyak yang kemungkinan merupakan sandbox yang tidak digunakan lagi.

Tanpa perujukan eksplisit, agen AI akan memilih tabel berdasarkan kesamaan nama sederhana, sehingga menghasilkan jawaban "salah yang meyakinkan" yang berasal dari data yang tidak terverifikasi.

Codelab ini adalah bagian dari seri dua bagian yang menjelaskan cara membangun agen AI yang memahami tata kelola.

Di bagian pertama ini, Anda akan membangun fondasi data. Anda akan menyiapkan data lake "berantakan" yang realistis di BigQuery, menerapkan tag metadata yang ketat (aspek Knowledge Catalog) untuk membedakan data yang valid dari noise, dan menggunakan CLI Antigravity (AGY) untuk menguji secara lokal apakah agen mematuhi aturan tata kelola data Anda dengan ketat.

Anda dapat membaca bagian kedua dari seri ini, yang membahas cara men-deploy prototipe agen lokal ke dalam aplikasi web tingkat perusahaan yang aman menggunakan Model Context Protocol (MCP) dan Cloud Run. 👉 Baca Bagian 2

Yang akan Anda pelajari

• Deploy data lake multi-tingkat yang realistis menggunakan skrip penyiapan.
• Desain dan daftarkan template metadata kustom (jenis aspek) di Knowledge Catalog untuk membedakan produk data resmi dari tabel sandbox mentah.
• Verifikasi aturan tata kelola data secara lokal menggunakan AGY CLI sebelum menulis kode aplikasi apa pun.

Yang Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan.
• Akses ke Google Cloud Shell (AGY CLI sudah terinstal di Cloud Shell).
• Pemahaman dasar dan keakraban dengan BigQuery dan Knowledge Catalog.

Konsep utama

• Knowledge Catalog: Layanan pengelolaan metadata terpadu. Kami menggunakannya untuk memperkaya metadata teknis (skema) dengan konteks bisnis (tata kelola).
• Jenis Aspek: Template metadata terstruktur. Tidak seperti tag teks bebas, Aspek menerapkan pengetikan yang kuat (enum, boolean), sehingga dapat diandalkan untuk dievaluasi oleh mesin.

2. Penyiapan dan persyaratan

Mulai Cloud Shell

Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.

Dari Google Cloud Console, klik ikon Cloud Shell di toolbar kanan atas:

Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:

Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.

Lakukan inisialisasi lingkungan

Buka Cloud Shell dan tetapkan variabel project Anda untuk memastikan semua perintah menargetkan infrastruktur yang benar.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Mengaktifkan API

Aktifkan layanan Google Cloud yang diperlukan untuk menjalankan petunjuk berikut.

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

Melakukan cloning repositori

Dapatkan kode infrastruktur dan skrip otomatisasi dari repositori GitHub. Untuk menghemat ruang disk di Cloud Shell, kita hanya akan mendownload folder tertentu yang diperlukan untuk lab ini.

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

Membangun data lake "berantakan"

Lingkungan data dunia nyata jarang sekali bersih. Untuk menyimulasikan kenyataan, kita memerlukan gabungan data mart "resmi" dan tabel "sandbox" yang tidak tepercaya.

Kita akan menggunakan skrip penyiapan untuk men-deploy set data dan tabel BigQuery.

1. Jadikan skrip penyiapan sebagai file yang dapat dieksekusi dan jalankan. Tindakan ini akan membuat tiga set data BigQuery (finance_mart, marketing_prod, analyst_sandbox) dan mengisi tabelnya dengan data contoh.

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Checkpoint: Sekarang Anda memiliki data lake yang terisi sepenuhnya, tetapi tidak diatur sama sekali. Bagi AI, setiap tabel terlihat sama persis.

3. Membuat template tata kelola data (jenis aspek)

Sekarang, kita akan menentukan beberapa aturan tata kelola data. Di Knowledge Catalog, hal ini dilakukan dengan membuat jenis aspek, yang merupakan template metadata yang dapat digunakan kembali dan memiliki jenis yang kuat.

Kita akan mendaftarkan template ini menggunakan CLI gcloud sehingga Anda dapat melihat cara template ini ditentukan.

Periksa skema aspek

Outputkan isi aspect_template.json untuk melihat definisi skema.

cat aspect_template.json

Struktur JSON berikut akan ditampilkan:

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      ...
    }
  ]
}

Perhatikan bagaimana skema ini menerapkan jenis data yang ketat, seperti enum untuk tingkat kekritisan (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) dan bool untuk is_certified. Hal ini memastikan metadata tetap terstruktur dan dapat dibaca oleh mesin.

Mendaftarkan jenis aspek

Jalankan perintah gcloud berikut untuk mendaftarkan template ini di registry Knowledge Catalog Anda.

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

4. Menerapkan tata kelola

Ini adalah langkah engineering yang penting. Saat ini, tabel finance_mart.fin_monthly_closing_internal dan analyst_sandbox.tmp_data_dump_v2_final_real terlihat identik bagi LLM. Objek ini hanyalah objek dengan kolom.

Sebagai engineer tata kelola, Anda harus melampirkan aspek (label metadata bersertifikasi) ke tabel ini untuk membedakannya. Di perusahaan yang sebenarnya, Anda akan mengotomatiskan hal ini melalui pipeline CI/CD. Kita akan menyimulasikan otomatisasi tersebut dengan skrip.

Membuat payload tata kelola

Kunci aspek Knowledge Catalog harus unik secara global (diawali dengan project ID Anda). Skrip ./generate_payloads.sh akan membuat file metadata YAML secara dinamis.

chmod +x ./generate_payloads.sh
./generate_payloads.sh

Output:

Tindakan ini akan membuat folder "./aspect_payloads" yang berisi 4 file YAML, yang menentukan skenario tata kelola (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Menerapkan aspek dengan CLI

Sebelum menjalankan skrip, mari kita lihat apa yang sebenarnya kita terapkan untuk menyederhanakan prosesnya. Jalankan perintah berikut untuk melihat struktur payload keuangan internal:

cat aspect_payloads/fin_internal.yaml

Anda akan melihat konten berikut.

your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

Perhatikan cara YAML ini secara eksplisit menentukan konteks bisnis, seperti menyetel tanda is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Memberi LLM aturan yang jelas dan terstruktur untuk dievaluasi, bukan hanya menebak berdasarkan nama tabel.

Sekarang, jalankan skrip aplikasi. Proses ini melakukan iterasi melalui tabel BigQuery dan menjalankan perintah gcloud dataplex entries update untuk melampirkan metadata tetap ini.

chmod +x ./apply_governance.sh
./apply_governance.sh

Verifikasi (opsional)

Sebelum melanjutkan, pastikan metadata diterapkan dengan benar di konsol.

1. Buka halaman Knowledge Catalog di Konsol Google Cloud. Jika Anda tidak melihat "Knowledge Catalog" di menu navigasi sebelah kiri, gunakan kolom Search di bagian atas jendela Konsol Google Cloud, ketik "Knowledge Catalog", lalu pilih hasilnya di bagian "Top results" atau "Products & Pages".
2. Telusuri fin_monthly_closing_internal. Anda akan melihat tabel BigQuery yang tercantum dalam hasil. Klik nama tabel untuk membuka halaman detailnya.

3. Di halaman detail tabel, cari bagian "Tag dan aspek opsional" yang berada di bagian bawah.
4. Anda akan menemukan aspek official-data-product-spec. Konfirmasi bahwa nilai cocok dengan skenario "Gold Internal" yang kami terapkan.

Sekarang Anda telah mengonfirmasi bahwa tabel BigQuery yang identik secara teknis (fin_monthly_closing_internal dan tmp_data_dump_v2_final_real) dibedakan secara logis oleh metadata yang dapat dibaca mesin.

5. Mengonfigurasi dan membuat prototipe agen

Sebelum membuat aplikasi (yang akan kita lakukan di Bagian 2), kita akan memverifikasi logika tata kelola data secara lokal. Kita perlu menginstal plugin Knowledge Catalog dan mengonfigurasi Agent Skill.

Menginstal ekstensi

Di Cloud Shell, instal plugin Knowledge Catalog. Anda akan diminta untuk mengonfirmasi dan memberikan detail penyiapan.

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

Memeriksa kemampuan agen

Keahlian agen adalah file definisi statis yang dapat digunakan kembali dan terletak di .agents/skills/knowledge_catalog_governance/SKILL.md. File ini berisi logika yang menerjemahkan aturan abstrak manusia (misalnya, "Saya memerlukan data yang aman") menjadi pencarian teknis yang ketat.

Periksa file untuk memahami algoritma yang kita ajarkan kepada AI:

cat .agents/skills/knowledge_catalog_governance/SKILL.md

Perhatikan bahwa perintah ini secara eksplisit menginstruksikan model untuk mengikuti loop ketat Fase 1 (Verifikasi Metadata) dan Fase 2 (Eksekusi Kueri). Model harus menemukan dan memverifikasi metadata sebelum menyusun SQL apa pun.

Mulai agen dan uji skenario

Mulai sesi CLI AGY. Keterampilan akan otomatis ditemukan dan dimuat dari direktori .agents/skills.

agy

Catatan: Anda mungkin melihat beberapa file konteks dimuat. Hal ini wajar. CLI memuat skill lokal untuk aturan spesifik project ini, ditambah petunjuk default untuk plugin Knowledge Catalog itu sendiri.

Verifikasi penginstalan

Ketik /mcp untuk mengonfirmasi bahwa plugin Knowledge Catalog aktif. Anda akan melihat knowledge-catalog tercantum sebagai plugin aktif dengan alat yang tersedia.

/mcp

Output yang diharapkan:

MCP Servers
...
>  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Skenario pengujian (pembuatan prototipe)

Tempelkan perintah berikut ke sesi agen yang sedang berjalan satu per satu untuk memverifikasi bahwa agen mematuhi aturan Anda.

💡 Tips: Jika diminta, pilih "2. Ya, dan selalu izinkan 'knowledge-catalog/search_entries' dalam percakapan ini' untuk mengaktifkan pengujian yang lancar.

• Skenario A (mensertifikasi data CFO):

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

Harapan: Agen secara otomatis menemukan project dan region aktif Anda dari alatnya, mengkueri fin_monthly_closing_internal karena secara semantik cocok dengan GOLD_CRITICAL (akurat) dan INTERNAL_ONLY (rapat dewan) dalam Aspeknya, dan merekomendasikannya.

• Skenario B (pengungkapan publik):

"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"

Diharapkan: Agen harus melewati tabel internal bulanan dan memilih fin_quarterly_public_report secara ketat karena hanya aset tersebut yang diberi tag EXTERNAL_READY.

• Skenario C (kebutuhan operasional):

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Yang diharapkan: Agen memilih mkt_realtime_campaign_performance karena mengidentifikasi frekuensi pembaruan REALTIME_STREAMING, yang diprioritaskan daripada tingkat GOLD_CRITICAL data keuangan.

• Skenario D (eksperimen sandbox):

"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."

Harapan: Agen memilih tmp_data_dump_v2_final_real karena secara semantik cocok dengan BRONZE_ADHOC (data mentah) dan is_certified: false (lingkungan sandbox) dalam Aspeknya.

(Untuk keluar dari sesi AGY, ketik /exit atau /quit)

6. Selamat! Apa langkah selanjutnya?

Anda telah berhasil membangun fondasi data yang diatur dan membuktikan bahwa AI dapat mengikuti aturan metadata Anda secara ketat menggunakan prototipe CLI lokal.

Sekarang, Anda telah mencapai titik pemeriksaan. Pilih langkah berikutnya:

Opsi A: Saya ingin melanjutkan ke Bagian 2 sekarang.

Jika Anda siap mengubah prototipe lokal ini menjadi aplikasi web tingkat produksi yang aman menggunakan Model Context Protocol (MCP) dan Cloud Run:

👉 Link ke Codelab Bagian 2

⚠️ HENTIKAN: Jangan jalankan langkah-langkah Pembersihan di bawah. Anda memerlukan setelan data dan Knowledge Catalog saat ini untuk Bagian 2.

Opsi B: Saya akan mengerjakan Bagian 2 nanti atau saya hanya ingin menyelesaikan Bagian 1.

Jika Anda ingin berhenti untuk hari ini dan menghindari biaya cloud, Anda harus membersihkan resource.

Jangan khawatir! Di Bagian 2, kami akan memberikan "Skrip Jalur Cepat" yang akan membangun kembali lingkungan Bagian 1 ini sepenuhnya untuk Anda hanya dalam 2 menit, sehingga Anda dapat melanjutkan tepat di bagian yang terakhir Anda buka.

👉 Lanjutkan ke bagian pembersihan.

7. Membersihkan (hanya untuk opsi B)

Jika Anda berhenti di sini, hapus resource untuk menghindari timbulnya biaya.

Menghancurkan data lake

Jika saat ini Anda berada dalam sesi AGY CLI, keluar dari sesi dengan menekan Ctrl+C dua kali atau mengetik /quit. Kemudian, jalankan perintah berikut:

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

Uninstal plugin AGY CLI dan hapus file lokal

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos