1. סקירה כללית
ב-Codelab הזה אנחנו מסבירים איך מפתחים את Neighbor Loop – אפליקציה בת קיימא לשיתוף עודפים, שמתייחסת לנתונים כאל חלק חשוב בשכבת הנתונים.
שילוב של Gemini 3.0 Flash עם שילוב למידת המכונה של Cloud SQL מאפשר לכם לעבור מאחסון בסיסי לתחום של מידע מתוך מסד הנתונים. תלמדו איך לבצע ניתוח פריטים מולטי-מודאלי וחקירה סמנטית ישירות ב-SQL.
מה תפַתחו
אפליקציית אינטרנט עם ביצועים גבוהים שמאפשרת לקהילה לשתף עודפים באמצעות החלקה.
מה תלמדו
- הקצאת משאבים בלחיצה אחת: איך מגדירים Cloud SQL ומופע שמותאמים לעומסי עבודה של AI.
- הטמעות במסד נתונים: יצירת וקטורים של text-embedding-005 ישירות בהצהרות INSERT.
- הסקה מולטי-מודאלית: שימוש ב-Gemini 3.0 Flash כדי 'לראות' פריטים וליצור אוטומטית ביוגרפיות שנונות בסגנון אפליקציות היכרויות.
- גילוי סמנטי: ביצוע בדיקות של 'אווירה' מבוססות-לוגיקה בתוך שאילתות SQL באמצעות הפונקציה ai.if() כדי לסנן תוצאות על סמך הקשר, ולא רק על סמך מתמטיקה.
הארכיטקטורה
Neighbor Loop עוקף צווארי בקבוק מסורתיים בשכבת האפליקציה. במקום לשלוף נתונים כדי לעבד אותם, אנחנו משתמשים ב:
- שילוב של Cloud SQL + ML: כדי ליצור ולאחסן וקטורים בזמן אמת.
- Google Cloud Storage: לאחסון תמונות
- Gemini 3.0 Flash: כדי לבצע חשיבה רציונלית על נתוני תמונות וטקסט ישירות דרך SQL תוך פחות משנייה.
- Cloud Run: לאירוח קצה עורפי קל משקל של Flask עם קובץ יחיד.
דרישות
2. לפני שמתחילים
יצירת פרויקט
- ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
- מוודאים שהחיוב מופעל בפרויקט ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט.
- תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud. לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud.
- אחרי שמתחברים ל-Cloud Shell, אפשר לבדוק שכבר בוצע אימות ושהפרויקט מוגדר לפי מזהה הפרויקט באמצעות הפקודה הבאה:
gcloud auth list
- מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.
gcloud config list project
- אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:
gcloud config set project <YOUR_PROJECT_ID>
- מפעילים את ממשקי ה-API הנדרשים: לוחצים על הקישור ומפעילים את ממשקי ה-API.
אפשר גם להשתמש בפקודת gcloud. אפשר לעיין במאמרי העזרה בנושא פקודות gcloud ושימוש בהן.
נקודות חשובות ופתרון בעיות
תסמונת הפרויקט הרפאים | הפעלתם את הפקודה |
מחסום החיוב | הפעלתם את הפרויקט, אבל שכחתם להוסיף חשבון לחיוב. אם החיוב ריק, Cloud SQL לא יופעל. |
השהיה בפרסום ה-API | לחצתם על 'הפעלת ממשקי API', אבל בשורת הפקודה עדיין מופיע |
3. הגדרת מסד נתונים
בשיעור ה-Lab הזה נשתמש ב-Cloud SQL ל-PostgreSQL כמסד הנתונים של נתוני הבדיקה.
ניצור מכונה של Cloud SQL שבה ייטען מערך הנתונים של הבדיקה.
- לוחצים על הלחצן או מעתיקים את הקישור שלמטה לדפדפן שבו המשתמש מחובר למסוף Google Cloud.
- אחרי שתשלימו את השלב הזה, המאגר ישוכפל לעורך המקומי של Cloud Shell ותוכלו להריץ את הפקודה שבהמשך מתוך תיקיית הפרויקט (חשוב לוודא שאתם בספריית הפרויקט):
sh run.sh
- עכשיו משתמשים בממשק המשתמש (לוחצים על הקישור במסוף או על הקישור 'תצוגה מקדימה באינטרנט' במסוף).
- כדי להתחיל, מזינים את הפרטים של מזהה הפרויקט ושם המכונה.
- אתם יכולים ללכת לשתות קפה בזמן שהיומנים מתעדכנים, וכאן תוכלו לקרוא איך זה קורה מאחורי הקלעים.
נקודות חשובות ופתרון בעיות
חוסר התאמה באזור | אם הפעלתם את ממשקי ה-API ב- |
פסק זמן ב-Cloud Shell | אם הפסקת הקפה שלכם נמשכת 30 דקות, יכול להיות ש-Cloud Shell יעבור למצב שינה וינתק את התהליך |
4. הקצאת הרשאות לסכימה
אחרי שהמכונה של Cloud SQL פועלת, עוברים אל עורך ה-SQL של Cloud SQL Studio כדי להפעיל את תוספי ה-AI ולהקצות את הסכימה.
יכול להיות שתצטרכו לחכות עד שהמופע שלכם יסיים את תהליך היצירה. אחרי שיוצרים את המכונה, צריך להיכנס ל-Cloud SQL באמצעות פרטי הכניסה שיצרתם. משתמשים בנתונים הבאים כדי לבצע אימות ב-PostgreSQL:
- שם משתמש : "
postgres" - מסד נתונים : "
postgres" - סיסמה:
cloudsql(או כל סיסמה שהגדרתם בזמן היצירה)
אחרי שתעברו את תהליך האימות ב-Cloud SQL Studio, תוכלו להזין פקודות SQL בעורך. אפשר להוסיף כמה חלונות של Editor באמצעות סימן הפלוס שמשמאל לחלון האחרון.
תזינו פקודות ל-Cloud SQL בחלונות העריכה, ותשתמשו באפשרויות Run (הפעלה), Format (עיצוב) ו-Clear (ניקוי) לפי הצורך.
הפעלת תוספים
כדי לבנות את האפליקציה הזו, נשתמש בתוספים pgvector ו-google_ml_integration. התוסף pgvector מאפשר לכם לאחסן ולחפש הטמעות של וקטורים. התוסף google_ml_integration מספק פונקציות שמשמשות לגישה לנקודות קצה (endpoints) של חיזוי ב-Vertex AI כדי לקבל חיזויים ב-SQL. מפעילים את התוספים האלה על ידי הפעלת פקודות ה-DDL הבאות:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
צור טבלה
אפשר ליצור טבלה באמצעות הצהרת ה-DDL שבהמשך ב-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()
);
בעמודה item_vector אפשר לאחסן את ערכי הווקטור של הטקסט.
מתן הרשאה
מריצים את ההצהרה הבאה כדי להעניק הרשאת הפעלה לפונקציה embedding:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
הפעלת השילוב של ML
כדי להשתמש בתכונות של למידת מכונה ישירות במסד הנתונים, צריך להפעיל את דגל השילוב של למידת המכונה.
אפשר להריץ את הפקודה הבאה מ-Cloud Shell Terminal:
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
הענקת התפקיד 'משתמש ב-Vertex AI' לחשבון השירות של Cloud SQL
במסוף Cloud IAM של Google, מעניקים לחשבון השירות של Cloud SQL (שנראה כך: service-<<PROJECT_NUMBER>>@cp-sa-cloud-sql.iam.gserviceaccount.com) גישה לתפקיד Vertex AI User. PROJECT_NUMBER יכיל את מספר הפרויקט.
לחלופין, אפשר להריץ את הפקודה הבאה מ-Cloud Shell Terminal:
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 ב-Cloud SQL
מריצים את הצהרת ה-SQL הבאה מ-Cloud SQL Query Editor
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.
נקודות חשובות ופתרון בעיות
הלולאה של 'שכחתי את הסיסמה' | אם השתמשתם בהגדרה 'קליק אחד' ואתם לא זוכרים את הסיסמה, אתם יכולים לעבור לדף 'פרטים בסיסיים של מופע' במסוף וללחוץ על 'עריכה' כדי לאפס את הסיסמה |
השגיאה 'התוסף לא נמצא' | אם הפעולה |
הפער בהפצת IAM | הפעלתם את פקודת ה-IAM |
חוסר התאמה במאפיין הווקטור | הטבלה |
שגיאת כתיב במזהה הפרויקט | בשיחה |
האינטגרציה של Vertex AI מושבתת | הפעלה של |
5. אחסון תמונות (Google Cloud Storage)
כדי לאחסן את התמונות של הפריטים העודפים שלנו, אנחנו משתמשים בדלי GCS. לצורך אפליקציית ההדגמה הזו, אנחנו רוצים שהתמונות יהיו נגישות לכולם כדי שהן יוצגו באופן מיידי בכרטיסי ההחלקה שלנו.
- יוצרים קטגוריה: יוצרים קטגוריה חדשה בפרויקט GCP (לדוגמה, neighborloop-images), רצוי באותו אזור כמו מסד הנתונים והאפליקציה.
- הגדרת גישה ציבורית: * עוברים לכרטיסייה Permissions (הרשאות) של הקטגוריה.
- מוסיפים את חשבון המשתמש allUsers.
- מקצים את התפקיד צפייה באובייקט אחסון (כדי שכולם יוכלו לראות את התמונות) ואת התפקיד יצירת אובייקטים של אחסון (לצורך העלאה של הדגמה).
אפשרות חלופית (חשבון שירות): אם אתם לא רוצים להשתמש בגישה ציבורית, אתם צריכים לוודא שלחשבון השירות של האפליקציה שלכם יש גישה מלאה ל-Cloud SQL ותפקידי האחסון הנדרשים לניהול אובייקטים בצורה מאובטחת.
אם רוצים להריץ את הפקודה ולאפשר גישה לכולם. מריצים את הפקודות הבאות במסוף Cloud Shell:
BUCKET_NAME="<<your-bucket-name>>"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
--member="allUsers" \
--role="roles/storage.objectViewer"
נקודות חשובות ופתרון בעיות
The Region Drag | אם מסד הנתונים שלכם נמצא ב- |
ייחודיות של שם הקטגוריה | שמות הקטגוריות הם מרחב שמות גלובלי. אם תנסו לקרוא לקטגוריה שלכם בשם |
הבלבול בין 'יוצר' לבין 'צופה' | בלבול בין 'יוצר' לבין 'צופה': אם מוסיפים רק 'צופה', האפליקציה תקרוס כשמשתמש ינסה להוסיף פריט חדש, כי אין לה הרשאה לכתוב את הקובץ. שני הפרטים האלה נדרשים להגדרת ההדגמה הספציפית הזו. |
6. נתחיל ליצור את האפליקציה
שכפלו את המאגר הזה לפרויקט שלכם ונעבור עליו ביחד.
- כדי לשכפל את הפרויקט, מריצים את הפקודות הבאות אחת אחרי השנייה בטרמינל של Cloud Shell (בספריית הבסיס או בכל מקום שבו רוצים ליצור את הפרויקט):
git clone https://github.com/flazer99/neighbor-loop-cloud-sql
cd neighbor-loop-cloud-sql/
הפעולה הזו אמורה ליצור את הפרויקט, ואפשר לוודא זאת בעורך Cloud Shell.
- איך מקבלים מפתח Gemini API
- נכנסים ל-Google AI Studio: עוברים לכתובת aistudio.google.com.
- כניסה: צריך להשתמש באותו חשבון Google שבו אתם משתמשים לפרויקט בענן של Google.
- יצירת מפתח API:
- בסרגל הצד הימני, לוחצים על 'קבלת מפתח API'.
- לוחצים על הלחצן 'יצירת מפתח API בפרויקט חדש'.
- מעתיקים את המפתח: אחרי שהמפתח נוצר, לוחצים על סמל ההעתקה.
- עכשיו מגדירים את משתני הסביבה בקובץ .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>>
מחליפים את הערכים של הפלייסהולדרים <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<HOST_IP>>, <<PORT>> and <<YOUR_GCS_BUCKET>>.
נקודות חשובות ופתרון בעיות
בלבול בין כמה חשבונות | אם אתם מחוברים לכמה חשבונות Google (אישי לעומת חשבון לצורכי עבודה), יכול להיות ש-AI Studio יוגדר כברירת מחדל לחשבון הלא נכון. בודקים את הדמות בפינה השמאלית העליונה כדי לוודא שהיא תואמת לחשבון הפרויקט שלכם ב-GCP. |
הגעתם למכסת השימוש בתוכנית החינמית | אם אתם משתמשים בתוכנית ללא תשלום, יש מגבלות על קצב הבקשות (RPM – בקשות לדקה). אם תגללו מהר מדי ב'שכונה', יכול להיות שתופיע שגיאת |
חשיפת אבטחת מפתחות | אם בטעות |
7. בדיקת הקוד
הפרופיל שלכם ב-Stuff
כשמשתמש מעלה תמונה של פריט, הוא לא צריך לכתוב תיאור ארוך. אני משתמש ב-Gemini 3 Flash כדי 'לראות' את הפריט ולכתוב את הפרטים שלו בדף.
בצד השרת, המשתמש רק מציין כותרת ותמונה. Gemini מטפל בכל השאר:
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")
)
הטמעות בזמן אמת במסד הנתונים
אחת התכונות הכי מגניבות של Cloud SQL היא היכולת ליצור הטמעות בלי לצאת מההקשר של SQL. במקום להפעיל מודל הטמעה ב-Python ולשלוח את הווקטור בחזרה למסד הנתונים, אני עושה את הכול בהצהרת INSERT אחת באמצעות הפונקציה 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
)
כך אפשר לוודא שכל פריט יהיה 'ניתן לחיפוש' לפי המשמעות שלו ברגע שהוא מתפרסם. חשוב לציין שזה החלק שמתייחס לתכונה 'הוספת המוצר לרשימה' באפליקציית Neighbor Loop.
חיפוש וקטורי מתקדם וסינון חכם באמצעות Gemini 3.0
החיפוש הרגיל של מילות מפתח מוגבל. אם תחפשו "משהו לתקן את הכיסא שלי", יכול להיות שמסד נתונים מסורתי לא יחזיר תוצאות אם המילה "כיסא" לא מופיעה בכותרת. כדי לפתור את הבעיה הזו, Neighbor Loop משתמש בחיפוש וקטורי מתקדם של Cloud SQL AI.
באמצעות התוסף pgvector והאחסון המותאם של Cloud SQL, אנחנו יכולים לבצע חיפושי דמיון מהירים במיוחד. אבל הקסם האמיתי קורה כשמשלבים בין קרבה וקטורית לבין לוגיקה שמבוססת על מודלים גדולים של שפה (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
השאילתה הזו מייצגת שינוי ארכיטקטוני משמעותי: אנחנו מעבירים את הלוגיקה אל הנתונים. במקום לשלוף אלפי תוצאות לקוד האפליקציה כדי לסנן אותן, Gemini 3 Flash מבצע "בדיקת אווירה" בתוך המנוע של מסד הנתונים. כך מצטמצם זמן האחזור, יורדות העלויות של תעבורת נתונים יוצאת ומובטח שהתוצאות לא יהיו רק דומות מבחינה מתמטית, אלא גם רלוונטיות מבחינת ההקשר.
הלולאה 'החלקה להתאמה'
ממשק המשתמש הוא חפיסת קלפים קלאסית.
החלקה ימינה: מחיקה.
החלקה ימינה: יש התאמה!
כשמחליקים ימינה, האינטראקציה נרשמת בטבלת ההחלקות שלנו בקצה העורפי והפריט מסומן כפריט שתאם. ממשק הקצה מפעיל באופן מיידי חלון קופץ שבו מוצגים הפרטים ליצירת קשר עם הספק, כדי שתוכלו לתאם את האיסוף.
8. בואו נפרוס אותו ב-Cloud Run
- פורסים אותו ב-Cloud Run על ידי הפעלת הפקודה הבאה מ-Cloud Shell Terminal שבו הפרויקט משוכפל, מוודאים שאתם נמצאים בתיקיית הבסיס של הפרויקט.
מריצים את הפקודה הבאה בטרמינל Cloud Shell:
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>>
מחליפים את הערכים של הפלייסהולדרים <<YOUR_GEMINI_API_KEY>>, <<YOUR_PASSWORD>, <<PRIVATE_IP_HOST>>, <<PORT>> and <<YOUR_GCS_BUCKET>>
אחרי שהפקודה מסתיימת, היא מחזירה כתובת URL של שירות. מעתיקים אותו.
עכשיו משתמשים בכתובת ה-URL של השירות (נקודת הקצה של Cloud Run שהעתקתם קודם) ובודקים את האפליקציה. מעלים תמונה של הכלי החשמלי הישן ומאפשרים ל-Gemini לעשות את השאר.
נקודות חשובות ופתרון בעיות
הלולאה 'הבדיקה נכשלה' | אם הפריסה מסתיימת אבל כתובת ה-URL מחזירה |
9. פתרון בעיות ברמה גבוהה
10. הדגמה (דמו)
אפשר להשתמש בנקודת היעד לבדיקות.
אבל למטרות הדגמה למשך כמה ימים, אתם יכולים לנסות את זה:
11. הסרת המשאבים
כשמסיימים את ה-Lab הזה, חשוב למחוק את מכונת Cloud SQL.
12. מזל טוב
יצרתם בהצלחה את אפליקציית Neighbor Loop לקהילות בנות קיימא באמצעות Google Cloud. העברת ההטמעה והלוגיקה של Gemini 3 Flash AI אל Cloud SQL מאפשרת לאפליקציה לפעול במהירות רבה (בהתאם להגדרות הפריסה) ולקוד להיות נקי במיוחד. אנחנו לא רק מאחסנים נתונים – אנחנו מאחסנים כוונה.
השילוב בין המהירות של Gemini 3 Flash לבין עיבוד הווקטורים המותאם של Cloud SQL הוא באמת הדבר הבא בפלטפורמות שמבוססות על קהילה.