Menggunakan agen Gemini CLI untuk menguji konteks data

Agen AI dapat bernalar, tetapi mereka memulai dengan nol pengetahuan tentang perusahaan spesifik Anda. Bayangkan Anda bertanya kepada agen, "Berapa pendapatan kita pada kuartal 1?" Tanpa panduan, agen mungkin memilih dari lusinan tabel bernama "pendapatan" di database Anda, mulai dari laporan resmi hingga data pengujian yang tidak teratur. Jika agen memilih tabel dengan nama yang terdengar paling mirip, agen dapat memberikan jawaban yang salah dan meyakinkan berdasarkan sumber yang tidak terverifikasi.

Pengayaan metadata adalah solusi untuk masalah konteks ini. Dalam tutorial ini, Anda akan menyiapkan aspek yang memberikan konteks ini, dan menggunakan Gemini CLI untuk menguji konteks data serta memverifikasi bahwa agen dapat secara akurat mendasarkan jawabannya pada data tepercaya dan bersertifikasi.

Tujuan

• Buat data lake yang realistis untuk pengujian.
• Gunakan aspek Knowledge Catalog untuk memberi label pada data "emas" Anda dan membedakannya dari data pengujian.
• Uji konteks data Anda secara lokal dengan Gemini CLI.

Sebelum memulai

Sebelum memulai, pastikan Anda melakukan hal berikut:

• Pilih Google Cloud project untuk tutorial ini.
• Konfirmasi bahwa penagihan diaktifkan untuk project Anda.

Untuk menyelesaikan tutorial ini, Anda juga harus memiliki pemahaman dasar tentang BigQuery, Knowledge Catalog, dan Terraform.

Menyiapkan lingkungan Anda

Tutorial ini menggunakan Google Cloud Shell, lingkungan command line yang berjalan di cloud.

1. Dari Google Cloud konsol, klik Activate Cloud Shell di toolbar kanan atas. Proses menyediakan dan menghubungkan ke lingkungan memerlukan waktu beberapa saat.

2. Di Cloud Shell, tetapkan variabel PROJECT_ID dan REGION agar semua perintah mendatang menargetkan project Google Cloud tertentu Anda.

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

3. Aktifkan layanan Google Cloud yang diperlukan.

   gcloud services enable \
     artifactregistry.googleapis.com \
     bigqueryunified.googleapis.com \
     cloudaicompanion.googleapis.com \
     cloudbuild.googleapis.com \
     cloudresourcemanager.googleapis.com \
     datacatalog.googleapis.com \
     run.googleapis.com
   

4. Buat clone repositori Demo DevRel.Google Cloud

   Download kode dan skrip infrastruktur dari GitHub. Gunakan checkout jarang untuk menarik hanya folder tertentu yang Anda butuhkan untuk tutorial 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 you need for this tutorial
   git sparse-checkout set data-analytics/governance-context
   cd data-analytics/governance-context
   

Membangun data lake

Untuk membuat semuanya realistis, Anda memerlukan campuran data resmi dan data berantakan yang tidak tepercaya. Gunakan Terraform dan file konfigurasi Terraform yang telah dikonfigurasi sebelumnya dari repositori tutorial untuk menyiapkan ini dengan cepat.

Konfigurasi Terraform menangani dua tugas:

• Menyiapkan jenis aspek (template metadata) Knowledge Catalog, set data BigQuery, dan tabel, termasuk finance_mart.fin_monthly_closing_internal dan analyst_sandbox.tmp_data_dump_v2_final_real.
• Memuat data sampel ke dalam tabel.

1. Buka direktori terraform dan lakukan inisialisasi.

   cd terraform
   terraform init
   

2. Terapkan konfigurasi. Proses ini mungkin memerlukan waktu hingga satu menit.

   terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

Sekarang Anda memiliki data lake yang tidak diatur. Bagi agen AI, tabel di data lake Anda terlihat sama persis karena hanya berupa objek dengan kolom. Untuk memperbaikinya, Anda perlu menerapkan tata kelola di langkah berikutnya.

