1. Ringkasan
Dalam codelab ini, Anda akan membangun aplikasi penelusuran Pusat Informasi yang skalabel. Alih-alih mengelola pipeline ETL yang kompleks dengan skrip dan loop Python untuk menghasilkan embedding vektor, Anda akan menggunakan AlloyDB AI untuk menangani pembuatan embedding secara native dalam database menggunakan satu perintah SQL.
Yang akan Anda build
Aplikasi database pusat informasi "yang dapat ditelusuri" dan berperforma tinggi.
Yang akan Anda pelajari
Anda akan mempelajari cara:
- Menyediakan Cluster AlloyDB dan mengaktifkan ekstensi AI.
- Membuat data sintetis (lebih dari 50.000 baris) menggunakan SQL.
- Mengisi ulang embedding vektor untuk seluruh set data menggunakan Batch Processing.
- Siapkan Pemicu Inkremental Real-Time untuk menyematkan data baru secara otomatis.
- Lakukan Penelusuran Campuran (Filter Vektor + SQL) untuk "Flexing Context".
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, periksa apakah 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.
gcloud services enable \
alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com
Gotcha & Pemecahan Masalah
Sindrom "Ghost Project" | Anda menjalankan |
Penghalang Penagihan | Anda mengaktifkan project, tetapi lupa akun penagihan. AlloyDB adalah mesin berperforma tinggi; mesin ini tidak akan menyala jika "tangki bahan bakar" (penagihan) kosong. |
Jeda Penyebaran API | Anda mengklik "Enable APIs", tetapi command line masih menampilkan |
Kuota Quags | Jika menggunakan akun uji coba 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. Alat ini 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, repositori akan di-clone ke editor Cloud Shell lokal Anda dan Anda akan dapat menjalankan perintah di bawah dari dalam folder project (penting untuk memastikan Anda berada di direktori project):
sh run.sh
- Sekarang gunakan UI (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 menunggu log di-scroll & Anda dapat membaca cara kerjanya di balik layar di sini. Proses ini mungkin memerlukan waktu sekitar 10-15 menit.
Gotcha & Pemecahan Masalah
Masalah "Kesabaran" | Cluster database adalah infrastruktur yang berat. Jika Anda memuat ulang halaman atau menghentikan sesi Cloud Shell karena "terlihat macet", Anda mungkin akan mendapatkan instance "hantu" yang disediakan sebagian dan tidak dapat dihapus tanpa intervensi manual. |
Region Tidak Cocok | 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 sebuah project. |
Waktu Tunggu Cloud Shell | Jika Anda beristirahat selama 30 menit, Cloud Shell mungkin akan beralih ke mode tidur dan memutuskan proses |
4. Penyediaan Skema
Pada langkah ini, kita akan membahas hal berikut:
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 itu, login ke AlloyDB menggunakan kredensial yang Anda buat saat membuat cluster. Gunakan data berikut untuk melakukan autentikasi ke PostgreSQL:
- Nama pengguna : "
postgres" - Database : "
postgres" - Password : "
alloydb" (atau apa pun yang Anda tetapkan pada saat pembuatan)
Setelah Anda berhasil melakukan autentikasi ke AlloyDB Studio, perintah SQL akan 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 Run, Format, dan Clear 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
Kita memerlukan set data untuk menunjukkan skala. Daripada mengimpor CSV, kita akan membuat 50.000 baris "Artikel Bantuan" sintetis secara instan menggunakan SQL.
Anda dapat membuat tabel menggunakan pernyataan DDL di bawah di AlloyDB Studio:
-- 1. Create the table
CREATE TABLE help_articles (
id SERIAL PRIMARY KEY,
title TEXT,
category TEXT,
product_version TEXT,
content_body TEXT,
embedding vector(768) -- Dimension for text-embedding-005
);
-- 2. Generate 50,000 rows of synthetic data
INSERT INTO help_articles (title, category, product_version, content_body)
SELECT
'Help Article ' || i,
CASE
WHEN i % 3 = 0 THEN 'Billing'
WHEN i % 3 = 1 THEN 'Technical'
ELSE 'General'
END,
CASE
WHEN i % 2 = 0 THEN '2.0'
ELSE '1.0'
END,
'This article covers common issues regarding ' ||
CASE
WHEN i % 3 = 0 THEN 'payment failures, invoice disputes, and credit card updates.'
WHEN i % 3 = 1 THEN 'connection timeouts, latency issues, and API errors.'
ELSE 'account profile settings, password resets, and user roles.'
END
FROM generate_series(1, 50000) AS i;
Kolom item_vector akan memungkinkan penyimpanan untuk nilai vektor teks.
Verifikasi data:
SELECT count(*) FROM help_articles;
-- Output: 50000
Mengaktifkan Flag Database
Buka konsol Instance configuration, klik "Edit Primary", buka Advanced Configuration, lalu klik "Add Database Flags".
Jika belum, masukkan flag di menu drop-down, tetapkan ke "ON", lalu update instance.
Jika belum, masukkan flag di menu drop-down, tetapkan ke "ON", lalu update instance.
Langkah-langkah untuk mengonfigurasi flag database:
- Di Konsol Google Cloud, buka halaman Clusters.
- Klik cluster di kolom Resource Name.
- Di halaman Overview, buka Instances di cluster Anda, pilih instance, lalu klik Edit.
- Tambahkan, ubah, atau hapus flag database dari instance Anda:
Menambahkan tanda
- Untuk menambahkan flag database ke instance, klik Add flag.
- Pilih flag database dari daftar flag database baru.
- Berikan nilai untuk flag.
- Klik Selesai.
- Klik Update instance.
- Pastikan ekstensi google_ml_integration adalah versi 1.5.2 atau yang lebih tinggi:
Untuk memeriksa versi ekstensi Anda dengan perintah berikut:
SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
Jika Anda perlu mengupdate ekstensi ke versi yang lebih tinggi, gunakan perintah:
ALTER EXTENSION google_ml_integration UPDATE;
Berikan Izin
- Agar pengguna dapat mengelola pembuatan embedding otomatis, berikan izin INSERT, UPDATE, dan DELETE pada tabel google_ml.embed_gen_progress dan google_ml.embed_gen_settings:
GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO postgres;
‘postgres' adalah USER_NAME yang diberi 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 Google Cloud IAM, beri akun layanan AlloyDB (yang terlihat seperti ini: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) akses ke peran "Vertex AI User". 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"
Gotcha & Pemecahan Masalah
Siklus "Amnesia Sandi" | Jika Anda menggunakan penyiapan "One Click" dan tidak dapat mengingat sandi, buka halaman Instance basic information di konsol, lalu klik "Edit" untuk mereset sandi |
Error "Ekstensi Tidak Ditemukan" | Jika |
5. Pembuatan Vektor "One-Shot"
Ini adalah inti dari lab ini. Alih-alih menulis loop Python untuk memproses 50.000 baris ini, kita akan menggunakan fungsi ai.initialize_embeddings.
Satu perintah ini melakukan dua hal:
- Mengisi ulang semua baris yang ada.
- Membuat Pemicu untuk menyematkan baris mendatang secara otomatis.
Jalankan pernyataan SQL di bawah dari Editor Kueri AlloyDB
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional'
);
Memverifikasi Embedding
Pastikan kolom embedding kini telah diisi:
SELECT id, left(content_body, 30), substring(embedding::text, 1, 30) as vector_partial
FROM help_articles;
Anda akan melihat hasil yang mirip dengan berikut ini:
Apa yang baru saja terjadi?
- Backfill dalam Skala Besar: Alat ini otomatis menyisir 50.000 baris yang ada dan menghasilkan embedding melalui Vertex AI.
- Otomatisasi: Dengan menetapkan incremental_refresh_mode => 'transactional', AlloyDB akan otomatis menyiapkan pemicu internal. Setiap baris baru yang disisipkan ke help_articles akan langsung menghasilkan embedding-nya.
- Anda dapat menetapkan incremental_refresh_mode => ‘None' agar Anda hanya bisa mendapatkan pernyataan untuk melakukan update massal dan memanggil ai.refresh_embeddings() secara manual untuk mengupdate semua embedding baris.
Anda baru saja mengganti antrean Kafka, worker Python, dan skrip migrasi dengan 6 baris SQL. Berikut adalah dokumentasi resmi mendetail untuk semua atribut.
Pengujian Pemicu Real-Time
Mari kita verifikasi bahwa otomatisasi "Zero Loop" berfungsi untuk data baru.
- Menyisipkan baris baru:
INSERT INTO help_articles (title, category, product_version, content_body)
VALUES ('New Scaling Guide', 'Technical', '2.0', 'How to scale AlloyDB to millions of transactions.');
- Periksa segera:
SELECT embedding FROM help_articles WHERE title = 'New Scaling Guide';
Hasil:
Anda akan melihat vektor yang dihasilkan secara instan tanpa menjalankan skrip eksternal apa pun.
Menyesuaikan Ukuran Batch
Saat ini, AlloyDB menetapkan ukuran batch default ke 50 secara otomatis. Meskipun setelan default berfungsi dengan baik, AlloyDB tetap memberi pengguna kontrol untuk menyesuaikan konfigurasi yang sempurna untuk model dan set data unik Anda.
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional',
batch_size => 20
);
Namun, pengguna harus mengetahui batas kuota yang dapat membatasi performa. Untuk meninjau kuota AlloyDB yang direkomendasikan, lihat bagian "Sebelum memulai" dalam dokumentasi.
Gotcha & Pemecahan Masalah
Kesenjangan Propagasi IAM | Anda menjalankan perintah IAM |
Ketidakcocokan Dimensi Vektor | Tabel |
6. Penelusuran Konteks Fleksibel
Sekarang kita akan melakukan Penelusuran Campuran. Kami menggabungkan pemahaman semantik (Vektor) dengan logika bisnis (Filter SQL).
Jalankan kueri ini untuk menemukan masalah penagihan khusus untuk Product Version 2.0:
SELECT
title,
left(content_body, 100) as content_snippet,
1 - (embedding <=> embedding('text-embedding-005', 'Invoice did not go through')::vector) as relevance
FROM help_articles
WHERE category = 'Billing' -- Hard SQL Filter
AND product_version = '2.0' -- Hard SQL Filter
ORDER BY relevance DESC
LIMIT 5;
Ini adalah Konteks Fleksibel. Penelusuran "beradaptasi" untuk memahami niat pengguna ("masalah penagihan") sekaligus mematuhi batasan bisnis yang ketat (Versi 2.0).
Mengapa hal ini menguntungkan untuk Startup & Migrasi
- Zero Infrastructure Debt: Anda tidak perlu menjalankan DB Vektor terpisah (Pinecone/Milvus). Anda tidak menulis tugas ETL terpisah. Semuanya ada di Postgres.
- Pembaruan Real-Time: Dengan menggunakan mode 'transaksional', indeks penelusuran Anda tidak akan pernah usang. Saat data di-commit, data tersebut siap untuk vektor.
- Skala: AlloyDB dibangun di infrastruktur Google. Alat ini dapat menangani pembuatan massal jutaan vektor lebih cepat daripada skrip Python Anda.
Gotcha & Pemecahan Masalah
Gotcha Performa Produksi | Masalah: Cepat untuk 50.000 baris. Sangat lambat untuk 1 juta baris jika pemfilteran kategori tidak cukup selektif.Solusi:Tambahkan Indeks Vektor: Untuk skala produksi, Anda harus membuat indeks:CREATE INDEX ON help_articles USING hnsw (embedding vector_cosine_ops);Verifikasi Penggunaan Indeks: Jalankan |
Bencana "Ketidakcocokan Model" | Masalah: Anda melakukan inisialisasi kolom menggunakan text-embedding-005 dalam prosedur CALL. Jika Anda tidak sengaja menggunakan model yang berbeda (misalnya, text-embedding-004 atau model OSS) dalam fungsi kueri SELECT embedding('model-name', ...), dimensinya mungkin cocok (768), tetapi ruang vektornya akan sangat berbeda. Kueri berjalan tanpa error, tetapi hasilnya sama sekali tidak relevan (skor relevansi sampah). Pemecahan masalah:Pastikan model_id di ai.initialize_embeddings sama persis dengan model_id di kueri SELECT Anda. |
Hasil "Kosong Tanpa Pesan" (Pemfilteran Berlebihan) | Masalah: Penelusuran campuran adalah operasi "AND". Kueri ini memerlukan Pencocokan Semantik DAN Pencocokan SQL.Jika pengguna menelusuri "Bantuan penagihan", tetapi kolom
|
4. Error Izin/Kuota (Error 500) | Masalah:Fungsi
|
5. Embedding Null | Masalah:Jika Anda menyisipkan data sebelum model diinisialisasi sepenuhnya atau jika worker latar belakang gagal, beberapa baris mungkin memiliki
|
7. Pembersihan
Setelah lab ini selesai, jangan lupa untuk menghapus cluster dan instance AlloyDB.
Tindakan ini akan membersihkan cluster beserta instance-nya.
8. Selamat
Anda telah berhasil membangun aplikasi penelusuran Basis Pengetahuan yang skalabel. Alih-alih mengelola pipeline ETL yang kompleks dengan skrip dan loop Python untuk menghasilkan embedding vektor, Anda menggunakan AlloyDB AI untuk menangani pembuatan embedding secara native dalam database menggunakan satu perintah SQL.
Yang kita bahas
- Kami menghentikan "Python For-Loop" untuk pemrosesan data.
- Kami membuat 50.000 vektor dengan satu perintah SQL.
- Kami mengotomatiskan pembuatan vektor di masa mendatang dengan pemicu.
- Kami melakukan Penelusuran Campuran.
Langkah Berikutnya
- Cobalah dengan set data Anda sendiri.
- Pelajari Dokumentasi AlloyDB AI.
- Lihat situs Code Vipassana untuk mengetahui workshop lainnya.