1. Genel Bakış
Bu codelab'de, zekayı veri katmanının birinci sınıf bir öğesi olarak ele alan, sürdürülebilir bir fazla paylaşım uygulaması olan Neighbor Loop'u oluşturacaksınız.
Gemini 3.0 Flash ve Cloud SQL'in makine öğrenimi entegrasyonunu birleştirerek temel depolama alanının ötesine geçip veritabanı içi zeka alanına adım atabilirsiniz. Doğrudan SQL içinde çok formatlı öğe analizi ve semantik keşif yapmayı öğreneceksiniz.
Ne oluşturacaksınız?
Toplulukta fazla olan eşyaların paylaşımı için yüksek performanslı bir "kaydırarak eşleştirme" web uygulaması.
Neler öğreneceksiniz?
- Tek Tıklamayla Sağlama: Yapay zeka iş yükleri için tasarlanmış bir Cloud SQL ve örneği nasıl oluşturulur?
- Veritabanı İçi Yerleştirmeler: Doğrudan INSERT ifadeleri içinde text-embedding-005 vektörleri oluşturma.
- Çok formatlı akıl yürütme: Gemini 3.0 Flash'ı kullanarak öğeleri "görme" ve otomatik olarak esprili, flört tarzı biyografiler oluşturma.
- Anlamsal Keşif: Sonuçları yalnızca matematiksel olarak değil, bağlama göre de filtrelemek için ai.if() işlevini kullanarak SQL sorgularında mantığa dayalı "vibe check" işlemleri gerçekleştirme.
Mimari
Neighbor Loop, geleneksel uygulama katmanı darboğazlarını atlar. Verileri işlemek için dışarı çekmek yerine şunları kullanırız:
- Cloud SQL + makine öğrenimi entegrasyonu: Vektörleri anında oluşturup depolamak için.
- Google Cloud Storage: Resimleri depolamak için
- Gemini 3.0 Flash: Doğrudan SQL üzerinden görüntü ve metin verileri üzerinde bir saniyeden kısa sürede akıl yürütme işlemleri yapmak için.
- Cloud Run: Tek dosyalı, basit bir Flask arka ucu barındırmak için.
Şartlar
2. Başlamadan önce
Proje oluşturma
- Google Cloud Console'daki 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ı kontrol etmeyi öğ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 aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
- gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak 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 ederek API'leri etkinleştirin.
Alternatif olarak, bu işlem için gcloud komutunu kullanabilirsiniz. gcloud komutları ve kullanımı için belgelere bakın.
Gotchas & Troubleshooting
"Hayalet Proje" Sendromu |
|
Faturalandırma Barikatı | Projeyi etkinleştirdiniz ancak faturalandırma hesabını unuttunuz. Faturalandırma boşsa Cloud SQL başlatılmaz. |
API Yayılımı Gecikmesi | "API'leri etkinleştir"i tıkladınız ancak komut satırında hâlâ |
3. Veritabanı kurulumu
Bu laboratuvarda, test verileri için veritabanı olarak Cloud SQL for PostgreSQL'i kullanacağız.
Test veri kümesinin yükleneceği bir Cloud SQL örneği oluşturalım.
- Google Cloud Console kullanıcısının oturumunun açık olduğu tarayıcınızda aşağıdaki bağlantıyı kopyalayın veya düğmeyi tıklayı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 olmanız önemlidir):
sh run.sh
- Şimdi kullanıcı arayüzünü kullanın (terminaldeki bağlantıyı veya terminaldeki "web'de önizleme" bağlantısını tıklayarak).
- Başlamak için proje kimliği ve örnek adı ayrıntılarınızı girin.
- Günlükler kayarken kahve almaya gidebilirsiniz. Bu işlemin arka planda nasıl yapıldığı hakkında bilgi edinmek için burayı ziyaret edebilirsiniz.
Gotchas & Troubleshooting
Bölge Uyuşmazlığı | API'lerinizi |
Cloud Shell Zaman Aşımı | Kahve molanız 30 dakika sürerse Cloud Shell uyku moduna geçebilir ve |
4. Şema Sağlama
Cloud SQL örneğiniz çalıştıktan sonra, yapay zeka uzantılarını etkinleştirmek ve şemayı sağlamak için Cloud SQL Studio SQL düzenleyicisine gidin.
Örneğinizin oluşturulmasının tamamlanmasını beklemeniz gerekebilir. Örnek oluşturulduktan sonra, oluştururken belirlediğiniz kimlik bilgilerini kullanarak Cloud SQL örneğinde oturum açın. PostgreSQL'de kimlik doğrulaması yapmak için aşağıdaki verileri kullanın:
- Kullanıcı adı : "
postgres" - Veritabanı : "
postgres" - Şifre : "
cloudsql" (veya oluşturma sırasında ayarladığınız şifre)
Cloud SQL Studio'da kimliğiniz başarıyla doğrulandıktan sonra SQL komutları Düzenleyici'ye girilir. Son pencerenin sağındaki artı işaretini kullanarak birden fazla Editor penceresi ekleyebilirsiniz.
Gerekli durumlarda Çalıştır, Biçimlendir ve Temizle seçeneklerini kullanarak Cloud SQL komutlarını düzenleyici pencerelerine gireceksiniz.
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 üzere 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
Cloud SQL Studio'da aşağıdaki DDL ifadesini kullanarak bir tablo oluşturabilirsiniz:
-- 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()
);
item_vector sütunu, metnin vektör değerlerinin depolanmasına olanak tanır.
İzin Ver
"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;
ML entegrasyonunu etkinleştirme
Makine öğrenimi özelliklerinden doğrudan veritabanınızda yararlanmak için ML entegrasyonu işaretini etkinleştirmeniz gerekir.
Aşağıdaki komutu Cloud Shell Terminali'nden çalıştırabilirsiniz:
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
Cloud SQL hizmet hesabına Vertex AI Kullanıcısı ROLÜ'nü verme
Google Cloud IAM Console'dan Cloud SQL hizmet hesabına (service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.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, aşağıdaki komutu Cloud Shell Terminali'nden çalıştırabilirsiniz:
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"
Gemini 3 Flash modelini Cloud SQL'e kaydetme
Cloud SQL sorgu düzenleyicisinden aşağıdaki SQL ifadesini çalıştırın.
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.
Gotchas & Troubleshooting
"Parola Unutma" Döngüsü | "Tek Tıkla" kurulumunu kullandıysanız ve şifrenizi hatırlamıyorsanız konsoldaki örnek temel bilgileri sayfasına gidip |
"Uzantı Bulunamadı" Hatası |
|
IAM Yayılma Boşluğu |
|
Vektör Boyutu Uyuşmazlığı |
|
Project ID Typo |
|
Vertex AI entegrasyonu devre dışı |
|
5. Görüntü Depolama (Google Cloud Storage)
Fazla ürünlerimizin fotoğraflarını depolamak için bir GCS paketi kullanıyoruz. Bu demo uygulamasında, resimlerin herkese açık olmasını istiyoruz. Böylece, kaydırma kartlarımızda anında oluşturulabilirler.
- Paket oluşturma: GCP projenizde yeni bir paket oluşturun (ör.neighborloop-images). Tercihen veritabanınız ve uygulamanızla aynı bölgede olmalıdır.
- Herkese açık erişimi yapılandırma: * Bucket'ın İzinler sekmesine gidin.
- allUsers ana hesabını ekleyin.
- Storage Object Viewer (Depolama Alanı Nesne Görüntüleyici) rolünü (böylece herkes fotoğrafları görebilir) ve Storage Object Creator (Depolama Alanı Nesne Oluşturucu) rolünü (demo yükleme amacıyla) atayın.
Alternatif (Hizmet Hesabı): Herkese açık erişimi kullanmamayı tercih ediyorsanız uygulamanızın hizmet hesabına Cloud SQL'e tam erişim ve nesneleri güvenli bir şekilde yönetmek için gerekli depolama rolleri verildiğinden emin olun.
Komutu çalıştırmak ve herkese açık erişim vermek istiyorsanız. Cloud Shell terminalinde aşağıdaki komutları çalıştırın:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
Gotchas & Troubleshooting
The Region Drag | Veritabanınız |
Paket Adının Benzersizliği | Paket adları, genel bir ad alanıdır. Paketinize |
"İçerik üretici" ve "izleyici" karışıklığı | "Oluşturucu" ve "Görüntüleyici" karışıklığı: Yalnızca "Görüntüleyici" eklediyseniz uygulamanız, bir kullanıcı yeni bir öğe listelemeye çalıştığında dosya yazma izni olmadığı için çöker. Bu özel demo kurulumu için her ikisine de ihtiyacınız var. |
6. Uygulamayı oluşturalım
Bu depoyu projenize klonlayın ve inceleyelim.
- Bunu klonlamak için Cloud Shell terminalinizde (kök dizinde veya bu projeyi oluşturmak istediğiniz herhangi bir yerden) aşağıdaki komutları tek tek çalıştırın:
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
Bu işlem projeyi oluşturur ve Cloud Shell Düzenleyici'de bunu doğrulayabilirsiniz.
- Gemini API anahtarınızı alma
- Google AI Studio'yu ziyaret edin: aistudio.google.com adresine gidin.
- Oturum açma: Google Cloud projeniz için kullandığınız aynı Google Hesabı'nı kullanın.
- API anahtarı oluşturma:
- Sol kenar çubuğunda "API anahtarı al"ı tıklayın.
- "Yeni projede API anahtarı oluştur" düğmesini tıklayın.
- Anahtarı kopyalama: Anahtar oluşturulduktan sonra kopyalama simgesini tıklayın.
- Şimdi .env dosyasındaki ortam değişkenlerini ayarlayın.
GEMINI_API_KEY=<<YOUR_GEMINI_API_KEY>>
DATABASE_URL=postgresql+pg8000://postgres:<<YOUR_PASSWORD>>@<<HOST_IP>>:<<PORT>>/postgres
GCS_BUCKET_NAME=<<YOUR_GCS_BUCKET>>
Yer tutucuların değerlerini değiştirin <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
Gotchas & Troubleshooting
Birden Çok Hesapla İlgili Kafa Karışıklığı | Birden fazla Google Hesabı'nda (kişisel ve iş) oturum açtıysanız AI Studio yanlış hesabı varsayılan olarak kullanabilir. GCP projesi hesabınızla eşleştiğinden emin olmak için sağ üst köşedeki avatarı kontrol edin. |
"Ücretsiz Katman" Kota Sınırına Ulaşıldı | Ücretsiz katmanı kullanıyorsanız hız sınırları (RPM - Dakikadaki İstek Sayısı) vardır. Komşuluk Çemberi'nde çok hızlı "kaydırırsanız" |
Açığa Çıkan Anahtar Güvenliği |
|
7. Kodu kontrol edelim
Eşyalarınız için "Flört Profili"
Kullanıcılar, bir öğenin fotoğrafını yüklediklerinde uzun bir açıklama yazmak zorunda kalmamalıdır. Öğeyi "görmek" ve listelemesini yazmak için Gemini 3 Flash'i kullanıyorum.
Arka uçta kullanıcı yalnızca bir başlık ve fotoğraf sağlar. Gerisini Gemini halleder:
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")
)
Veritabanında Anlık Yerleştirmeler
Cloud SQL'in en iyi özelliklerinden biri, SQL bağlamından ayrılmadan yerleştirme oluşturabilme özelliğidir. Python'da bir yerleştirme modelini çağırmak ve vektörü veritabanına geri göndermek yerine, embedding() işlevini kullanarak tüm bunları tek bir INSERT ifadesinde yapıyorum:
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
)
Bu sayede, her öğe yayınlandığı anda anlamı üzerinden "aranabilir" hale gelir. Bu bölümün, Neighbor Loop uygulamasının "ürünü listeleme" özelliğini kapsadığını unutmayın.
Gemini 3.0 ile Gelişmiş Vektör Arama ve Akıllı Filtreleme
Standart anahtar kelime araması sınırlıdır. "Sandalyemi tamir etmek için bir şey" ifadesini aradığınızda, geleneksel bir veritabanı "sandalye" kelimesi başlıkta yer almıyorsa hiçbir sonuç döndürmeyebilir. Neighbor Loop, Cloud SQL AI'ın gelişmiş vektör arama özelliğiyle bu sorunu çözüyor.
pgvector uzantısını ve Cloud SQL'in optimize edilmiş depolama alanını kullanarak son derece hızlı benzerlik aramaları yapabiliriz. Ancak asıl "sihir", vektör yakınlığını LLM tabanlı mantıkla birleştirdiğimizde ortaya çıkar.
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
Bu sorgu, büyük bir mimari değişikliği temsil ediyor: Mantığı veriye taşıyoruz. Gemini 3 Flash, binlerce sonucu filtrelemek için uygulama koduna çekmek yerine veritabanı motorunda "vibe check" (enerji kontrolü) yapar. Bu, gecikmeyi azaltır, çıkış maliyetlerini düşürür ve sonuçların yalnızca matematiksel olarak benzer değil, bağlamsal olarak da alakalı olmasını sağlar.
"Eşleşmek için Kaydırın" Döngüsü
Kullanıcı arayüzü, klasik bir iskambil destesidir.
Sola kaydırma: Silme
Sağa kaydırın: Eşleşme!
Sağa kaydırdığınızda arka uç, etkileşimi kaydırma tablomuzda kaydeder ve öğeyi eşleşmiş olarak işaretler. Ön uç, teslim alma işlemini ayarlayabilmeniz için sağlayıcının iletişim bilgilerini gösteren bir modalı anında tetikler.
8. Cloud Run'a dağıtalım
- Projeyi klonladığınız Cloud Shell terminalinden aşağıdaki komutu çalıştırarak Cloud Run'da dağıtın ve projenin kök klasöründe olduğunuzdan emin olun.
Cloud Shell terminalinizde şunu çalıştırın:
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>>
Yer tutucuların değerlerini değiştirin <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
Komut tamamlandığında bir hizmet URL'si oluşturulur. Kopyalayın.
Şimdi hizmet URL'sini (daha önce kopyaladığınız Cloud Run uç noktası) kullanarak uygulamayı test edin. Eski elektrikli aletin fotoğrafını yükleyin ve gerisini Gemini'a bırakın.
Gotchas & Troubleshooting
"Düzeltme Başarısız Oldu" Döngüsü | Dağıtım tamamlanmasına rağmen URL'de |
9. Üst Düzey Sorun Giderme
10. Demo
Uç noktanızı testler için kullanabilirsiniz.
Ancak birkaç gün boyunca demo amaçlı olarak şunları deneyebilirsiniz:
11. Temizleme
Bu laboratuvar tamamlandıktan sonra Cloud SQL örneğini silmeyi unutmayın.
12. Tebrikler
Google Cloud ile sürdürülebilir topluluklar için Neighbor Loop uygulamasını başarıyla oluşturdunuz. Yerleştirme ve Gemini 3 Flash yapay zeka mantığını Cloud SQL'e taşıyarak uygulama inanılmaz derecede hızlı (dağıtım ayarlarına bağlı olarak) ve kod son derece temiz hale gelir. Yalnızca verileri değil, amaçları da saklıyoruz.
Gemini 3 Flash'in hızı ile Cloud SQL'in optimize edilmiş vektör işleme özelliği, topluluk odaklı platformlar için gerçekten de yeni bir dönemin başlangıcıdır.