Menerapkan tata kelola

Ini adalah bagian terpenting dari penyiapan. Saat ini, kedua tabel Anda terlihat identik bagi agen AI. Untuk membedakannya, Anda menerapkan aspek, yang seperti label metadata bersertifikasi yang memberikan konteks yang dibutuhkan agen. Di bagian ini, Anda akan menggunakan dua skrip: satu untuk membuat metadata dan satu lagi untuk menerapkannya ke tabel Anda.

Membuat payload tata kelola

Terraform telah menyiapkan jenis aspek, jadi sekarang Anda perlu membuat data untuk mengisinya.

Jalankan skrip ./generate_payloads.sh untuk membuat direktori aspect_payloads/. Direktori ini berisi empat file YAML yang menentukan berbagai skenario tata kelola, yang akan Anda terapkan pada langkah berikutnya.

Kembali ke root direktori tutorial dan jalankan skrip ./generate_payloads.sh:

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

Menerapkan aspek

1. Sebelum menjalankan skrip apply_governance.sh, lihat data yang akan dilampirkan ke tabel Anda. Jalankan perintah berikut untuk melihat metadata yang ditentukan untuk data keuangan internal Anda:

   cat aspect_payloads/fin_internal.yaml
   

   File YAML menentukan konteks bisnis untuk tabel:

   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 ini menandai data secara eksplisit sebagai is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Hal ini memberi agen AI aturan yang jelas dan terstruktur untuk diikuti.

2. Jalankan skrip apply_governance.sh. Skrip ini melakukan iterasi melalui tabel BigQuery Anda dan menggunakan CLI gcloud untuk "membubuhi" metadata dari payload YAML Anda ke setiap tabel.

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

Memverifikasi metadata

Sebelum melanjutkan, periksa apakah skrip menerapkan aspek dengan benar.

1. Buka halaman Knowledge Catalog di Google Cloud console. Anda dapat menggunakan kotak penelusuran di bagian atas untuk menemukannya.
2. Telusuri fin_monthly_closing_internal. Pilih nama tabel dalam hasil untuk membuka halaman detailnya.
3. Di bagian Tag dan aspek opsional, temukan aspek official-data-product-spec. Konfirmasi bahwa nilai cocok dengan skenario "Gold Internal" yang Anda terapkan.

Sekarang Anda telah berhasil menggunakan metadata untuk membedakan tabel ini, dan Anda telah memberi agen AI Anda cara untuk melakukan hal yang sama.

Menguji konteks data Anda dengan Gemini CLI

Sebelum membuat aplikasi web lengkap, Anda dapat menguji logika tata kelola secara lokal menggunakan lingkungan Model Context Protocol (MCP). Dalam penyiapan ini, Gemini CLI bertindak sebagai klien (antarmuka yang Anda ajak bicara) dan ekstensi Knowledge Catalog bertindak sebagai server lokal.

Menginstal ekstensi Knowledge Catalog

Di Cloud Shell, instal Ekstensi Knowledge Catalog.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Menentukan aturan

File konfigurasi GEMINI.md memiliki logika yang mengubah aturan deklaratif seperti "Saya memerlukan data yang aman" menjadi penelusuran yang tepat yang hanya menampilkan tabel dengan label tata kelola yang benar.

Saat ini, file konfigurasi hanyalah template. Anda perlu menambahkan ID project Google Cloud tertentu ke aturan agar saat Anda menjalankan CLI, CLI tersebut menargetkan data yang diatur dengan benar.

1. Tambahkan PROJECT_ID Anda ke file konfigurasi.

   envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md
   

