Untuk mencapai akurasi kueri QueryData yang tinggi dan latensi online yang rendah dalam aplikasi agen data, Anda dapat menggunakan agen rekayasa konteks untuk membangun, mengevaluasi, dan mengoptimalkan set konteks. Dengan mengotomatiskan pembuatan, upload, dan pengoptimalan konteks, agen membantu aplikasi Anda memberikan jawaban yang cepat, deterministik, dan dapat dijelaskan untuk pertanyaan dalam bahasa alami.
Untuk mempelajari set konteks dan QueryData, lihat Ringkasan set konteks dan Ringkasan QueryData.
Dengan memberikan QueryData dengan konteks yang disesuaikan dengan aplikasi bisnis Anda, Anda memberikan aturan bisnis yang tepat yang dibutuhkan sistem untuk menyelesaikan niat pengguna yang bernuansa dan memberikan kualitas kueri hampir 100%. Saat Anda bekerja di CLI atau IDE, agen rekayasa konteks akan otomatis mengupload set konteks Anda ke Google Cloud sambil menyimpan file lokal di ruang kerja Anda untuk kontrol versi.
Agen rekayasa konteks
Agen context engineering bertindak sebagai asisten waktu desain Anda langsung di CLI atau IDE Anda. Pembuatan konteks manual memerlukan penulisan pola kueri mendetail secara manual, mengantisipasi setiap variasi frasa, dan mendiagnosis kegagalan kueri secara manual di seluruh iterasi. Agen context engineering menghilangkan overhead ini dengan melakukan bootstrap pada konteks dasar, mengumpulkan set data evaluasi kebenaran nyata, melakukan hill-climbing secara iteratif untuk memperbaiki kesenjangan akurasi, dan membuktikan bahwa konteks Anda berlaku secara umum untuk pertanyaan baru.
Anda berkomunikasi dengan agen menggunakan bahasa alami untuk mendorong alur kerja pengoptimalan. Mulailah dengan perintah seperti "Optimalkan set konteks terhadap persyaratan aplikasi saya".
Sebelum memulai
Sebelum Anda menggunakan agen rekayasa konteks, selesaikan prasyarat di
bagian berikut. Anda dapat membuat dan menyimpan set konteks di region us-central1,
us-east1, europe-west4, dan asia-southeast1, meskipun instance database Anda
berada di region yang berbeda.
Mengaktifkan layanan yang diperlukan
Aktifkan layanan berikut untuk project Anda:
Menyiapkan database Anda
Siapkan instance AlloyDB untuk PostgreSQL dan konfigurasikan akses untuk agen:
- Buat cluster dan instance AlloyDB dan buat database, atau gunakan instance dan database yang ada.
- Aktifkan akses Data API di instance AlloyDB Anda. Jika Anda menggunakan IP pribadi, tetapkan kolom akses Data API (
dataApiAccess) keENABLEDdi instance utama agar agen dapat memeriksa skema dan memvalidasi kueri. Untuk instance yang dibuat tanpa mengaktifkan akses Data API, lihat Mengaktifkan akses Data API atau konfigurasikan di konsol Google Cloud .
Peran dan izin yang diperlukan
Untuk mendapatkan izin yang diperlukan untuk menggunakan agen context engineering dan mengelola set konteks, konfigurasikan peran Identity and Access Management (IAM) dan hak istimewa database berikut:
- Tambahkan akun pengguna atau layanan IAM ke cluster. Untuk mengetahui informasi selengkapnya, lihat Mengelola autentikasi IAM.
- Berikan peran
roles/alloydb.databaseUser,roles/serviceusage.serviceUsageConsumer,roles/geminidataanalytics.queryDataUser, danroles/mcp.toolUserkepada pengguna IAM atau akun layanan di level project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project. - Untuk membuat, mengupload, dan mengelola set konteks, berikan peran Dataplex Catalog Editor (
roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) kepada pengguna IAM atau akun layanan di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks. - Jika Anda menggunakan penelusuran nilai semantik (
google_ml.embedding), aktifkan Vertex AI API dan berikan peranroles/aiplatform.userke akun layanan cluster AlloyDB. Berikan hak istimewa database hanya baca kepada pengguna atau akun layanan IAM dengan login sebagai pengguna yang memiliki hak istimewa superuser, seperti pengguna
postgres:GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";Ganti
USER_NAMEdengan alamat email untuk pengguna (untuk akun layanan, hapus akhiran.). Jika tabel Anda berada dalam skema kustom selainpublic, jalankan jugaGRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME";danGRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";. Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada pengguna IAM.
Menyiapkan database untuk penelusuran nilai
Untuk menggunakan penelusuran nilai semantik dan trigram dengan latensi kueri rendah, konfigurasikan database AlloyDB Anda dengan ekstensi yang diperlukan, kolom embedding yang telah dihitung sebelumnya, dan indeks pada tabel pencarian atau dimensi (kurang dari 100.000 baris, atau tampilan terwujud SELECT DISTINCT yang diperbarui):
Agar instance AlloyDB dapat melakukan penelusuran nilai fuzzy trigram (
%dan<->), aktifkan ekstensipg_trgmdan buat indeks trigramGiSTdi kolom pencarian target:CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE INDEX IF NOT EXISTS idx_properties_address_trgm ON properties USING GiST (address gist_trgm_ops);Indeks ini memungkinkan
ORDER BY column <-> $value::text LIMIT 25menggunakan pemindaian indeks K-nearest-neighbor (KNN), bukan memindai seluruh tabel.Agar instance AlloyDB dapat melakukan penelusuran nilai semantik (
<=>dangoogle_ml.embedding):Aktifkan Vertex AI API dan berikan peran
roles/aiplatform.userke akun layanan AlloyDB Anda. Untuk mengetahui informasi selengkapnya, lihat Mengintegrasikan dengan Vertex AI.Aktifkan ekstensi
vectordangoogle_ml_integrationdi database Anda:CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS google_ml_integration;Tambahkan kolom
vector(768)pada tabel pencarian, lakukan pra-komputasi embedding untuk baris yang ada, dan buat indeks kosinusHNSW(vector_cosine_ops) daripada memanggilgoogle_ml.embeddingper baris pada waktu kueri:ALTER TABLE properties ADD COLUMN IF NOT EXISTS city_embedding vector(768); UPDATE properties SET city_embedding = l2_normalize(subvector(google_ml.embedding('gemini-embedding-001', city)::vector, 1, 768))::vector(768) WHERE city IS NOT NULL AND city_embedding IS NULL; CREATE INDEX IF NOT EXISTS idx_properties_city_embedding_hnsw ON properties USING hnsw (city_embedding vector_cosine_ops);
Menyiapkan lingkungan Anda
Anda dapat membangun dan mengoptimalkan set konteks dari lingkungan pengembangan lokal atau IDE Anda.
Menginstal uv
Agen rekayasa konteks memerlukan uv untuk mengelola paket Python yang mendasarinya:
Instal
uvdengan mengikuti petunjuk di Menginstaluv.Pastikan
uvtelah diinstal dan dapat diakses dari command line Anda:uv --version
Menginstal agen rekayasa konteks
Instal plugin agen rekayasa konteks di lingkungan pengembangan pilihan Anda:
Antigravity CLI
- Instal Antigravity CLI. Lihat Mulai menggunakan Antigravity CLI.
- Instal plugin agen rekayasa konteks:
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
- Mulai Antigravity CLI:
agy
Untuk mengupdate plugin nanti, jalankan agy plugin uninstall db-context-engineering diikuti dengan agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.
Claude Code
- Tambahkan marketplace plugin:
/plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
- Instal plugin:
/plugin install db-context-engineering@db-context-enrichment-marketplace
- Muat ulang plugin untuk mengaktifkan perubahan:
/reload-plugins
Untuk mengupdate plugin nanti, jalankan /plugin update db-context-engineering@db-context-enrichment-marketplace.
Gemini CLI (Tidak Digunakan Lagi)
- Menginstal Gemini CLI. Lihat Mulai Menggunakan Gemini CLI.
- Instal ekstensi:
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
Untuk mengupdate ekstensi nanti, jalankan gemini extensions update google-cloud-db-context-engineering.
Autentikasi dengan Google Cloud
Konfigurasi Kredensial Default Aplikasi (ADC) untuk mengautentikasi lingkungan pengembangan Anda:
gcloud auth application-default loginTetapkan project kuota untuk kredensial Anda agar alat Model Context Protocol (MCP) dapat menggunakan project Google Cloud Anda:
gcloud auth application-default set-quota-project PROJECT_IDGanti
PROJECT_IDdengan project ID Google Cloud Anda.
Menghubungkan ke database Anda
Mulai lingkungan agen Anda dan minta agen untuk membuat koneksi database (misalnya, "Bantu saya menyiapkan koneksi database"). Agen akan memandu Anda membuat file konfigurasi
.context-engineering/tools.yamlsehingga dapat membaca skema dan memvalidasi SQL. (Sebelum.context-engineering/tools.yamldibuat, peringatan koneksi server MCPtoolboxawal saat memulai adalah hal yang wajar.)Muat ulang koneksi server MCP untuk menerapkan konfigurasi
.context-engineering/tools.yaml:- Antigravity CLI: Jalankan
/mcpdan pilihtoolbox(ataudb-context-engineering_toolbox) untuk memulai ulang. - Claude Code: Jalankan
/mcp, pilihtoolbox, lalu pilihReconnect. - Gemini CLI: Jalankan
/mcp refresh(atau/mcp reload).
- Antigravity CLI: Jalankan
Membangun dan mengoptimalkan konteks
Agen rekayasa konteks memandu set konteks Anda melalui siklus proses end-to-end, mulai dari bootstrap awal hingga generalisasi yang terverifikasi.
Melakukan bootstrap pada set konteks dasar pengukuran
Untuk menghindari pembuatan konteks dari halaman kosong, agen akan memeriksa skema database Anda beserta artefak aplikasi yang tersedia, seperti persyaratan bisnis, dokumentasi, atau contoh kueri SQL. Agen memperoleh set konteks dasar pengukuran awal yang berisi template kueri dasar dan aspek kueri yang didasarkan pada model database Anda.
Setelah membuat dan memvalidasi konteks dasar pengukuran, agen akan menguploadnya langsung ke Google Cloud dan menampilkan nama resource set konteks.
Membuat set data evaluasi dan held-out dari artefak aplikasi
Untuk meningkatkan akurasi secara sistematis, Anda memerlukan pertanyaan kebenaran nyata yang dipasangkan dengan kueri SQL terverifikasi. Jika Anda belum memiliki tolok ukur evaluasi, agen dapat membuatnya dengan mengekstrak skenario bisnis dari kode aplikasi, kueri historis, dan skema database Anda.
Selama pembuatan set data, agen membuat dua set yang berbeda:
- Tolok ukur pelatihan: Kumpulan pasangan pertanyaan-SQL representatif yang digunakan selama pengoptimalan iteratif.
- Set data yang dipertahankan: Kumpulan pertanyaan terpisah yang mirip dalam domain dengan tolok ukur pelatihan Anda, yang disediakan untuk pengujian generalisasi.
Mengoptimalkan akurasi dengan hill-climbing
Dalam pengoptimalan hill-climbing, agen secara berulang menyempurnakan set konteks Anda untuk mendorong akurasi QueryData mendekati 100%:
- Mengevaluasi: Agen menguji set konteks Anda saat ini terhadap tolok ukur pelatihan dengan menggunakan QueryData API dan menilai akurasi.
- Mendiagnosis kesenjangan: Agen menganalisis kegagalan kueri, mengidentifikasi akar masalahnya (seperti gabungan tabel yang hilang, entity pribadi yang tidak ditautkan, atau kondisi filter yang kompleks), dan merumuskan perbaikan yang ditargetkan.
- Menyempurnakan dan mengupload: Agen menambahkan atau meningkatkan kualitas template kueri, faset kueri, dan penelusuran nilai untuk mengatasi kesenjangan, dan otomatis mengupload set konteks yang diperbarui ke Google Cloud dari CLI Anda.
- Iterasi: Agen mengulangi siklus ini di seluruh putaran hingga akurasi konvergen pada skor optimal.
Diagram berikut menunjukkan alur kerja hill-climbing sistematis:
Membuktikan generalisasi dengan set data holdout
Mencapai akurasi tinggi pada tolok ukur pelatihan memang diperlukan, tetapi traffic produksi mencakup variasi frasa dan pertanyaan gabungan yang kompleks yang belum pernah terlihat selama pengembangan.
Setelah pengoptimalan hill-climbing konvergen, agen akan menguji set konteks yang dihasilkan terhadap set data yang ditahan. Langkah ini memverifikasi bahwa set konteks digeneralisasi dengan baik ke input pengguna baru tanpa overfitting ke tolok ukur awal. Agen akan menghasilkan laporan generalisasi yang menunjukkan akurasi di berbagai variasi pertanyaan yang belum pernah dilihat dan filter gabungan (seperti "Find me homes near good schools in Del Mar for a starter family with an ocean view").
Pembuatan dan penalaran on-demand
Selain menjalankan pengoptimalan penuh, Anda dapat berkomunikasi dengan agen untuk mendapatkan update yang ditargetkan seiring berkembangnya persyaratan bisnis:
Penulisan yang ditargetkan: Deskripsikan persyaratan bisnis tertentu dalam bahasa alami, dan agen akan memformat item konteks dan menguploadnya langsung dari CLI Anda tanpa pengeditan manual:
- "Create a template for: 'Find me homes near good schools in Del Mar' with SQL:
SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7." - "Buat faset untuk filter
properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500yang diberi label 'untuk keluarga pemula'." - "Buat penelusuran nilai untuk
properties.city."
- "Create a template for: 'Find me homes near good schools in Del Mar' with SQL:
Update massal di seluruh set konteks: Jika kolom database diganti namanya atau struktur tabel berubah, agen dapat mengupdate semua item konteks yang terpengaruh secara bersamaan tanpa mengubah entri yang tidak terkait:
- "Dalam set konteks saya, ganti
properties.property_type = 'SFR'denganproperties.property_type = 'Single Family Residential'untuk item apa pun yang merujuk pada rumah satu keluarga. Biarkan item yang tidak terkait."
- "Dalam set konteks saya, ganti
Langkah berikutnya
- Pelajari lebih lanjut set konteks.
- Pelajari cara menguji QueryData di AlloyDB Studio.
- Pelajari cara mengintegrasikan QueryData dengan aplikasi.
- Pelajari cara membuat atau menghapus set konteks di AlloyDB Studio.