1. Genel Bakış
Bu codelab'de, ölçeklenebilir bir bilgi bankası arama uygulaması oluşturacaksınız. Vektör yerleştirmeleri oluşturmak için Python komut dosyaları ve döngüler içeren karmaşık bir ETL ardışık düzenini yönetmek yerine, tek bir SQL komutu kullanarak veritabanında yerleştirme oluşturma işlemini yerel olarak gerçekleştirmek için AlloyDB AI'ı kullanacaksınız.

Ne oluşturacaksınız?
Yüksek performanslı ve "aranabilir" bir bilgi bankası veritabanı uygulaması.
Neler öğreneceksiniz?
Şunları öğreneceksiniz:
- AlloyDB kümesi temel hazırlığı yapma ve yapay zeka uzantılarını etkinleştirme
- SQL kullanarak sentetik veriler (50.000'den fazla satır) oluşturun.
- Toplu İşleme'yi kullanarak tüm veri kümesi için vektör yerleştirmelerini doldurun.
- Yeni verileri otomatik olarak yerleştirmek için Gerçek Zamanlı Analiz Artımlı Tetikleyicileri ayarlayın.
- "Flexing Context" için karma arama (vektör + SQL filtreleri) gerçekleştirme
Şartlar
2. Başlamadan önce
Proje oluşturma
- Google Cloud Console'da, proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
- Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğiniziöğrenin.
- Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

- Cloud Shell'e bağlandıktan sonra, kimliğinizin doğrulandığını ve projenin, proje kimliğinize ayarlandığını aşağıdaki komutu kullanarak kontrol edebilirsiniz:
gcloud auth list
- gcloud komutunun projenizi tanıdığını doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
- Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
- Gerekli API'leri etkinleştirin: Bağlantıyı takip edin ve API'leri etkinleştirin.
Alternatif olarak, bunun için gcloud komutunu kullanabilirsiniz. gcloud komutları ve kullanımı için belgeleri inceleyin.
gcloud services enable \
alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Hayalet Proje" Sendromu |
|
Faturalandırma Engeli | Projeyi etkinleştirdiniz ancak faturalandırma hesabını unuttunuz. AlloyDB, yüksek performanslı bir motordur. "Yakıt deposu" (faturalandırma) boşsa çalışmaz. |
API yayılma gecikmesi | "API'leri etkinleştir"i tıkladınız ancak komut satırında hâlâ |
Kota sorunları | Yeni bir deneme hesabı kullanıyorsanız AlloyDB örnekleri için bölgesel bir kotaya ulaşabilirsiniz. |
"Gizli" hizmet aracısı | Bazen AlloyDB hizmet aracısına |
3. Veritabanı kurulumu
Bu laboratuvarda, test verilerinin veritabanı olarak AlloyDB'yi kullanacağız. Veritabanları ve günlükler gibi tüm kaynakları tutmak için kümeleri kullanır. Her kümede, verilere erişim noktası sağlayan bir birincil örnek bulunur. Tablolarda gerçek veriler bulunur.
Test veri kümesinin yükleneceği bir AlloyDB kümesi, örneği ve tablosu oluşturalım.
- Düğmeyi tıklayın veya aşağıdaki bağlantıyı kopyalayıp Google Cloud Console kullanıcısının oturum açtığı tarayıcıya yapıştırın.
- Bu adım tamamlandıktan sonra depo, yerel Cloud Shell düzenleyicinize klonlanır ve aşağıdaki komutu proje klasöründen çalıştırabilirsiniz (proje dizininde olduğunuzdan emin olun):
sh run.sh
- Şimdi kullanıcı arayüzünü kullanın (terminaldeki bağlantıyı veya terminaldeki "web'de önizle" bağlantısını tıklayın).
- Başlamak için proje kimliği, küme ve örnek adlarıyla ilgili bilgilerinizi girin.
- Günlükler kaydırılırken gidip bir kahve alın. Bu işlemin kamera arkasında nasıl yapıldığını buradan okuyabilirsiniz. Bu işlem yaklaşık 10-15 dakika sürebilir.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Sabır" Sorunu | Veritabanı kümeleri ağır altyapılardır. Sayfayı yenilerseniz veya "takılmış gibi göründüğü" için Cloud Shell oturumunu sonlandırırsanız kısmen temel hazırlığı yapılmış ve manuel müdahale olmadan silinmesi imkansız olan bir "hayalet" örnekle karşılaşabilirsiniz. |
Bölge uyuşmazlığı | API'lerinizi |
Zombi Kümeler | Daha önce bir küme için aynı adı kullandıysanız ve bu kümeyi silmediyseniz komut dosyası, küme adının zaten mevcut olduğunu belirtebilir. Küme adları bir proje içinde benzersiz olmalıdır. |
Cloud Shell Zaman Aşımı | Kahve molanız 30 dakika sürerse Cloud Shell uyku moduna geçebilir ve |
4. Şema Temel Hazırlığı
Bu adımda aşağıdaki konuları ele alacağız:

AlloyDB kümeniz ve örneğiniz çalışmaya başladıktan sonra AlloyDB Studio SQL düzenleyicisine giderek yapay zeka uzantılarını etkinleştirin ve şemayı sağlayın.
Örneğin oluşturulma işleminin tamamlanmasını beklemeniz gerekebilir. Küme oluşturulduktan sonra, kümeyi oluştururken belirlediğiniz kimlik bilgilerini kullanarak AlloyDB'de oturum açın. PostgreSQL'de kimlik doğrulaması yapmak için aşağıdaki verileri kullanın:
- Kullanıcı adı : "
postgres" - Veritabanı : "
postgres" - Şifre : "
alloydb" (veya oluşturma sırasında belirlediğiniz şifre)
AlloyDB Studio'da kimlik doğrulama işlemini başarıyla tamamladıktan sonra SQL komutları düzenleyiciye girilir. Son pencerenin sağındaki artı simgesini kullanarak birden fazla Düzenleyici penceresi ekleyebilirsiniz.

AlloyDB komutlarını düzenleyici pencerelerine girerken gerektiğinde Çalıştır, Biçimlendir ve Temizle seçeneklerini kullanacaksınız.
Uzantıları etkinleştirme
Bu uygulamayı oluşturmak için pgvector ve google_ml_integration uzantılarını kullanacağız. pgvector uzantısı, vektör yerleştirmelerini depolamanıza ve aramanıza olanak tanır. google_ml_integration uzantısı, SQL'de tahmin almak için Vertex AI tahmin uç noktalarına erişmek amacıyla kullandığınız işlevleri sağlar. Aşağıdaki DDL'leri çalıştırarak bu uzantıları etkinleştirin:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Tablo oluşturma
Ölçeği göstermek için bir veri kümesine ihtiyacımız var. CSV dosyası içe aktarmak yerine SQL kullanarak anında 50.000 satırlık yapay "Yardım Makaleleri" oluşturacağız.
AlloyDB Studio'da aşağıdaki DDL ifadesini kullanarak tablo oluşturabilirsiniz:
-- 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;
item_vector sütunu, metnin vektör değerlerinin depolanmasına olanak tanır.
Verileri doğrulayın:
SELECT count(*) FROM help_articles;
-- Output: 50000
Veritabanı İşaretlerini Etkinleştirme
Örnek yapılandırma konsoluna gidin, "Edit Primary"yi (Birincili Düzenle) tıklayın, Advanced Configuration'a (Gelişmiş Yapılandırma) gidin ve "Add Database Flags"i (Veritabanı İşaretleri Ekle) tıklayın.
Değilse işaretler açılır menüsüne girip "AÇIK" olarak ayarlayın ve örneği güncelleyin.
Değilse işaretler açılır menüsüne girip "AÇIK" olarak ayarlayın ve örneği güncelleyin.
Veritabanı işaretlerini yapılandırma adımları:
- Google Cloud Console'da Kümeler sayfasına gidin.
- Kaynak Adı sütununda bir kümeyi tıklayın.
- Genel bakış sayfasında, kümenizdeki Örnekler'e gidin, bir örnek seçin ve ardından Düzenle'yi tıklayın.
- Örneğinize veritabanı işareti ekleme, değiştirme veya silme:
İşaret ekleme
- Örneğinize veritabanı işareti eklemek için Add flag'i (İşaret ekle) tıklayın.
- Yeni veritabanı işareti listesinden bir işaret seçin.
- İşaret için bir değer girin.
- Bitti'yi tıklayın.
- Örneği güncelle'yi tıklayın.
- google_ml_integration uzantısının 1.5.2 veya sonraki bir sürüm olduğunu doğrulayın:
Uzantı sürümünüzü kontrol etmek için aşağıdaki komutu kullanın:
SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
Uzantıyı daha yüksek bir sürüme güncellemeniz gerekiyorsa şu komutu kullanın:
ALTER EXTENSION google_ml_integration UPDATE;
İzin Ver
- Bir kullanıcının otomatik yerleştirme oluşturmayı yönetmesine izin vermek için google_ml.embed_gen_progress ve google_ml.embed_gen_settings tablolarında INSERT, UPDATE ve DELETE izinleri verin:
GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO postgres;
"postgres", izinlerin verildiği KULLANICI_ADI'dır.
- "embedding" işlevinde yürütme izni vermek için aşağıdaki ifadeyi çalıştırın:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
AlloyDB hizmet hesabına Vertex AI Kullanıcısı rolünü verme
Google Cloud IAM konsolundan, AlloyDB hizmet hesabına (service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com şeklinde görünür) "Vertex AI Kullanıcısı" rolüne erişim izni verin. PROJECT_NUMBER, proje numaranızı içerir.
Alternatif olarak Cloud Shell terminalinden aşağıdaki komutu çalıştırabilirsiniz:
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"
Dikkat Edilmesi Gerekenler ve Sorun Giderme
"Şifre Unutma" Döngüsü | "Tek Tıkla" kurulumunu kullandıysanız ve şifrenizi hatırlamıyorsanız konsoldaki örnek temel bilgiler sayfasına gidip "Düzenle"yi tıklayarak |
"Uzantı Bulunamadı" Hatası |
|
5. "Tek Atış" Vektör Oluşturma
Bu, laboratuvarın temelini oluşturur. Bu 50.000 satırı işlemek için Python döngüsü yazmak yerine ai.initialize_embeddings işlevini kullanacağız.
Bu tek komut iki işlem gerçekleştirir:
- Mevcut tüm satırları doldurur.
- Gelecekteki satırları otomatik olarak yerleştirmek için tetikleyici oluşturur.
AlloyDB Sorgu Düzenleyici'den aşağıdaki SQL ifadesini çalıştırın.
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional'
);
Yerleştirmeleri doğrulama
embedding sütununun doldurulduğunu kontrol edin:
SELECT id, left(content_body, 30), substring(embedding::text, 1, 30) as vector_partial
FROM help_articles;
Aşağıdakine benzer bir sonuç görürsünüz:

Az önce ne oldu?
- Geniş ölçekte doldurma: Mevcut 50.000 satırınızı otomatik olarak tarar ve Vertex AI aracılığıyla yerleştirmeler oluşturur.
- Otomasyon: incremental_refresh_mode => 'transactional' ayarını yaptığınızda AlloyDB, dahili tetikleyicileri otomatik olarak ayarlar. help_articles tablosuna eklenen her yeni satırın yerleştirmesi anında oluşturulur.
- İsteğe bağlı olarak incremental_refresh_mode => "None" değerini ayarlayabilirsiniz. Böylece, yalnızca toplu güncelleme yapmak için ifadeyi alabilir ve tüm satır yerleştirmelerini güncellemek için ai.refresh_embeddings() işlevini manuel olarak çağırabilirsiniz.
Kafka kuyruğu, Python çalışanı ve taşıma komut dosyasını 6 satırlık SQL ile değiştirdiniz. Tüm özelliklerle ilgili ayrıntılı resmi belgeleri burada bulabilirsiniz.
Gerçek Zamanlı Tetikleyici Testi
"Sıfır Döngü" otomasyonunun yeni veriler için çalıştığını doğrulayalım.
- Yeni satır ekleme:
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.');
- Hemen kontrol edin:
SELECT embedding FROM help_articles WHERE title = 'New Scaling Guide';
Sonuç:
Herhangi bir harici komut dosyası çalıştırmadan vektörün anında oluşturulduğunu görürsünüz.
İnce Ayar Toplu İş Boyutu
AlloyDB'de varsayılan toplu işlem boyutu 50'dir. Varsayılan ayarlar kullanıma hazır şekilde mükemmel çalışsa da AlloyDB, kullanıcılara benzersiz modeliniz ve veri kümeniz için mükemmel yapılandırmayı ayarlama kontrolü sunar.
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
);
Ancak kullanıcıların, performansı sınırlayabilecek kota sınırlarına dikkat etmesi gerekir. Önerilen AlloyDB kotalarını incelemek için belgelerdeki "Başlamadan önce" bölümüne bakın.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
IAM yayılma boşluğu |
|
Vektör Boyutu Uyuşmazlığı |
|
6. Flexing Context Search
Şimdi karma arama yapalım. Semantik anlayışı (vektör) işletme mantığıyla (SQL filtreleri) birleştiririz.
Özellikle Ürün Sürümü 2.0 ile ilgili faturalandırma sorunlarını bulmak için bu sorguyu çalıştırın:
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;
Bu, esnek bağlamdır. Arama, katı işletme kısıtlamalarına (Sürüm 2.0) uyarken kullanıcının amacını ("faturalandırma sorunları") anlamak için "esner".