2. Untuk memeriksa perubahan dan memahami cara kerja konteks data, lihat sekilas file GEMINI.md:

   cat GEMINI.md
   

   Perhatikan bahwa file membagi aturan menjadi Tahap 1 dan Tahap 2. Hal ini memberlakukan urutan operasi yang ketat. Agen harus terlebih dahulu mencari label tata kelola yang benar (Fase 1) sebelum diizinkan untuk menyentuh data itu sendiri (Fase 2). Logika "penelusuran terlebih dahulu" ini mencegah agen menebak nama tabel atau berhalusinasi jawaban dari sumber yang tidak terverifikasi.

   Pastikan Fase 2 berisi Google Cloud project ID Anda yang sebenarnya. Jika ini tidak benar, agen tidak akan tahu tempat untuk mencari data Anda.

Mulai Gemini CLI dan uji skenario

Mulai sesi Gemini baru. Karena Anda berada di folder project, CLI akan otomatis mendeteksi dan memuat GEMINI.md lokal sebagai konteks sistem.

gemini

Catatan: Anda mungkin melihat beberapa file konteks dimuat (misalnya, GEMINI.md dan lainnya). Hal ini wajar. CLI memuat GEMINI.md lokal untuk aturan spesifik project ini, ditambah petunjuk default untuk Ekstensi Knowledge Catalog itu sendiri.

Verifikasi penginstalan

Pastikan Ekstensi Katalog Pengetahuan aktif. dataplex akan muncul dalam daftar alat server MCP yang dikonfigurasi.

/mcp desc

Cobalah

Sekarang saatnya melihat konteks data Anda beraksi. Tempelkan perintah ini ke CLI satu per satu.

Tips: CLI akan meminta izin untuk menggunakan alatnya. Pilih "2. Izinkan alat untuk sesi ini" sehingga Anda tidak perlu menyetujui setiap langkah.

Skenario 1: Menemukan data standar "Gold"

Lihat apakah Gemini CLI dapat menemukan data yang paling tepercaya untuk rapat dewan yang penting.

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?

CLI akan melewati data mentah dan menemukan fin_monthly_closing_internal. Hal ini dilakukan dengan mencocokkan permintaan Anda untuk data "final" dan "rahasia" dengan tag GOLD_CRITICAL dan INTERNAL_ONLY yang Anda terapkan sebelumnya.

Skenario 2: Pengungkapan publik

Berpura-puralah Anda ingin membagikan data secara eksternal. Anda ingin memastikan CLI tidak membiarkan rahasia internal apa pun bocor.

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?

Meskipun tabel internal memiliki detail paling banyak, CLI harus melewatinya. Anda akan diarahkan ke fin_quarterly_public_report karena ini adalah satu-satunya tabel yang diberi tag EXTERNAL_READY.

Skenario 3: Kebutuhan operasional real-time

Ilmuwan data sering kali memerlukan info terbaru. Lihat apakah Gemini CLI memahami perbedaan antara batch harian dan livestream.

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?

CLI akan menemukan mkt_realtime_campaign_performance. Kolom ini mengidentifikasi frekuensi update REALTIME_STREAMING dalam metadata.

Skenario 4: Eksplorasi Sandbox

Terkadang "cukup baik" lebih baik daripada "sempurna". Lihat apakah Gemini CLI dapat menemukan data sandbox mentah untuk beberapa pekerjaan ML eksperimental.

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.

CLI akan menemukan tmp_data_dump_v2_final_real. Google tahu bahwa ini adalah pilihan yang tepat karena cocok dengan tingkat BRONZE_ADHOC dan ditandai secara eksplisit dengan is_certified: false.

Setelah selesai menguji, Anda dapat keluar dari sesi CLI:

/quit

Pembersihan

Ikuti langkah-langkah berikut untuk menghindari biaya berulang:

1. Hancurkan resource Terraform.

   cd ~/devrel-demos/data-analytics/governance-context/terraform
   terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
   

2. Uninstal ekstensi Knowledge Catalog dan hapus file demo lokal Anda.

   gemini extensions uninstall dataplex
   cd ~
   rm -rf ~/devrel-demos
   

Kesimpulan

Anda telah membangun fondasi data yang solid, menerapkan konteks yang ketat menggunakan metadata, dan memverifikasi bahwa semuanya berfungsi secara lokal menggunakan Gemini CLI.