1. Pengantar
Dalam codelab ini, Anda akan mempelajari cara mendapatkan hasil terbaik menggunakan QueryData API. Anda akan menemukan cara membuat hasil yang akurat dan dapat diulang saat membuat permintaan bahasa alami ke database Anda. Untuk membantu Anda mencapainya, panduan ini akan memandu Anda melalui enam resep di beberapa bab, yang membahas berbagai aspek bahasa alami ke SQL (NL2SQL) dan aplikasi praktisnya.
Prasyarat
- Pemahaman dasar tentang Google Cloud dan konsol Google Cloud
- Keterampilan dasar menggunakan antarmuka command line dan Cloud Shell
Yang akan Anda pelajari
- Cara men-deploy cluster dan instance utama AlloyDB
- Cara mengaktifkan QueryData, fungsi AI, dan Tampilan Aman yang Diberi Parameter
- Cara membuat set konteks QueryData
- Cara menggunakan berbagai template dan konteks di QueryData API
- Cara membuat template QueryData lebih fleksibel menggunakan faset
- Cara mengatasi ambiguitas data dengan penelusuran nilai dan pengindeksan trigram
- Cara menggunakan fungsi AI untuk penelusuran semantik dengan template
- Cara menggunakan Tampilan aman berparameter dengan QueryData API
Yang Anda butuhkan
- Akun Google Cloud dan project Google Cloud
- Browser web seperti Chrome yang mendukung Konsol Google Cloud dan Cloud Shell
2. Penyiapan dan Persyaratan
Penyiapan Project
- Login ke Konsol Google Cloud. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.
Gunakan akun pribadi, bukan akun kantor atau sekolah.
- Buat project baru atau gunakan kembali project yang sudah ada. Untuk membuat project baru di Konsol Google Cloud, di header, klik tombol Pilih project yang akan membuka jendela pop-up.
Di jendela Select a project, klik New Project yang akan membuka kotak dialog untuk project baru.
Di kotak dialog, masukkan Nama project dan pilih lokasi.
- Project name adalah nama tampilan untuk peserta project ini. Nama project tidak digunakan oleh Google API, dan dapat diubah kapan saja.
- Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Konsol Google Cloud otomatis membuat ID unik, tetapi Anda dapat menyesuaikannya. Jika tidak menyukai ID yang dibuat, Anda dapat membuat ID acak lain atau memberikan ID Anda sendiri untuk memeriksa ketersediaannya. Di sebagian besar codelab, Anda harus merujuk project ID Anda, yang biasanya diidentifikasi dengan placeholder PROJECT_ID.
- Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.
Aktifkan Penagihan
Menyiapkan akun penagihan pribadi
Jika menyiapkan penagihan menggunakan kredit Google Cloud, Anda dapat melewati langkah ini.
Untuk menyiapkan akun penagihan pribadi, buka di sini untuk mengaktifkan penagihan di Cloud Console.
Beberapa Catatan:
- Menyelesaikan lab ini akan dikenai biaya kurang dari $5 USD untuk resource Cloud.
- Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
- Pengguna baru memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD.
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:
Atau, Anda dapat menekan G, lalu S. Urutan ini akan mengaktifkan Cloud Shell jika Anda berada di Konsol Google Cloud atau menggunakan link ini.
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.
3. Sebelum memulai
Aktifkan API
Untuk menggunakan AlloyDB, Compute Engine, layanan jaringan, dan Agent Platform, aktifkan API masing-masing di project Google Cloud Anda.
Di dalam terminal Cloud Shell, pastikan project ID Anda sudah disiapkan:
gcloud config get-value project
Perintah akan menampilkan project ID Google Cloud Anda.
Tetapkan variabel lingkungan PROJECT_ID:
PROJECT_ID=$(gcloud config get-value project)
Aktifkan API yang diperlukan:
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
geminidataanalytics.googleapis.com \
cloudaicompanion.googleapis.com \
aiplatform.googleapis.com \
dataplex.googleapis.com
Output yang diharapkan:
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
geminidataanalytics.googleapis.com \
cloudaicompanion.googleapis.com \
aiplatform.googleapis.com \
dataplex.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
Anda dapat membaca tentang setiap API yang diaktifkan dalam dokumentasi.
4. Men-deploy AlloyDB
Buat cluster dan instance utama AlloyDB. Anda dapat men-deploy-nya menggunakan skrip yang telah disiapkan yang akan men-deploy semua resource yang diperlukan atau Anda dapat melakukannya langkah demi langkah sendiri dengan mengikuti dokumentasi AlloyDB.
Men-deploy AlloyDB Menggunakan Skrip Otomatis
Pendekatan ini menggunakan skrip otomatis untuk men-deploy cluster AlloyDB dan memberikan detail konfigurasi yang diperlukan untuk mulai menggunakan resource yang di-deploy.
Di terminal Cloud Shell, jalankan perintah untuk meng-clone skrip deployment dari repositori:
REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-nla"
git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR
Jalankan skrip deployment:
./deploy_alloydb.sh
Skrip memerlukan waktu lima hingga tujuh menit untuk selesai. Output akan menampilkan detail deployment cluster Anda. Perhatikan bahwa sandi Anda akan berbeda - catat sandi tersebut untuk penggunaan berikutnya.
... <redacted> ... Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster) Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715 Creating instance...done. ---------------------------------------- Deployment Process Completed Cluster: alloydb-aip-01 (TRIAL) Instance: alloydb-aip-01-pr Region: us-central1 Initial Password: JBBoDTgixzYwYpkF (if new cluster) ----------------------------------------
Lihat cluster dan instance baru Anda di halaman Cluster AlloyDB di Konsol Google Cloud.
5. Menyiapkan Database
Buat database, aktifkan integrasi Gemini Enterprise Agent Platform, buat objek database, dan tambahkan data contoh.
Memberikan Izin yang Diperlukan ke AlloyDB
Berikan peran IAM yang diperlukan ke agen layanan AlloyDB:
Buka tab Cloud Shell baru dengan mengklik Tambahkan (+).
Di tab baru, jalankan:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
Output konsol yang diharapkan:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project) Your active configuration is: [cloudshell-11039] student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \ --role="roles/aiplatform.user" Updated IAM policy for project [test-project-001-402417]. bindings: - members: - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com role: roles/aiplatform.user - members: ... etag: BwYIEbe_Z3U= version: 1
Mengaktifkan Data Access API
Aktifkan Data Access API di cluster AlloyDB Anda.
Di tab terminal yang sama, jalankan perintah berikut:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
Memperbarui Flag Database
Sebelum mengaktifkan flag di tingkat instance, tunggu hingga langkah Data Access API selesai. Pastikan status instance Anda menampilkan tanda centang hijau, seperti yang ditunjukkan pada gambar berikut.
Untuk menggunakan ekstensi AI dan autentikasi IAM untuk alat agentik, Anda harus mengaktifkan tanda database tertentu pada instance dan menambahkan diri Anda sebagai pengguna database. Aktifkan tanda berikut:
- alloydb.iam_authentication
- password.enforce_complexity
- google_ml_integration.enable_ai_query_engine
- parameterized_views
Di tab terminal yang sama, jalankan perintah berikut:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
--database-flags password.enforce_complexity=on,alloydb.iam_authentication=on,google_ml_integration.enable_ai_query_engine=on,parameterized_views.enabled=on \
--region=$REGION \
--cluster=$ADBCLUSTER \
--project=$PROJECT_ID \
--update-mode=FORCE_APPLY
Buat pengguna IAM AlloyDB untuk akun Anda:
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED
Tutup tab dengan menjalankan perintah keluar di terminal:
exit
Menghubungkan ke AlloyDB Studio
Di bab-bab berikut, Anda dapat menjalankan semua perintah SQL yang memerlukan koneksi database di AlloyDB Studio.
Untuk membuka AlloyDB Studio, lakukan langkah-langkah berikut:
- Di Konsol Google Cloud, buka halaman Cluster untuk AlloyDB untuk PostgreSQL.
- Pilih instance utama Anda untuk membuka antarmuka web-nya.
- Kemudian, klik AlloyDB Studio di sebelah kiri:
- Pilih database
postgres, pilih Autentikasi IAM, lalu klik Autentikasi.
Tindakan ini akan membuka antarmuka AlloyDB Studio.
- Pilih tab Untitled Query untuk membuka editor SQL.
Tindakan ini akan membuka editor tempat Anda dapat menjalankan perintah SQL, seperti yang ditunjukkan pada gambar berikut:
Buat Database
Membuat database panduan memulai
Di editor AlloyDB Studio, jalankan perintah berikut untuk membuat database:
CREATE DATABASE quickstart_db
Output yang diharapkan:
Statement executed successfully
Terhubung ke quickstart_db
Klik Ubah database/pengguna di AlloyDB Studio.
Pilih quickstart_db dari daftar database, pilih Autentikasi IAM, lalu lakukan autentikasi.
Tindakan ini akan membuka koneksi baru tempat Anda dapat menggunakan objek dari database quickstart_db.
Mengaktifkan ekstensi
Periksa semua ekstensi yang diperlukan untuk memverifikasi bahwa ekstensi tersebut diaktifkan di database Anda dan memiliki versi minimal yang benar.
Pastikan semua ekstensi yang diperlukan ada di database Anda:
SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector', 'google_ml_integration', 'parameterized_views');
Output yang diharapkan:
extname | extversion -----------------------+---------------- google_ml_integration | 1.5.9 parameterized_views | 1.0 vector | 0.8.2.google-1
Jika tidak menampilkan semua baris di atas, berarti beberapa ekstensi tidak diaktifkan.
Sebelum mengaktifkan ekstensi, kita harus memastikan semua tanda database ,"google_ml_integration.enable_ai_query_engine" dan "parameterized_views.enabled" diaktifkan di instance.
Di AlloyDB Studio saat terhubung ke quickstart_db, jalankan:
show google_ml_integration.enable_ai_query_engine;
show parameterized_views.enabled;
Jika salah satunya menampilkan "nonaktif", coba ulangi langkah "Perbarui Flag Database" dan periksa statusnya menggunakan perintah "show..." lagi.
Aktifkan ekstensi yang diperlukan.
Di AlloyDB Studio saat terhubung ke quickstart_db, jalankan:
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS parameterized_views;
Periksa versi ekstensi untuk parameterized_views dan google_ml.
Di AlloyDB Studio saat terhubung ke quickstart_db, jalankan:
SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector', 'google_ml_integration', 'parameterized_views');
Output yang diharapkan:
extname | extversion -----------------------+---------------- google_ml_integration | 1.5.9 parameterized_views | 1.0 vector | 0.8.2.google-1
Jika versinya lebih rendah dari yang diperlukan, coba perbarui ekstensi parameterized_views.
Untuk parameterized_views, coba:
ALTER EXTENSION parameterized_views UPDATE;
Verifikasi versi lagi.
Di AlloyDB Studio saat terhubung ke quickstart_db, jalankan:
SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector', 'google_ml_integration', 'parameterized_views');
Output yang diharapkan:
extname | extversion -----------------------+---------------- google_ml_integration | 1.5.9 parameterized_views | 1.0 vector | 0.8.2.google-1
6. Data Sampel
Sekarang Anda perlu membuat objek di database dan memuat data. Anda akan menggunakan set data perusahaan properti fiktif. Dataset ini memiliki data fiktif tentang penjualan properti dan agen. Data telah disediakan dalam skrip SQL real_estate_data.sql di repositori yang di-clone.
Buat Bucket Penyimpanan
Gunakan Google SDK (gcloud) untuk mengimpor data dari repositori yang di-clone ke database AlloyDB. Anda perlu membuat bucket Cloud Storage untuk itu dan memberikan akses ke akun layanan AlloyDB. Atau, Anda selalu dapat mencoba melakukannya menggunakan konsol web, seperti yang dijelaskan dalam dokumentasi.
Di terminal Google Cloud Shell, jalankan:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer
Muat Data
Dump SQL database berada di folder repositori yang di-clone. Perintah berikut mengasumsikan bahwa Anda telah menggunakan direktori beranda sebagai titik awal saat meng-clone repositori pada langkah sebelumnya saat membuat cluster AlloyDB.
Salin file dump database ke bucket Cloud Storage Anda:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-nla"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/real_estate_data.sql gs://$PROJECT_ID-import
Impor set data ke dalam quickstart_db:
PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
IAM_USER=$(gcloud config get-value account)
gcloud alloydb clusters import $CLUSTER_NAME --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/real_estate_data.sql --project=$PROJECT_ID --sql --user=$IAM_USER
Perintah ini akan memuat set data sampel ke database quickstart_db.
Verifikasi impor dengan menghitung data dalam tabel real_estate.agents menggunakan AlloyDB Studio:
SELECT COUNT(*) FROM real_estate.agents;
7. Menyiapkan Ontologi Skema
Siapkan set konteks QueryData Anda, berikan metadata skema, dan jalankan agen ADK.
Buat Metadata
Metadata terdiri dari komentar SQL yang diterapkan ke tabel dan kolom database. Komentar ini memandu mesin QueryData saat memilih objek database.
Jika Anda telah mengimpor skema data menggunakan dump SQL yang disediakan, semua metadata telah dibuat dalam skema Anda.
Berikut adalah contoh cuplikan metadata yang diterapkan pada skema real_estate:
COMMENT ON TABLE real_estate.agents IS 'Stores profile, contact, brokerage affiliation, and active status for individual real estate agents.'; COMMENT ON COLUMN real_estate.agents.agent_id IS 'Primary key uniquely identifying each real estate agent in the database.'; ...
Jika Anda menggunakan set data Anda sendiri, Anda dapat mengikuti panduan yang didokumentasikan tentang cara menambahkan metadata untuk skema Anda.
Membuat Konteks Ontologi Skema
Set konteks berisi template kueri, aspek, dan penelusuran nilai yang membantu model AI dalam membuat kueri. Tanpa konteks yang ditetapkan, agen AI akan mencoba membuat kueri hanya menggunakan informasi yang tersedia dari skema public, terutama berdasarkan nama tabel, kolom, dan metadata, dengan mencoba menyimpulkan objek yang tepat untuk menjawab permintaan kueri alami.
Set konteks QueryData adalah file JSON dengan template kueri, aspek, dan penelusuran nilai. Anda dapat melihat berbagai contoh dalam dokumentasi.
Memuat Set Konteks QueryData di Konsol Web
Untuk memuat set konteks, buka AlloyDB Studio dan di panel kiri di bagian bawah, Anda akan melihat Context sets dan tiga titik.
Klik tiga titik tersebut, lalu pilih Create context set.
Dalam dialog yang terbuka, masukkan nilai berikut:
- Nama:
sixrecipes - Deskripsi:
Real Estate Query Data - Mengupload file konteks: biarkan kosong
Saat Anda menekan tombol Create, mungkin perlu waktu beberapa saat untuk menginisialisasi penyimpanan konteks jika Anda melakukannya untuk pertama kalinya.
Periksa ID set konteks QueryData dengan mengklik lagi tiga titik di sebelah kanan nama set konteks, lalu pilih Edit context set.
ID set konteks muncul di bagian atas tab yang dibuka di sebelah kanan
Simpan ID ini untuk langkah-langkah selanjutnya.
Mulai Agen AI
Untuk berinteraksi dengan backend QueryData guna membuat dan menjalankan kueri, Anda dapat menggunakan antarmuka AlloyDB Studio seperti yang dijelaskan dalam dokumentasi. Namun, di lab ini, Anda akan menggunakan agen AI sebagai alat komunikasi utama dengan database. Agen AI adalah skenario yang lebih realistis untuk workload mendatang dan framework ADK Google menyediakan antarmuka web yang sangat baik tempat Anda dapat melihat semua langkah dan interaksi antara model, API, dan aplikasi.
Tinjau konfigurasi sumber agen di Cloud Shell:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-nla"
cd ~/$REPO_NAME/$SOURCE_DIR/data_agent
edit agent.py
Dalam file tersebut, Anda dapat melihat tempat kita menentukan daftar tabel dalam skema. Kita akan kembali ke hal itu di salah satu langkah berikutnya.
# List of database tables included in QueryData API requests
TABLE_IDS = [
"real_estate.municipalities",
"real_estate.cities",
"real_estate.agents",
"real_estate.properties",
"real_estate.schools",
"real_estate.school_to_property",
"real_estate.property_transactions",
"real_estate.secure_offers",
]
Selain itu, ada prosedur call_querydata_api untuk menggunakan QueryData API beserta serangkaian alat untuk menggunakan keterampilan QueryData API.
def call_querydata_api(
prompt: str,
target_project_id: str = project_id,
target_location: str = location,
target_cluster_id: str = cluster_name,
target_instance_id: str = instance_name,
target_database_id: str = database_name,
target_context_set_id: str = context_set_id,
target_table_ids: list[str] = TABLE_IDS,
) -> dict:
"""Calls the Gemini Data Analytics QueryData API to translate natural ...
<Redacted>
...
# ADK File-Based Skill
database_query_skill = load_skill_from_dir(
pathlib.Path(__file__).parent / "skills" / "database-query-skill"
)
skill_toolset = SkillToolset(
skills=[database_query_skill]
)
Berikut adalah agen root itu sendiri dengan perintah dan alat yang tersedia.
# Agent configuration
root_agent = Agent(
model=MODEL_ID,
name='root_agent',
description='A helpful assistant for analyst requests.',
instruction=f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about database contents, real estate properties, or sales activity:
1. Refer to database-query-skill for instructions on querying data using QueryData API.
2. Use `call_querydata_api` to submit the natural language prompt to the QueryData API.
CRITICAL: Call `call_querydata_api` EXACTLY ONCE per user request. Do NOT make retries, follow-up calls, or rephrased calls to `call_querydata_api`, even if the result contains zero rows or empty data.
3. Immediately parse the JSON response from that first `call_querydata_api` call.
4. Format your final response to the user containing:
- The generated SQL query (formatted in a Markdown SQL code block).
- The query results formatted as a Markdown table (constructed from `queryResult.columns` and `queryResult.rows`).
- The natural language answer (`naturalLanguageAnswer`).
""",
tools=[call_querydata_api, skill_toolset],
)
Tinjau data_agent/SKILL.md untuk memahami petunjuk sistem agen:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-nla"
cd ~/$REPO_NAME/$SOURCE_DIR/data_agent
edit SKILL.md
Sebelum memulai agen, Anda perlu menyiapkan file .env dengan parameter untuk permintaan Agent dan QueryData API.
Ekspor ID set konteks Anda ke variabel lingkungan:
export QUERYDATA_CONTEXTSET=<context set id from the Create Context Set chapter>
Buat file konfigurasi lingkungan runtime (.env) di direktori data_agent:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-nla"
cd ~/$REPO_NAME/$SOURCE_DIR/data_agent
echo "GOOGLE_GENAI_USE_ENTERPRISE=true" > .env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> .env
echo "GOOGLE_CLOUD_LOCATION=global" >> .env
echo "QUERYDATA_CONTEXTSET=$QUERYDATA_CONTEXTSET" >> .env
echo "ALLOYDB_CLUSTER=alloydb-aip-01" >> .env
echo "ALLOYDB_INSTANCE=alloydb-aip-01-pr" >> .env
echo "ALLOYDB_DATABASE=quickstart_db" >> .env
echo "ALLOYDB_LOCATION=$REGION" >> .env
Instal dependensi dan mulai layanan web agen:
cd ~/$REPO_NAME/$SOURCE_DIR/
uv sync
Mulai agen:
uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Anda akan melihat output seperti berikut dengan endpoint http://127.0.0.1:8000 .
INFO: Started server process [83608] INFO: Waiting for application startup. +-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://127.0.0.1:8000. | +-----------------------------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Klik URL server web yang dihasilkan (misalnya, http://127.0.0.1:8000) di Cloud Shell untuk meluncurkan antarmuka agen. Jika tidak berfungsi, di Cloud Shell, klik Web Preview -> Preview on port 8000 untuk membuka antarmuka agen.
Pastikan data_agent dipilih di dropdown kiri atas.
Membuat dan menjalankan kueri
Mari kita jalankan kueri Q1
Jalankan perintah bahasa alami ini di antarmuka chat agen untuk mengevaluasi performa QueryData dasar tanpa template atau aspek kustom:
How many properties are currently for sale in San Diego?
Kemudian, tekan tombol panah.
Alur kerja agen akan dimulai saat agen memilih keahlian yang sesuai dan menggunakan keahlian serta fungsi tersebut untuk mengirim permintaan ke endpoint API dan mendapatkan kembali kueri yang dihasilkan dan hasilnya.
Jika mengarahkan kursor mouse ke langkah-langkah tersebut, Anda dapat melihat dengan tepat apa yang dilakukan langkah-langkah tersebut. Anda juga dapat melihatnya dan banyak lagi di panel kiri saat memilih satu atau langkah lainnya. Hal ini dapat membantu memahami cara kerja agen dengan keahlian dan API.
Kirim kueri lanjutan (Q2):
List agents who sold a property for over $1000000.
Anda akan melihat bahwa agen langsung menuju skill QueryData API karena telah menulis ke memori skill yang tersedia dan tidak perlu melalui fase penemuan lagi.
SQL yang dihasilkan akan menyerupai pernyataan ini:
SELECT DISTINCT "a"."agent_id", "a"."firstname", "a"."lastname", "a"."email", "a"."brokerage" FROM "real_estate"."agents" AS "a" INNER JOIN "real_estate"."property_transactions" AS "t" ON "a"."agent_id" = "t"."seller_agent_id" WHERE "t"."sale_price" > 1000000 AND "a"."agent_id" IS NOT NULL ORDER BY "a"."lastname" ASC NULLS LAST;
Coba kueri lain (Q3):
What is the average price of a single-family home with a garage in San Diego?
QueryData menghasilkan kueri standar dengan set konteks kosong, tetapi tugas bisnis sering kali memerlukan logika bisnis tertentu dan perilaku deterministik.
8. Mencapai Akurasi Tinggi dan Relevansi Bisnis dengan Memasukkan Penafsiran
Menyisipkan interpretasi ke dalam perintah memastikan bahwa kueri yang dihasilkan cocok dengan logika bisnis tertentu.
Anda akan mencoba contoh tersebut dengan pelanggan yang meminta untuk mendapatkan rumah satu tingkat di Del Mar. Pertanyaan ini memiliki dua metrik penting dan mewakili pola yang sering untuk pilihan.
Coba prompt bahasa alami berikut (Q4) di agen.
Single level Del Mar houses
Mesin akan menampilkan kueri umum, tetapi mungkin menyertakan beberapa kondisi tambahan seperti is_single_family = TRUE:
SELECT p."property_id", p."address_street", p."price", p."bedrooms", p."bathrooms", p."listing_status", p."is_single_family", p."num_stories", c."city_name" FROM "real_estate"."properties" AS p JOIN "real_estate"."cities" AS c ON p."city_id" = c."city_id" WHERE c."city_name" ILIKE 'Del Mar' AND p."num_stories" = 1 AND p."is_single_family" = TRUE ORDER BY p."property_id" ASC NULLS LAST;
Kita mendapatkan satu baris yang ditampilkan sebagai hasilnya:
Natural Language Answer The database contains one single-level, single-family house in Del Mar: Address: 999 Main Ave (Postal Code: 90024) Price: $3,800,000.00 Bedrooms: 4 Bathrooms: 3.5 Listing Status: Active Features: Single-family home (1 story), has a garage, and no condo fees.
Uji perintah lain (Q5):
Del Mar houses close to good schools
Cukup pintar untuk menggunakan kolom proximity_miles dan school_ranking untuk mengurutkan properti, tetapi tidak mengevaluasi bobot dan kepentingan setiap metrik.
SELECT "p"."property_id", "p"."address_street", "p"."price", "p"."bedrooms", "p"."bathrooms", "s"."school_name", "s"."school_ranking", "sp"."proximity_miles" FROM "real_estate"."properties" AS "p" INNER JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id" INNER JOIN "real_estate"."school_to_property" AS "sp" ON "p"."property_id" = "sp"."property_id" INNER JOIN "real_estate"."schools" AS "s" ON "sp"."school_id" = "s"."school_id" WHERE "c"."city_name" = 'Del Mar' AND "sp"."proximity_miles" IS NOT NULL AND "s"."school_ranking" IS NOT NULL ORDER BY "sp"."proximity_miles" ASC NULLS LAST, "s"."school_ranking" ASC NULLS LAST;
Menggeneralisasi contoh kueri menjadi template
Logika bisnis memerlukan:
- Jarak dalam 2 mil
- Peringkat sekolah 5 atau lebih rendah
- Pengurutan berbobot: 80% peringkat sekolah + 20% kedekatan (Skor = 0,8 * school_ranking + 0,2 * proximity_miles)
Berikut adalah formula peringkat tertimbang:
Score = 0.8 * school_ranking + 0.2 * proximity_miles
Download file konteks sixrecipe_context1_1.json dari Cloud Shell menggunakan antarmuka command line di Cloud Shell:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context1_1.json
Atau dengan menggunakan item menu Download dari menu Cloud Shell:
Upload sixrecipe_context1_1.json ke set konteks sixrecipe menggunakan AlloyDB Studio untuk menentukan struktur standar ini. Klik tiga titik di sebelah kanan konteks sixrecipes dan gunakan "Edit set konteks" untuk mengupload file baru. Tindakan ini akan secara efektif menggantikan konteks kosong lama dengan konteks kosong baru.
Template menentukan aturan template SQL eksplisit untuk aturan kedekatan sekolah yang bagus:
{
"facets": [],
"templates": [
{
"nl_query": "Riverside houses close to good schools.",
"sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\", \"s\".\"school_name\", \"stp\".\"proximity_miles\" FROM \"real_estate\".\"properties\" AS \"p\" JOIN \"real_estate\".\"cities\" AS \"c\" ON \"p\".\"city_id\" = \"c\".\"city_id\" JOIN \"real_estate\".\"school_to_property\" AS \"stp\" ON \"p\".\"property_id\" = \"stp\".\"property_id\" JOIN \"real_estate\".\"schools\" AS \"s\" ON \"stp\".\"school_id\" = \"s\".\"school_id\" WHERE \"c\".\"city_name\" = 'Riverside' AND \"s\".\"school_ranking\" <= 5 AND \"stp\".\"proximity_miles\" <= 2 ORDER BY 0.8 * \"s\".\"school_ranking\" + 0.2 * \"stp\".\"proximity_miles\"",
"intent": "Houses in Riverside close to good schools (within 2 miles of schools with a rank of at least 5).",
"manifest": "A given city houses close to good schools.",
"parameterized": {
"parameterized_intent": "Houses in $1 close to good schools (within 2 miles of schools with a rank of at least 5).",
"parameterized_sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\", \"s\".\"school_name\", \"stp\".\"proximity_miles\" FROM \"real_estate\".\"properties\" AS \"p\" JOIN \"real_estate\".\"cities\" AS \"c\" ON \"p\".\"city_id\" = \"c\".\"city_id\" JOIN \"real_estate\".\"school_to_property\" AS \"stp\" ON \"p\".\"property_id\" = \"stp\".\"property_id\" JOIN \"real_estate\".\"schools\" AS \"s\" ON \"stp\".\"school_id\" = \"s\".\"school_id\" WHERE \"c\".\"city_name\" = $1 AND \"s\".\"school_ranking\" <= 5 AND \"stp\".\"proximity_miles\" <= 2 ORDER BY 0.8 * \"s\".\"school_ranking\" + 0.2 * \"stp\".\"proximity_miles\""
}
}
]
}
Jalankan kembali perintah:
Del Mar houses close to good schools
Kueri yang dihasilkan kini cocok dengan logika bisnis yang ditentukan dalam template:
SELECT "p"."address_street", "p"."address_postal_code", "s"."school_name", "stp"."proximity_miles" FROM "real_estate"."properties" AS "p" JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id" JOIN "real_estate"."school_to_property" AS "stp" ON "p"."property_id" = "stp"."property_id" JOIN "real_estate"."schools" AS "s" ON "stp"."school_id" = "s"."school_id" WHERE "c"."city_name" = 'Del Mar' AND "s"."school_ranking" <= 5 AND "stp"."proximity_miles" <= 2 ORDER BY 0.8 * "s"."school_ranking" + 0.2 * "stp"."proximity_miles"
Bersama dengan pernyataan SQL yang dihasilkan, maksud berikut dihasilkan:
intentExplanation: "Houses in Del Mar close to good schools (within 2 miles of schools with a rank of at least 5)."
Anda dapat melihat maksud di panel kiri antarmuka web ADK seperti yang ditunjukkan di sini:
Hasilnya menampilkan dua properti yang diurutkan berdasarkan Skor kami:
Query Results address_street address_postal_code school_name proximity_miles 200 Coast Blvd 92014 Del Mar Heights Elementary 0.50 100 Del Mar Heights Rd 92014 Del Mar Heights Elementary 1.00 Answer Based on the data, here are the properties in Del Mar located within 2 miles of a top-rated school (ranking of 5 or better): 200 Coast Blvd (92014) School: Del Mar Heights Elementary Proximity: 0.50 miles 100 Del Mar Heights Rd (92014) School: Del Mar Heights Elementary Proximity: 1.00 miles
Di bab berikutnya, Anda akan memperluas cakupan template.
Memasukkan Interpretasi dengan Menangkap & Menafsirkan Beberapa Pertanyaan
Anda dapat memperluas cakupan template kami agar tidak hanya digunakan untuk "dekat dengan sekolah bagus", tetapi juga menambahkan kondisi lain ke manifes untuk digunakan, misalnya, untuk "rumah untuk keluarga dengan anak-anak".
Download file konteks yang telah diperbarui:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context1_2.json
Upload file sixrecipe_context1_2.json yang telah diperbarui ke set konteks Anda.
Dalam file set konteks baru, kita mengganti manifes dari: "manifest": "A given city houses close to good schools." ke manifes: "manifest": "A given city houses close to good schools, or are great for families with kids.". Hal ini memperluas aplikasi template ini untuk digunakan lebih dari satu kasus.
Kirim kueri ini (Q6):
Houses in Waterloo great for families with kids.
Agen menggunakan manifes template yang telah diupdate untuk menerapkan logika kueri standar Anda yang menampilkan kueri yang sama seperti di atas, dengan maksud:
intentExplanation : "Houses in Waterloo close to good schools (within 2 miles of schools with a rank of at least 5)."
9. Menggunakan Template Berfaset untuk Mencapai Akurasi Tinggi sekaligus mempertahankan Fleksibilitas
Faset adalah kondisi SQL modular yang digabungkan secara dinamis dengan template untuk menangani kualifikasi (misalnya, "keluarga baru", "pemandangan laut") tanpa membuat template terpisah untuk setiap permutasi.
Daripada membuat template untuk setiap kueri atau kondisi, kita dapat menyiapkan fragmen yang dapat diterapkan ke template yang ada dengan menambahkan lebih banyak dimensi ke kueri.
Tentukan aspek untuk properti dengan atribut berikut:
- Rumah keluarga tunggal
- Status listingan aktif
- Tiga hingga empat kamar tidur dan setidaknya dua kamar mandi
- Lokasi di kota dengan tingkat kejahatan di bawah 500 per 100.000 penduduk
Download file konteks berfaset:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context2_1.json
Upload sixrecipe_context2_1.json ke set konteks sixrecipes di AlloyDB Studio untuk mengonfigurasi aspek.
"facets": [
{
"sql_snippet": "real_estate.properties.is_single_family = TRUE AND real_estate.properties.listing_status = 'Active' AND real_estate.properties.bedrooms BETWEEN 3 AND 4 AND real_estate.properties.bathrooms >= 2.0 AND 500 > (SELECT m.crime_rate_per_100k FROM real_estate.cities c JOIN real_estate.municipalities m ON c.municipality_id = m.municipality_id AND c.city_id = real_estate.properties.city_id)",
"intent": "for a starter family (active single-family home listings with 3 to 4 bedrooms, 2+ bathrooms, and a crime rate under 500 per 100,000 residents)",
"manifest": "for a starter family",
"parameterized": {
"parameterized_intent": "for a starter family (active single-family home listings with 3 to 4 bedrooms, 2+ bathrooms, and a crime rate under 500 per 100,000 residents)",
"parameterized_sql_snippet": "real_estate.properties.is_single_family = TRUE AND real_estate.properties.listing_status = 'Active' AND real_estate.properties.bedrooms BETWEEN 3 AND 4 AND real_estate.properties.bathrooms >= 2.0 AND 500 > (SELECT m.crime_rate_per_100k FROM real_estate.cities c JOIN real_estate.municipalities m ON c.municipality_id = m.municipality_id AND c.city_id = real_estate.properties.city_id)"
}
}
]
Membuat kueri menggunakan penelusuran dengan filter
Jalankan kueri NL ini (Q7):
Del Mar houses close to good schools for a starter family.
Mesin menambahkan kondisi aspek Anda langsung ke kueri dasar:
SELECT "p"."address_street", "p"."address_postal_code", "s"."school_name", "stp"."proximity_miles"
FROM "real_estate"."properties" AS "p"
JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id"
JOIN "real_estate"."school_to_property" AS "stp" ON "p"."property_id" = "stp"."property_id"
JOIN "real_estate"."schools" AS "s" ON "stp"."school_id" = "s"."school_id"
WHERE "c"."city_name" = 'Del Mar'
AND "s"."school_ranking" <= 5
AND "stp"."proximity_miles" <= 2
AND "p"."is_single_family" = TRUE
AND "p"."listing_status" = 'Active'
AND "p"."bedrooms" BETWEEN 3 AND 4
AND "p"."bathrooms" >= 2.0
AND 500 > (
SELECT m.crime_rate_per_100k
FROM real_estate.cities c
JOIN real_estate.municipalities m ON c.municipality_id = m.municipality_id
AND c.city_id = p.city_id
)
ORDER BY 0.8 * "s"."school_ranking" + 0.2 * "stp"."proximity_miles"
Berikut hasilnya:
Query Results address_street address_postal_code school_name proximity_miles 200 Coast Blvd 92014 Del Mar Heights Elementary 0.50 Natural Language Answer Based on your criteria, there is an active listing for a single-family house in Del Mar that fits your needs: Address: 200 Coast Blvd, Del Mar, 92014 Nearby School: Del Mar Heights Elementary (ranked within the top 5) Proximity to School: 0.50 miles
Menambahkan lebih banyak faset
Bagaimana jika kita ingin menambahkan satu dimensi lagi berdasarkan pola baru yang muncul - seperti tampilan jendela untuk properti?
Tambahkan pencocokan semantik pemandangan laut dalam definisi aspek.
{
"sql_snippet": "((real_estate.properties.description_embedding <=> google_ml.embedding('gemini-embedding-001', 'unobstructed, panoramic, ocean vista, vast Pacific, breathtaking, commanding view, deep blue horizon, massive, sweeping view')::vector) < 0.4)",
"intent": "with ocean view",
"manifest": "with ocean view",
"parameterized": {
"parameterized_intent": "with ocean view",
"parameterized_sql_snippet": "((real_estate.properties.description_embedding <=> google_ml.embedding('gemini-embedding-001', 'unobstructed, panoramic, ocean vista, vast Pacific, breathtaking, commanding view, deep blue horizon, massive, sweeping view')::vector) < 0.4)"
}
Nilai 0,4 dalam definisi aspek di atas adalah nilai minimum yang dikalibrasi secara eksperimental. Download file konteks multifaset:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context2_2.json
Upload sixrecipe_context2_2.json ke set konteks Anda dan jalankan perintah ini (Q8):
Ocean view Del Mar homes near good schools.
Outputnya berisi kondisi standar yang digabungkan dengan pencocokan kesamaan vektor melalui google_ml.embedding:
SELECT "p"."address_street", "p"."address_postal_code", "s"."school_name", "stp"."proximity_miles"
FROM "real_estate"."properties" AS "p"
JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id"
JOIN "real_estate"."school_to_property" AS "stp" ON "p"."property_id" = "stp"."property_id"
JOIN "real_estate"."schools" AS "s" ON "stp"."school_id" = "s"."school_id"
WHERE "c"."city_name" = 'Del Mar' AND "s"."school_ranking" <= 5 AND "stp"."proximity_miles" <= 2
AND (((p.description_embedding <=> google_ml.embedding('gemini-embedding-001', 'unobstructed, panoramic, ocean vista, vast Pacific, breathtaking, commanding view, deep blue horizon, massive, sweeping view')::vector) <= 0.4))
ORDER BY 0.8 * "s"."school_ranking" + 0.2 * "stp"."proximity_miles";
Kueri menampilkan satu properti:
Query Results address_street address_postal_code school_name proximity_miles 100 Del Mar Heights Rd 92014 Del Mar Heights Elementary 1.00 Answer The ocean-view home in Del Mar near a top-ranked school is located at 100 Del Mar Heights Rd (92014). It is situated just 1.00 mile away from Del Mar Heights Elementary, which is one of the area's highly-ranked schools (ranking of 5 or better).
Verifikasi hasilnya dengan memeriksa deskripsi properti di AlloyDB Studio dan menjalankan kueri berikut:
select description from real_estate.properties where address_postal_code='92014' and description is not null;
Deskripsi dengan "pertunjukan laut yang luar biasa" akan ditampilkan.
Well-located 2-bedroom condo with excellent proximity to coastal shopping and dining. The balcony provides a magnificent marine spectacle against an azure backdrop. Under contract, high monthly HOA fee.
10. Disambiguasi Data Pribadi Anda menggunakan Penelusuran Nilai
Permintaan yang ambigu dapat mencocokkan beberapa entitas, seperti mengacaukan nama lokasi dengan nama bisnis. Penelusuran nilai memetakan istilah ke konsep database untuk membantu menyelesaikan referensi ini.
Penelusuran nilai memberikan asosiasi antara nama kolom plus nilai dalam kolom dan jenis konsep yang dapat berupa kota, negara, atau nama. Karena telah mengindeks tidak hanya metadata, tetapi juga sampel representatif data dalam kolom, maka nilai yang digunakan dalam permintaan bahasa alami dapat dikaitkan dengan kemungkinan jenis konsep serta tabel dan kolom yang dapat digunakan dalam SQL yang dihasilkan.
Ambiguitas dalam kueri
Dalam kehidupan nyata, hal ini bisa lebih sulit dilakukan karena salah eja nama dan lokasi yang berbeda. Jalankan perintah ini (Q9) yang berisi kesalahan ketik dan istilah ambigu:
Westwod's sold properties in the last 1 month.
Ada dua masalah di sini - nama salah eja dan tidak jelas apakah kita sedang berbicara tentang properti yang dijual di lokasi dengan nama serupa atau tentang agen real estate. Saat kita menjalankan kueri, kueri tersebut akan menampilkan kueri seperti berikut.
SELECT "p"."property_id", "p"."address_street", "p"."address_postal_code", "p"."price" AS "listing_price", "p"."bedrooms", "p"."bathrooms", "p"."listing_status", "pt"."sale_date", "pt"."sale_price", "c"."city_name" FROM "real_estate"."properties" AS "p" INNER JOIN "real_estate"."property_transactions" AS "pt" ON "p"."property_id" = "pt"."property_id" INNER JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id" WHERE ("c"."city_name" ILIKE '%Westwood%' OR "c"."city_name" ILIKE '%Westwod%') AND "pt"."sale_date" >= '2025-09-01'::date AND "pt"."sale_date" <= '2025-09-30'::date ORDER BY "pt"."sale_date" DESC NULLS LAST, "pt"."sale_price" DESC NULLS LAST
Model telah mengoreksi nama dan mengasumsikan bahwa pertanyaan tersebut adalah tentang lokasi properti yang mencoba mencocokkan properti di kota Westwood.
Aktifkan ekstensi pg_trgm di AlloyDB Studio untuk mendukung perbandingan string fuzzy:
CREATE EXTENSION IF NOT EXISTS pg_trgm;
Setelah itu, kita dapat menggunakan ekstensi untuk menambahkan penelusuran nilai ke set konteks QueryData.
Berikut daftar penelusuran nilai yang ingin kita gunakan:
"value_searches": [
{
"conceptType": "Municipality name",
"query": "/* Requires extension: pg_trgm */ WITH TrigramMetrics AS (SELECT T.municipality_name AS original_value, (T.municipality_name % $value::text) AS normalized_dist FROM real_estate.municipalities T WHERE T.municipality_name % $value::text) SELECT original_value AS value, 'real_estate.municipalities.municipality_name' AS columns, 'Name of the municipality' AS concept_type, normalized_dist AS distance, ''::text AS context FROM TrigramMetrics",
"description": "Trigram match for municipality name"
},
{
"conceptType": "City name",
"query": "/* Requires extension: pg_trgm */ WITH TrigramMetrics AS (SELECT T.city_name AS original_value, (T.city_name % $value::text) AS normalized_dist FROM real_estate.cities T WHERE T.city_name % $value::text) SELECT original_value AS value, 'real_estate.cities.city_name' AS columns, 'Name of the city' AS concept_type, normalized_dist AS distance, ''::text AS context FROM TrigramMetrics",
"description": "Trigram match for city name"
},
{
"conceptType": "Brokerage name",
"query": "/* Requires extension: pg_trgm */ WITH TrigramMetrics AS (SELECT T.brokerage AS original_value, (T.brokerage % $value::text) AS normalized_dist FROM real_estate.agents T WHERE T.brokerage % $value::text) SELECT original_value AS value, 'real_estate.agents.brokerage' AS columns, 'Name of the brokerage' AS concept_type, normalized_dist AS distance, ''::text AS context FROM TrigramMetrics",
"description": "Trigram match for brokerage name"
}
]
Download file konteks penelusuran nilai:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context3_1.json
Upload sixrecipe_context3_1.json ke set konteks QueryData sixrecipes, lalu simpan.
Jalankan kembali perintah (Q9):
Westwod's sold properties in the last 1 month.
Respons klarifikasi ditampilkan karena dalam penelusuran nilai, ditemukan 3 entitas berbeda yang memiliki nilai serupa:
The database requires some clarification to provide the exact information you need: The search term 'Westwod' (Westwood) is ambiguous because it can refer to: A municipality name (e.g., the municipality of Westwood) A city name (e.g., the city of Westwood) A brokerage name (e.g., properties sold by agents affiliated with the Westwood brokerage) Could you please clarify which of these you are referring to?
Rekaman aktivitas memberi kita petunjuk mengapa jalur tersebut dipilih
Berikut teks lengkapnya:
"[NOT_ENOUGH_INFO] The search term 'Westwod' is ambiguous because it can refer to a municipality name, a city name, or a brokerage name. Could you please clarify if you are referring to properties sold within the municipality of Westwood, the city of Westwood, or properties sold by agents affiliated with the Westwood brokerage?"
Menghilangkan ambiguitas dari kueri
Sempurnakan perintah input (Q10):
Westwood city location properties sold in September 2025.
Sekarang kita memiliki kueri dan hasilnya:
Generated SQL SELECT "p"."property_id", "p"."address_street", "p"."address_postal_code", "p"."price", "pt"."sale_date", "pt"."sale_price" FROM "real_estate"."properties" AS "p" INNER JOIN "real_estate"."cities" AS "c" ON "p"."city_id" = "c"."city_id" INNER JOIN "real_estate"."property_transactions" AS "pt" ON "p"."property_id" = "pt"."property_id" WHERE "c"."city_name" = 'Westwood' AND "pt"."sale_date" >= '2025-09-01'::date AND "pt"."sale_date" <= '2025-09-30'::date ORDER BY "pt"."sale_date" ASC NULLS LAST Query Results property_id address_street address_postal_code price sale_date sale_price 32 999 Main St 99999 3800000.00 2025-09-12 1000000.00
11. Penelusuran Semantik dan Fungsi AI
Fungsi AlloyDB AI memungkinkan pemfilteran semantik atas data tidak terstruktur. Gunakan fungsi seperti ai.if dan google_ml.embedding langsung dalam kueri SQL bersama dengan operator database standar.
Template dengan operator ILIKE
Sebagai langkah pertama, upload file konteks baru dengan operator ILIKE.
Download file konteks template ILIKE:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context4_1.json
Upload sixrecipe_context4_1.json ke set konteks Anda untuk mengevaluasi pencocokan pola ILIKE standar untuk rumah "siap huni".
{
"nl_query": "Move-in ready houses",
"sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\" FROM \"real_estate\".\"properties\" AS \"p\" WHERE \"p\".listing_status = 'Active' AND \"p\".\"description\" IS NOT NULL AND (\"p\".description ILIKE '%turnkey%' OR \"p\".description ILIKE '%move-in%')",
"intent": "Move-in ready houses",
"manifest": "Move-in ready houses",
"parameterized": {
"parameterized_intent": "Move-in ready houses",
"parameterized_sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\" FROM \"real_estate\".\"properties\" AS \"p\" WHERE \"p\".listing_status = 'Active' AND \"p\".\"description\" IS NOT NULL AND (\"p\".description ILIKE '%turnkey%' OR \"p\".description ILIKE '%move-in%')"
}
}
Kirim kueri ini (Q11):
List move-in ready houses.
Kueri yang dihasilkan:
SELECT "p"."address_street", "p"."address_postal_code"
FROM "real_estate"."properties" AS "p"
WHERE "p".listing_status = 'Active'
AND "p"."description" IS NOT NULL
AND ("p".description ILIKE '%turnkey%' OR "p".description ILIKE '%move-in%')
Tindakan ini akan menampilkan satu catatan yang cocok.
Query Results address_street address_postal_code 40 Main St, Unit 8 N2H 2G8
Template dengan fungsi AI.IF
Download file konteks template AI.IF:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context4_2.json
Upload sixrecipe_context4_2.json ke set konteks Anda untuk mengevaluasi fungsi pemfilteran semantik ai.if.
{
"nl_query": "List Move-in ready houses",
"sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\" FROM \"real_estate\".\"properties\" AS \"p\" WHERE \"p\".listing_status = 'Active' AND \"p\".\"description\" IS NOT NULL AND ai.if('Does this description represent a move-in ready house? Description: ' || \"p\".\"description\")",
"intent": "List Move-in ready houses",
"manifest": "List Move-in ready houses",
"parameterized": {
"parameterized_intent": "List Move-in ready houses",
"parameterized_sql": "SELECT \"p\".\"address_street\", \"p\".\"address_postal_code\" FROM \"real_estate\".\"properties\" AS \"p\" WHERE \"p\".listing_status = 'Active' AND \"p\".\"description\" IS NOT NULL AND ai.if('Does this description represent a move-in ready house? Description: ' || \"p\".\"description\")"
}
}
Ulangi perintah (Q12):
List move-in ready houses.
SQL yang dibuat:
SELECT "p"."address_street", "p"."address_postal_code"
FROM "real_estate"."properties" AS "p"
WHERE "p".listing_status = 'Active'
AND "p"."description" IS NOT NULL
AND ai.if('Does this description represent a move-in ready house? Description: ' || "p"."description")
Hal ini memberi kita properti yang sama dalam hasilnya:
Query Results Address Street Address Postal Code 40 Main St, Unit 8 N2H 2G8 Natural Language Answer The move-in ready home currently available is located at: Address: 40 Main St, Unit 8 Postal Code: N2H 2G8
Faset dengan penelusuran vektor
Download file konteks penelusuran sematan:
cloudshell download ~/codelabs/alloydb-ai-nla/sixrecipe_context4_3.json
Upload sixrecipe_context4_3.json ke set konteks Anda untuk mengevaluasi penelusuran vektor semantik menggunakan google_ml.embedding dan menelusuri rumah dengan peralatan dapur baru.
Perbarui set konteks menggunakan file sixrecipe_context4_3.json dengan aspek tambahan menggunakan penelusuran vektor AlloyDB.
{
"sql_snippet": "((real_estate.properties.description_embedding <=> google_ml.embedding('gemini-embedding-001', 'Upgraded kitchen appliances')::vector) < 0.4)",
"intent": "with upgraded kitchen appliances",
"manifest": "with upgraded kitchen appliances",
"parameterized": {
"parameterized_intent": "with upgraded kitchen appliances",
"parameterized_sql_snippet": "((real_estate.properties.description_embedding <=> google_ml.embedding('gemini-embedding-001', 'Upgraded kitchen appliances')::vector) < 0.4)"
}
}
Nilai 0,4 dalam definisi aspek di atas adalah nilai minimum yang dikalibrasi secara eksperimental.
Jalankan kueri ini (Q13):
List move-in ready houses with upgraded kitchen appliances.
SQL yang dibuat:
SELECT "p"."address_street", "p"."address_postal_code" FROM "real_estate"."properties" AS "p" WHERE "p"."listing_status" = 'Active' AND "p"."description" IS NOT NULL AND ai.if('Does this description represent a Move-in ready house? Description: ' || "p"."description") AND ((("p"."description_embedding" <=> google_ml.embedding('gemini-embedding-001', 'Upgraded kitchen appliances')::vector) < 0.4))
Berikut hasil kueri dan rekomendasi bahasa alami:
Query Results Address Postal Code 40 Main St, Unit 8 N2H 2G8 Natural Language Answer The move-in ready house with upgraded kitchen appliances is located at: Address: 40 Main St, Unit 8 Postal Code: N2H 2G8
12. Keamanan & Privasi
Setiap kali API QueryData menghasilkan kueri, ada risiko privasi bahwa kueri yang dihasilkan dapat mengekspos data milik pengguna lain. Tampilan Aman yang Diberi Parameter (PSV) menerapkan batas keamanan tingkat baris selama pembuatan NL2SQL.
Membuat Tampilan Aman yang Diberi Parameter
Kita memiliki tabel real_estate.offers dengan informasi tentang penawaran untuk semua transaksi properti kita. Kita ingin agen kita hanya melihat kesepakatan mereka sendiri, bukan kesepakatan agen lain. Kita membuat PSV dengan kemampuan untuk memfilter baris berdasarkan agent_id.
Buat Parameterized Secure View untuk tabel penawaran di AlloyDB Studio:
CREATE VIEW real_estate.secure_offers
WITH (security_barrier) AS
SELECT offer_id, property_id, buyer_agent_id,
seller_agent_id, offer_amount, offer_date,
offer_status, offer_expiration_date,
contingencies
FROM real_estate.offers
WHERE buyer_agent_id = $@agent_id;
Verifikasi definisi tampilan keamanan berparameter:
SELECT definition
FROM parameterized_views.all_parameterized_views
WHERE schemaname = 'real_estate' AND viewname = 'secure_offers';
Bagaimana dengan tabel real_estate.offers?
Membatasi akses data QueryData menggunakan tampilan aman yang diberi parameter AlloyDB
Di agent.py, tampilan keamanan berparameter real_estate.secure_offers terdaftar di TABLE_IDS, bukan real_estate.offers:
Kode sumber agent.py:
List of database tables included in QueryData API requests
TABLE_IDS = [
"real_estate.municipalities",
"real_estate.cities",
"real_estate.agents",
"real_estate.properties",
"real_estate.schools",
"real_estate.school_to_property",
"real_estate.property_transactions",
"real_estate.secure_offers",
]
Dan meneruskan konteks runtime sesi untuk agen dengan agent_id=1:
"parameterized_secure_view_parameters": {
"parameters": {
"key": "agent_id",
"value": "1"
}
}
},
Akibatnya, setiap permintaan QueryData API akan meneruskan parameter tersebut dan saat tampilan aman disertakan dalam permintaan, tampilan tersebut akan menerapkan pemfilteran yang hanya menampilkan hasil untuk agen tertentu tersebut.
Jalankan kueri ini (Q14):
List the offer id and listing price in 2025 where the offer was within 5% of the final selling price.
SQL yang dibuat:
SELECT "o"."offer_id", "p"."price" AS "listing_price"
FROM "real_estate"."secure_offers" AS "o"
INNER JOIN "real_estate"."properties" AS "p" ON "o"."property_id" = "p"."property_id"
INNER JOIN "real_estate"."property_transactions" AS "t" ON "o"."property_id" = "t"."property_id"
WHERE "o"."offer_date" >= '2025-01-01'
AND "o"."offer_date" <= '2025-12-31'
AND "o"."offer_amount" IS NOT NULL
AND "t"."sale_price" IS NOT NULL
AND "p"."price" IS NOT NULL
AND ABS("o"."offer_amount" - "t"."sale_price") <= (0.05 * "t"."sale_price")
ORDER BY "o"."offer_id" ASC NULLS LAST
Mengirim kueri ke tampilan akan memfilter hasil menurut parameter sesi agen aktif, melindungi data rekaman yang tidak sah, dan hanya menampilkan dua rekaman.
Query Results Offer ID Listing Price 7 $750,000.00 8 $510,000.00 Natural Language Answer Here are the offers from 2025 where the offer amount was within 5% of the final selling price: Offer ID 7: Listing Price of $750,000.00 Offer ID 8: Listing Price of $510,000.00
Jika Anda menjalankan kueri berikut terhadap tabel real_estate.offers dasar di AlloyDB Studio:
SELECT "o"."offer_id", "p"."price" AS "listing_price"
FROM "real_estate"."offers" AS "o"
INNER JOIN "real_estate"."properties" AS "p" ON "o"."property_id" = "p"."property_id"
INNER JOIN "real_estate"."property_transactions" AS "t" ON "o"."property_id" = "t"."property_id"
WHERE "o"."offer_date" >= '2025-01-01'
AND "o"."offer_date" <= '2025-12-31'
AND "o"."offer_amount" IS NOT NULL
AND "t"."sale_price" IS NOT NULL
AND "p"."price" IS NOT NULL
AND ABS("o"."offer_amount" - "t"."sale_price") <= (0.05 * "t"."sale_price")
ORDER BY "o"."offer_id" ASC NULLS LAST
Laporan ini menampilkan lebih dari dua data, yang menunjukkan data untuk semua agen.
Lab kita sudah selesai. Anda telah mempelajari cara menggunakan QueryData API, Fungsi AI, dan Tampilan Aman yang Diberi Parameter AlloyDB.
13. Membersihkan lingkungan
Hancurkan instance dan cluster AlloyDB setelah Anda selesai mengerjakan lab.
Hapus cluster AlloyDB dan semua instance
Cluster tersebut dihancurkan dengan opsi force yang juga akan menghapus semua instance milik cluster tersebut.
Jika terminal Anda terputus, hubungkan kembali dan tentukan variabel project dan lingkungan di Cloud Shell:
gcloud config set project <YOUR_PROJECT_ID>
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)
Hapus cluster:
gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
Output konsol yang diharapkan:
student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force All of the cluster data will be lost when the cluster is deleted. Do you want to continue (Y/n)? Y Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f Deleting cluster...done.
Hapus Cadangan AlloyDB
Hapus semua cadangan AlloyDB untuk cluster:
for i in $(gcloud alloydb backups list \
--filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" \
--format="value(name)" \
--sort-by=~createTime) ; do \
gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Output konsol yang diharapkan:
student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f Deleting backup...done.
Menghapus Bucket Cloud Storage
Hapus bucket impor Cloud Storage untuk mencegah biaya penyimpanan berkelanjutan:
gcloud storage rm -r gs://${PROJECT_ID}-import
14. Selamat
Selamat, Anda telah menyelesaikan codelab ini!
Yang telah kita bahas
- Cara men-deploy cluster dan instance utama AlloyDB
- Cara mengaktifkan QueryData, fungsi AI, dan Parameterized Secure Views untuk AlloyDB
- Cara membuat set konteks QueryData
- Cara menggunakan berbagai template dan konteks di QueryData API
- Cara membuat template QueryData lebih fleksibel menggunakan faset
- Cara mengatasi ambiguitas data dengan penelusuran nilai dan pengindeksan trigram
- Cara menggunakan fungsi AI untuk penelusuran semantik dengan template
- Cara menggunakan Tampilan aman berparameter dengan QueryData API
Survei
Output: