1. סקירה כללית
בשיעור הזה תלמדו איך לפתח את Neighbor Loop, אפליקציה בת קיימא לשיתוף עודפים שמתייחסת לנתונים כאל חלק חשוב בשכבת הנתונים.
שילוב של Gemini 3.0 Flash עם שילוב ה-ML של 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 Console, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-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 ולהקצות את הסכימה.
יכול להיות שתצטרכו לחכות עד שהמופע שלכם יסיים את תהליך היצירה. אחרי שיוצרים את המכונה, נכנסים אליה באמצעות פרטי הכניסה שיצרתם. משתמשים בנתונים הבאים כדי לבצע אימות ב-PostgreSQL:
- שם משתמש : "
postgres" - מסד נתונים : "
postgres" - סיסמה:
cloudsql(או כל סיסמה אחרת שהגדרתם בזמן היצירה)
אחרי שתעברו בהצלחה את תהליך האימות ב-Cloud SQL Studio, תוכלו להזין פקודות SQL בעורך. אפשר להוסיף כמה חלונות של Editor באמצעות סימן הפלוס שמשמאל לחלון האחרון.
תזינו פקודות ל-Cloud SQL בחלונות העריכה, ותשתמשו באפשרויות Run (הפעלה), Format (עיצוב) ו-Clear (ניקוי) לפי הצורך.
הפעלת תוספים
כדי ליצור את האפליקציה הזו, נשתמש בתוספים pgvector ו-google_ml_integration. התוסף pgvector מאפשר לכם לאחסן ולחפש הטמעות של וקטורים. התוסף google_ml_integration מספק פונקציות שמשמשות לגישה לנקודות קצה של חיזוי ב-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
במסוף IAM של Google Cloud, מעניקים לחשבון השירות של 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), רצוי באותו אזור כמו מסד הנתונים והאפליקציה.
- הגדרת גישה ציבורית: * עוברים לכרטיסייה הרשאות של הקטגוריה.
- מוסיפים את חשבון המשתמש 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 Cloud.
- יצירת מפתח 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 – Requests Per Minute). אם תגללו מהר מדי ב-Neighbor Loop, יכול להיות שתופיע שגיאת |
חשיפת מפתחות אבטחה | אם בטעות |
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 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 הוא באמת הדבר הבא בפלטפורמות שמבוססות על קהילה.