1. Ringkasan
Dalam codelab ini, Anda akan membuat Neighbor Loop, aplikasi berbagi kelebihan yang berkelanjutan yang memperlakukan kecerdasan sebagai bagian penting dari lapisan data.
Dengan mengintegrasikan Gemini 3.0 Flash dan AlloyDB AI, Anda akan melampaui penyimpanan dasar dan memasuki ranah In-Database Intelligence. Anda akan mempelajari cara melakukan analisis item multimodal dan penemuan semantik langsung dalam SQL, sehingga menghilangkan "Pajak AI" berupa latensi dan pembengkakan arsitektur.
Yang akan Anda build
Aplikasi web "geser untuk mencocokkan" berperforma tinggi untuk berbagi kelebihan persediaan komunitas.
Yang akan Anda pelajari
- Penyediaan Sekali Klik: Cara menyiapkan cluster dan instance AlloyDB yang dirancang untuk workload AI.
- Embedding Dalam Database: Membuat vektor text-embedding-005 langsung dalam pernyataan INSERT.
- Penalaran Multimodal: Menggunakan Gemini 3.0 Flash untuk "melihat" item dan membuat bio bergaya kencan yang cerdas secara otomatis.
- Penemuan Semantik: Melakukan "pengecekan suasana" berbasis logika di dalam kueri SQL menggunakan fungsi ai.if() untuk memfilter hasil berdasarkan konteks, bukan hanya matematika.
Arsitektur
Neighbor Loop melewati hambatan tradisional di lapisan aplikasi. Daripada menarik data untuk memprosesnya, kita menggunakan:
- AlloyDB AI: Untuk membuat dan menyimpan vektor secara real-time.
- Google Cloud Storage: Untuk menyimpan gambar
- Gemini 3.0 Flash: Untuk melakukan penalaran dalam waktu kurang dari satu detik pada data gambar dan teks secara langsung melalui SQL.
- Cloud Run: Untuk menghosting backend Flask satu file yang ringan.
Persyaratan
2. Sebelum memulai
Membuat project
- Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
- Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.
- Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
- Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:
gcloud auth list
- Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
- Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:
gcloud config set project <YOUR_PROJECT_ID>
- Aktifkan API yang diperlukan: Ikuti link dan aktifkan API.
Atau, Anda dapat menggunakan perintah gcloud untuk melakukannya. Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.
Gotcha & Pemecahan Masalah
Sindrom "Project Hantu" | Anda menjalankan |
Penghalang Penagihan | Anda mengaktifkan project, tetapi lupa akun penagihan. AlloyDB adalah mesin berperforma tinggi; mesin ini tidak akan dimulai jika "tangki bahan bakar" (penagihan) kosong. |
Keterlambatan Penyebaran API | Anda mengklik "Aktifkan API", tetapi command line masih menampilkan |
Quags Kuota | Jika menggunakan akun uji coba yang baru, Anda mungkin mencapai kuota regional untuk instance AlloyDB. Jika |
Agen Layanan"Tersembunyi" | Terkadang, Agen Layanan AlloyDB tidak otomatis diberi peran |
3. Penyiapan database
Di lab ini, kita akan menggunakan AlloyDB sebagai database untuk data pengujian. Cloud SQL menggunakan cluster untuk menyimpan semua resource, seperti database dan log. Setiap cluster memiliki instance utama yang menyediakan titik akses ke data. Tabel akan menyimpan data sebenarnya.
Mari kita buat cluster, instance, dan tabel AlloyDB tempat set data pengujian akan dimuat.
- Klik tombol atau Salin link di bawah ke browser tempat Anda login sebagai pengguna Konsol Google Cloud.
- Setelah langkah ini selesai, repo akan di-clone ke editor Cloud Shell lokal Anda dan Anda akan dapat menjalankan perintah di bawah dari folder project (penting untuk memastikan Anda berada di direktori project):
sh run.sh
- Sekarang gunakan UI (dengan mengklik link di terminal atau mengklik link "preview on web" di terminal.
- Masukkan detail Anda untuk project id, nama cluster, dan nama instance untuk memulai.
- Ambil kopi sambil melihat log yang bergulir dan Anda dapat membaca tentang cara kerjanya di balik layar di sini.
Gotcha & Pemecahan Masalah
Masalah "Kesabaran" | Cluster database adalah infrastruktur yang berat. Jika Anda memuat ulang halaman atau menghentikan sesi Cloud Shell karena "tampaknya macet", Anda mungkin akan mendapatkan instance "hantu" yang disediakan sebagian dan tidak dapat dihapus tanpa intervensi manual. |
Ketidakcocokan Region | Jika Anda mengaktifkan API di |
Cluster Zombie | Jika sebelumnya Anda menggunakan nama yang sama untuk cluster dan tidak menghapusnya, skrip mungkin akan menyatakan bahwa nama cluster sudah ada. Nama cluster harus unik dalam project. |
Waktu Tunggu Cloud Shell | Jika istirahat kopi Anda berlangsung selama 30 menit, Cloud Shell mungkin akan memasuki mode tidur dan menghentikan proses |
4. Penyediaan Skema
Setelah cluster dan instance AlloyDB Anda berjalan, buka editor SQL AlloyDB Studio untuk mengaktifkan ekstensi AI dan menyediakan skema.
Anda mungkin perlu menunggu hingga instance selesai dibuat. Setelah selesai, login ke AlloyDB menggunakan kredensial yang Anda buat saat membuat cluster. Gunakan data berikut untuk melakukan autentikasi ke PostgreSQL:
- Nama pengguna : "
postgres" - Database : "
postgres" - Sandi : "
alloydb" (atau apa pun yang Anda tetapkan pada saat pembuatan)
Setelah Anda berhasil diautentikasi ke AlloyDB Studio, perintah SQL dimasukkan di Editor. Anda dapat menambahkan beberapa jendela Editor menggunakan tanda plus di sebelah kanan jendela terakhir.
Anda akan memasukkan perintah untuk AlloyDB di jendela editor, menggunakan opsi Jalankan, Format, dan Hapus sesuai kebutuhan.
Mengaktifkan Ekstensi
Untuk membangun aplikasi ini, kita akan menggunakan ekstensi pgvector dan google_ml_integration. Ekstensi pgvector memungkinkan Anda menyimpan dan menelusuri embedding vektor. Ekstensi google_ml_integration menyediakan fungsi yang Anda gunakan untuk mengakses endpoint prediksi Vertex AI guna mendapatkan prediksi di SQL. Aktifkan ekstensi ini dengan menjalankan DDL berikut:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Membuat tabel
Anda dapat membuat tabel menggunakan pernyataan DDL di bawah di AlloyDB Studio:
-- Items Table (The "Profile" you swipe on)
CREATE TABLE items (
item_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id UUID,
provider_name TEXT,
provider_phone TEXT,
title TEXT,
bio TEXT,
category TEXT,
image_url TEXT,
item_vector VECTOR(768),
status TEXT DEFAULT 'available',
created_at TIMESTAMP DEFAULT NOW()
);
-- Swipes Table (The Interaction)
CREATE TABLE swipes (
swipe_id SERIAL PRIMARY KEY,
swiper_id UUID,
item_id UUID REFERENCES items(item_id),
direction TEXT CHECK (direction IN ('left', 'right')),
is_match BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
Kolom item_vector akan memungkinkan penyimpanan untuk nilai vektor teks.
Berikan Izin
Jalankan pernyataan di bawah untuk memberikan izin eksekusi pada fungsi "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Memberikan PERAN Vertex AI User ke akun layanan AlloyDB
Dari konsol IAM Google Cloud, berikan akses akun layanan AlloyDB (yang terlihat seperti ini: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) ke peran "Pengguna Vertex AI". PROJECT_NUMBER akan memiliki nomor project Anda.
Atau, Anda dapat menjalankan perintah di bawah dari Terminal Cloud Shell:
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"
Mendaftarkan model Gemini 3 Flash di AlloyDB
Jalankan pernyataan SQL di bawah dari Editor Kueri AlloyDB
CALL google_ml.create_model(
model_id => 'gemini-3-flash-preview',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/<<YOUR_PROJECT_ID>>/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent',
model_qualified_name => 'gemini-3-flash-preview',
model_provider => 'google',
model_type => 'llm',
model_auth_type => 'alloydb_service_agent_iam'
);
--replace <<YOUR_PROJECT_ID>> with your project id.
Gotcha & Pemecahan Masalah
Loop "Lupa Sandi" | Jika Anda menggunakan penyiapan "Satu Klik" dan tidak dapat mengingat sandi, buka halaman Informasi dasar instance di konsol dan klik "Edit" untuk mereset sandi |
Error "Ekstensi Tidak Ditemukan" | Jika |
IAM Propagation Gap | Anda menjalankan perintah IAM |
Ketidakcocokan Dimensi Vektor | Tabel |
Kesalahan Pengetikan Project ID | Dalam panggilan |
5. Penyimpanan Gambar (Google Cloud Storage)
Untuk menyimpan foto barang surplus kami, kami menggunakan bucket GCS. Untuk tujuan aplikasi demo ini, kita ingin gambar dapat diakses secara publik sehingga dirender secara instan di kartu geser kita.
- Buat Bucket: Buat bucket baru di project GCP Anda (misalnya, neighborloop-images), sebaiknya di region yang sama dengan database dan aplikasi Anda.
- Konfigurasi Akses Publik: * Buka tab Izin bucket.
- Tambahkan prinsipal allUsers.
- Tetapkan peran Storage Object Viewer (agar semua orang dapat melihat foto) dan peran Storage Object Creator (untuk tujuan upload demo).
Alternatif (Akun Layanan): Jika Anda memilih untuk tidak menggunakan akses publik, pastikan Akun Layanan aplikasi Anda diberi akses penuh ke AlloyDB dan peran Storage yang diperlukan untuk mengelola objek secara aman.
Gotcha & Pemecahan Masalah
Penarikan Wilayah | Jika database Anda berada di |
Keunikan Nama Bucket | Nama bucket adalah namespace global. Jika Anda mencoba memberi nama bucket Anda |
Kesalahan "Kreator" vs. "Penonton" | Kesalahan "Kreator" vs. "Pelihat": Jika Anda hanya menambahkan "Pelihat", aplikasi Anda akan error saat pengguna mencoba mencantumkan item baru karena tidak memiliki izin untuk menulis file. Anda memerlukan keduanya untuk penyiapan demo khusus ini. |
6. Mari kita buat aplikasi
Clone repo ini ke project Anda dan mari kita bahas.
- Untuk meng-clone-nya, dari Terminal Cloud Shell (di direktori root atau dari tempat Anda ingin membuat project ini), jalankan perintah berikut:
git clone https://github.com/AbiramiSukumaran/neighbor-loop
Tindakan ini akan membuat project dan Anda dapat memverifikasinya di Cloud Shell Editor.
- Cara mendapatkan Kunci Gemini API Anda
- Buka Google AI Studio: Buka aistudio.google.com.
- Login: Gunakan Akun Google yang sama dengan yang Anda gunakan untuk project Google Cloud Anda.
- Buat Kunci API:
- Di sidebar sebelah kiri, klik "Dapatkan kunci API".
- Klik tombol "Create API key in new project".
- Salin Kunci: Setelah kunci dibuat, klik ikon salin.
- Sekarang tetapkan variabel lingkungan dalam file .env
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Ganti nilai untuk placeholder <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Gotcha & Pemecahan Masalah
Kebingungan Terhadap Beberapa Akun | Jika Anda login ke beberapa akun Google (Pribadi vs. Kerja), AI Studio mungkin menggunakan akun yang salah secara default. Periksa avatar di sudut kanan atas untuk memastikan avatar tersebut cocok dengan akun Project GCP Anda. |
Terlampaui Kuota "Free Tier" | Jika Anda menggunakan tingkat Bebas Biaya, ada batas kecepatan (RPM - Permintaan Per Menit). Jika Anda "menggeser" terlalu cepat di Neighbor Loop, Anda mungkin akan mendapatkan error |
Keamanan Kunci yang Terekspos | Jika Anda secara tidak sengaja |
Void "Waktu Tunggu Koneksi Habis" | Anda menggunakan alamat IP Pribadi di file .env, tetapi Anda mencoba terhubung dari luar VPC (seperti mesin lokal Anda). IP pribadi hanya dapat dijangkau dari dalam jaringan Google Cloud yang sama. Beralih ke IP Publik. |
Asumsi Port 5432 | Meskipun 5432 adalah port PostgreSQL standar, AlloyDB terkadang memerlukan konfigurasi port tertentu jika Anda menggunakan Proxy Auth. Untuk lab ini, pastikan Anda menggunakan :5432 di akhir string host. |
Penjaga Gerbang "Jaringan yang Diizinkan" | Meskipun Anda memiliki IP Publik, AlloyDB akan "Menolak Koneksi" kecuali jika Anda telah memasukkan alamat IP mesin yang menjalankan kode ke dalam daftar yang diizinkan.Perbaikan: Di setelan instance AlloyDB, tambahkan 0.0.0.0/0 (hanya untuk pengujian sementara!) atau IP spesifik Anda ke Jaringan yang Diizinkan. |
Kegagalan Handshake SSL/TLS | AlloyDB lebih memilih koneksi yang aman. Jika DATABASE_URL Anda tidak menentukan driver dengan benar (seperti menggunakan pg8000), handshake mungkin gagal tanpa pemberitahuan, sehingga Anda akan mendapatkan error "Database tidak dapat dijangkau" yang umum. |
Pengalihan "Primary vs. Read Pool" | Jika Anda secara tidak sengaja menyalin alamat IP Read Pool, bukan Primary Instance, aplikasi Anda akan berfungsi untuk menelusuri item, tetapi akan error dengan pesan "Read-only" saat Anda mencoba mencantumkan item baru. Selalu gunakan IP Instance Utama untuk penulisan. |
7. Mari kita periksa kodenya
"Profil Kencan" untuk Barang Anda
Saat pengguna mengupload foto item, mereka tidak perlu menulis deskripsi yang panjang. Saya menggunakan Gemini 3 Flash untuk "melihat" item dan menulis listingannya.
Di backend, pengguna hanya memberikan judul dan foto. Gemini akan menangani sisanya:
prompt = """
You are a witty community manager for NeighborLoop.
Analyze this surplus item and return JSON:
{
"bio": "First-person witty dating-style profile bio for the product, not longer than 2 lines",
"category": "One-word category",
"tags": ["tag1", "tag2"]
}
"""
response = genai_client.models.generate_content(
model="gemini-3-flash-preview",
contents=[types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"), prompt],
config=types.GenerateContentConfig(response_mime_type="application/json")
)
Penyematan Dalam Database Real-time
Salah satu fitur paling keren AlloyDB adalah kemampuan untuk membuat embedding tanpa keluar dari konteks SQL. Daripada memanggil model embedding di Python dan mengirim vektor kembali ke DB, saya melakukannya semua dalam satu pernyataan INSERT menggunakan fungsi embedding():
INSERT INTO items (owner_id, provider_name, provider_phone, title, bio, category, image_url, status, item_vector)
VALUES (
:owner, :name, :phone, :title, :bio, :cat, :url, 'available',
embedding('text-embedding-005', :title || ' ' || :bio)::vector
)
Hal ini memastikan bahwa setiap item dapat "ditelusuri" berdasarkan maknanya segera setelah diposting. Perhatikan bahwa bagian ini mencakup fitur "mencantumkan produk" di aplikasi Neighbor Loop.
Penelusuran Vektor Lanjutan dan Pemfilteran Cerdas dengan Gemini 3.0
Penelusuran kata kunci standar terbatas. Jika Anda menelusuri "sesuatu untuk memperbaiki kursi saya", database tradisional mungkin tidak menampilkan apa pun jika kata "kursi" tidak ada dalam judul. Neighbor Loop memecahkan masalah ini dengan penelusuran vektor canggih AlloyDB AI.
Dengan menggunakan ekstensi pgvector dan penyimpanan yang dioptimalkan AlloyDB, kita dapat melakukan penelusuran kemiripan yang sangat cepat. Namun, "keajaiban" yang sebenarnya terjadi saat kita menggabungkan kedekatan vektor dengan logika berbasis LLM.
AlloyDB AI memungkinkan kita memanggil model seperti Gemini langsung dalam kueri SQL kita. Artinya, kita dapat melakukan Penemuan Semantik yang mencakup "pemeriksaan kewarasan" berbasis logika menggunakan fungsi ai.if():
SELECT item_id, title, bio, category, image_url,
1 - (item_vector <=> embedding('text-embedding-005', :query)::vector) as score
FROM items
WHERE status = 'available'
AND item_vector IS NOT NULL
AND ai.if(
prompt => 'Does this text: "' || bio ||'" match the user request: "' || :query || '", at least 60%? "',
model_id => 'gemini-3-flash-preview'
)
ORDER BY score DESC
LIMIT 5
Kueri ini mewakili perubahan arsitektur yang signifikan: kita memindahkan logika ke data. Daripada menarik ribuan hasil ke dalam kode aplikasi untuk memfilternya, Gemini 3 Flash melakukan "pengecekan suasana" di dalam mesin database. Tindakan ini mengurangi latensi, menurunkan biaya traffic keluar, dan memastikan bahwa hasilnya tidak hanya serupa secara matematis, tetapi juga relevan secara kontekstual.
Loop "Geser untuk Mencocokkan"
UI adalah setumpuk kartu klasik.
Geser ke Kiri: Batalkan.
Geser ke Kanan: Anda cocok!
Saat Anda menggeser ke kanan, backend akan mencatat interaksi di tabel geser kami dan menandai item sebagai cocok. Frontend akan langsung memicu modal yang menampilkan info kontak penyedia sehingga Anda dapat mengatur pengambilan.
8. Mari kita deploy ke Cloud Run
- Deploy di Cloud Run dengan menjalankan perintah berikut dari Terminal Cloud Shell tempat project di-clone dan pastikan Anda berada di dalam folder root project.
Jalankan perintah ini di terminal Cloud Shell Anda:
gcloud beta run deploy neighbor-loop \
--source . \
--region=us-central1 \
--network=<<YOUR_NETWORK_NAME>> \
--subnet=<<YOUR_SUBNET_NAME>> \
--allow-unauthenticated \
--vpc-egress=all-traffic \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:<<PORT>>/postgres,GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Ganti nilai untuk placeholder <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Setelah perintah selesai, URL Layanan akan ditampilkan. Salin.
- Berikan peran Klien AlloyDB ke akun layanan Cloud Run.Dengan demikian, aplikasi serverless Anda dapat membuat tunnel ke database dengan aman.
Jalankan perintah ini di terminal Cloud Shell Anda:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
Sekarang gunakan URL layanan (endpoint Cloud Run yang Anda salin sebelumnya) dan uji aplikasi. Upload foto alat listrik lama tersebut, dan biarkan Gemini melakukan sisanya.
Gotcha & Pemecahan Masalah
Loop "Revisi Gagal" | Jika deployment selesai, tetapi URL menampilkan |
Peran "Shadow" IAM | Meskipun Anda memiliki izin untuk men-deploy, Akun Layanan Cloud Run (biasanya |
9. Pemecahan Masalah Tingkat Tinggi
10. Demo
Anda akan dapat menggunakan endpoint untuk pengujian.
Namun, untuk tujuan demo selama beberapa hari, Anda dapat mencoba ini:
11. Pembersihan
Setelah lab ini selesai, jangan lupa untuk menghapus cluster dan instance AlloyDB.
Tindakan ini akan membersihkan cluster beserta instance-nya.
12. Selamat
Anda telah berhasil membuat aplikasi Neighbor Loop untuk komunitas berkelanjutan dengan Google Cloud. Dengan memindahkan logika AI embedding dan Gemini 3 Flash ke AlloyDB, aplikasi menjadi sangat cepat (bergantung pada setelan deployment) dan kodenya sangat rapi. Kami tidak hanya menyimpan data, tetapi juga menyimpan niat.
Kombinasi kecepatan Gemini 3 Flash dan pemrosesan vektor yang dioptimalkan AlloyDB benar-benar merupakan terobosan baru untuk platform berbasis komunitas.