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 integrasi ML Cloud SQL, Anda akan melampaui penyimpanan dasar ke ranah In-Database Intelligence. Anda akan mempelajari cara melakukan analisis item multimodal dan penemuan semantik langsung dalam SQL.
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 Cloud SQL dan instance yang dirancang untuk beban kerja 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 lapisan aplikasi tradisional. Daripada menarik data untuk diproses, kita menggunakan:
- Integrasi Cloud SQL + ML: 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. Cloud SQL tidak akan dimulai jika penagihan kosong. |
Keterlambatan Penyebaran API | Anda mengklik "Aktifkan API", tetapi command line masih menampilkan |
3. Penyiapan database
Di lab ini, kita akan menggunakan Cloud SQL untuk PostgreSQL sebagai database untuk data pengujian.
Mari kita buat instance Cloud SQL 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 ID project dan nama instance untuk memulai.
- Pergilah minum kopi sambil melihat log yang bergulir dan Anda dapat membaca tentang cara kerjanya di balik layar di sini.
Gotcha & Pemecahan Masalah
Ketidakcocokan Region | Jika Anda mengaktifkan API di |
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 instance Cloud SQL Anda berjalan, buka editor SQL Cloud SQL Studio untuk mengaktifkan ekstensi AI dan menyediakan skema.
Anda mungkin perlu menunggu hingga instance selesai dibuat. Setelah itu, login ke instance Cloud SQL menggunakan kredensial yang Anda buat saat membuatnya. Gunakan data berikut untuk melakukan autentikasi ke PostgreSQL:
- Nama pengguna : "
postgres" - Database : "
postgres" - Sandi : "
cloudsql" (atau apa pun yang Anda tetapkan pada saat pembuatan)
Setelah Anda berhasil diautentikasi ke Cloud SQL 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 Cloud SQL 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 ini di Cloud SQL 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;
Mengaktifkan Integrasi ML
Untuk memanfaatkan fitur machine learning langsung dalam database, Anda harus mengaktifkan tanda integrasi ML.
Anda dapat menjalankan perintah di bawah dari Terminal Cloud Shell:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
gcloud sql instances patch $INSTANCE_NAME --tier=db-custom-1-3840
gcloud sql instances patch $INSTANCE_NAME \
--database-flags=cloudsql.enable_google_ml_integration=on
gcloud sql instances patch $INSTANCE_NAME --enable-google-ml-integration
Memberikan PERAN Vertex AI User ke akun layanan Cloud SQL
Dari konsol IAM Google Cloud, berikan akses ke akun layanan Cloud SQL (yang terlihat seperti ini: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.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:
INSTANCE_NAME="<<The name of your Cloud SQL Instance>>"
PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format='value(serviceAccountEmailAddress)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SA_EMAIL" \
--role="roles/aiplatform.user"
Mendaftarkan model Gemini 3 Flash di Cloud SQL
Jalankan pernyataan SQL di bawah dari Editor Kueri Cloud SQL
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 => 'generic',
model_auth_type => 'cloudsql_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 |
Integrasi Vertex AI dinonaktifkan | Jalankan |
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 tidak ingin menggunakan akses publik, pastikan Akun Layanan aplikasi Anda diberi akses penuh ke Cloud SQL dan peran Storage yang diperlukan untuk mengelola objek dengan aman.
Jika Anda ingin menjalankan perintah dan memberikan akses publik. Jalankan perintah di bawah ini di Terminal Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
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 Cloud Shell Terminal Anda (di direktori root atau dari tempat mana pun Anda ingin membuat project ini), jalankan perintah berikut satu per satu:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
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 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 frekuensi (RPM - Permintaan Per Menit). Jika Anda "menggeser" terlalu cepat di Neighbor Loop, Anda mungkin akan mendapatkan error |
Keamanan Kunci yang Terekspos | Jika Anda tidak sengaja |
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 dari Cloud SQL adalah kemampuan untuk membuat penyematan 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 AI Cloud SQL.
Dengan menggunakan ekstensi pgvector dan penyimpanan yang dioptimalkan Cloud SQL, kita dapat melakukan penelusuran kemiripan yang sangat cepat. Namun, "keajaiban" yang sebenarnya terjadi saat kita menggabungkan kedekatan vektor dengan logika berbasis LLM.
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
ORDER BY score DESC
LIMIT 5
Kueri ini merepresentasikan 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. Hal 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 Cloud Shell Terminal tempat project di-clone dan pastikan Anda berada di dalam folder root project.
Jalankan perintah ini di terminal Cloud Shell Anda:
gcloud run deploy neighbor-loop-cloud-sql \
--source . \
--region=us-central1 \
--allow-unauthenticated \
--network=easy-cloudsql-vpc \
--subnet=easy-cloudsql-subnet \
--vpc-egress=private-ranges-only \
--set-env-vars GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>,DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<PRIVATE_IP_HOST>>:5432/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.
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 |
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 instance Cloud SQL.
12. Selamat
Anda telah berhasil membangun aplikasi Neighbor Loop untuk komunitas berkelanjutan dengan Google Cloud. Dengan memindahkan logika AI Gemini 3 Flash dan penyematan ke Cloud SQL, aplikasi menjadi sangat cepat (bergantung pada setelan deployment) dan kodenya sangat bersih. Kami tidak hanya menyimpan data, tetapi juga menyimpan niat.
Kombinasi kecepatan Gemini 3 Flash dan pemrosesan vektor yang dioptimalkan Cloud SQL benar-benar merupakan terobosan baru untuk platform berbasis komunitas.