Bu yaklaşım, yeni başlayanlar ve taşıma işlemleri için neden avantajlıdır?
- Sıfır altyapı borcu: Ayrı bir vektör veritabanı (Pinecone/Milvus) oluşturmadınız. Ayrı bir ETL işi yazmadınız. Hepsi Postgres'te.
- Gerçek Zamanlı Güncellemeler: "İşlemsel" modu kullanarak arama dizininizin her zaman güncel kalmasını sağlayabilirsiniz. Veriler kaydedildiği anda vektör aramasına hazır hale gelir.
- Ölçek: AlloyDB, Google'ın altyapısı üzerine inşa edilmiştir. Milyonlarca vektörün toplu olarak oluşturulmasını Python komut dosyanızdan daha hızlı bir şekilde gerçekleştirebilir.
Dikkat Edilmesi Gerekenler ve Sorun Giderme
Üretim Performansı ile İlgili Dikkat Edilmesi Gerekenler | Sorun: 50.000 satır için hızlı. Kategori filtresi yeterince seçici değilse 1 milyon satır için çok yavaş.Çözüm:Vektör dizini ekleyin: Üretim ölçeği için bir dizin oluşturmanız gerekir:CREATE INDEX ON help_articles USING hnsw (embedding vector_cosine_ops);Dizin kullanımını doğrulayın: Veritabanının dizini kullandığından ve sıralı tarama yapmadığından emin olmak için |
"Model Uyuşmazlığı" Felaketi | Sorun: CALL prosedüründe text-embedding-005'i kullanarak sütunu başlattınız. SELECT sorgu işlevi embedding('model-name', ...) içinde yanlışlıkla farklı bir model (ör. text-embedding-004 veya bir OSS modeli) kullanırsanız boyutlar eşleşebilir (768) ancak vektör uzayı tamamen farklı olur. Sorgu hatasız çalışır ancak sonuçlar tamamen alakasızdır (alakasız alaka düzeyi puanları). Sorun giderme:ai.initialize_embeddings içindeki model_id değerinin SELECT sorgunuzdaki model_id değeriyle tam olarak eşleştiğinden emin olun. |
"Silent Empty" sonucu (aşırı filtreleme) | Sorun: Karma arama bir "VE" işlemidir. Semantik eşleşme VE SQL eşleşmesi gerektirir. Kullanıcı "Faturalandırma yardımı" araması yaparsa ancak
|
4. İzin/Kota Hataları (500 Hatası) | Sorun:
|
5. Boş Yerleştirmeler | Sorun:Model tamamen başlatılmadan önce veri eklerseniz veya arka plan çalışanı başarısız olursa bazı satırların
|
7. Temizleme
Bu laboratuvar tamamlandıktan sonra AlloyDB kümesini ve örneğini silmeyi unutmayın.
Bu komut, kümeyi ve örneklerini temizler.
8. Tebrikler
Ölçeklenebilir bir bilgi bankası arama uygulamasını başarıyla oluşturdunuz. Vektör yerleştirmeleri oluşturmak için Python komut dosyaları ve döngülerle karmaşık bir ETL ardışık düzenini yönetmek yerine, tek bir SQL komutu kullanarak yerleştirme oluşturma işlemini doğrudan veritabanında gerçekleştirmek için AlloyDB AI'ı kullandınız.
İşlediğimiz konular
- Veri işleme için "Python For-Loop"u kullanımdan kaldırdık.
- Tek bir SQL komutuyla 50.000 vektör oluşturduk.
- Tetikleyicilerle gelecekteki vektör oluşturma işlemlerini otomatikleştirdik.
- Karma arama yaptık.
Sonraki Adımlar
- Bunu kendi veri kümenizle deneyin.
- AlloyDB AI belgelerini inceleyin.
- Daha fazla atölye için Code Vipassana web sitesine göz atın.