1. סקירה כללית
ב-Codelab הזה תפתחו אפליקציה לחיפוש במאגר ידע שניתן להתאים לעומס. במקום לנהל צינור עיבוד נתונים מורכב של ETL עם סקריפטים ולולאות של Python כדי ליצור הטמעות וקטורים, תשתמשו ב-AlloyDB AI כדי לטפל ביצירת הטמעות באופן מקורי בתוך מסד הנתונים באמצעות פקודת SQL אחת.

מה תפתחו
אפליקציה של מסד נתונים עם ביצועים גבוהים שניתן לחפש בה במאגר הידע.
מה תלמדו
כאן תלמדו איך:
- להקצות אשכול AlloyDB ולהפעיל תוספי AI.
- ליצור נתונים סינתטיים (יותר מ-50,000 שורות) באמצעות SQL.
- ממלאים את הטמעות הווקטורים לכל מערך הנתונים באמצעות עיבוד באצווה.
- מגדירים טריגרים מצטברים בזמן אמת כדי להטמיע נתונים חדשים באופן אוטומטי.
- מבצעים חיפוש היברידי (וקטור + מסנני SQL) של "Flexing Context".
דרישות
2. לפני שמתחילים
יצירת פרויקט
- במסוף Google Cloud, בדף לבחירת הפרויקט בוחרים או יוצרים פרויקט ב-Google Cloud.
- מוודאים שהחיוב מופעל בפרויקט ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט.
- תשתמשו ב-Cloud Shell, סביבה של שורת פקודה שפועלת ב-Google Cloud. לוחצים על Activate 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 ושימוש בהן.
gcloud services enable \
alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com
בעיות נפוצות ופתרון בעיות
תסמונת "פרויקט הרפאים" | הפעלתם את |
מחסום החיוב | הפעלתם את הפרויקט, אבל שכחתם את החשבון לחיוב. AlloyDB הוא מנוע עם ביצועים גבוהים, והוא לא יתחיל לפעול אם "מכל הדלק" (החיוב) ריק. |
עיכוב בהפצת API | לחצתם על "הפעלת ממשקי API", אבל בשורת הפקודה עדיין מופיע |
ביצות של מכסות | אם אתם משתמשים בחשבון חדש לתקופת ניסיון, יכול להיות שתגיעו למכסה האזורית של מכונות AlloyDB. אם |
סוכן שירות "מוסתר" | לפעמים סוכן השירות של AlloyDB לא מקבל באופן אוטומטי את התפקיד |
3. הגדרת מסד הנתונים
בשיעור ה-Lab הזה נשתמש ב-AlloyDB כמסד הנתונים של נתוני הבדיקה. הוא משתמש באשכולות כדי להחזיק את כל המשאבים, כמו מסדי נתונים ויומנים. לכל אשכול יש מכונה ראשית שמספקת נקודת גישה לנתונים. הטבלאות יכילו את הנתונים בפועל.
ניצור אשכול, מכונה וטבלה של AlloyDB שבהם ייטען מערך הנתונים לבדיקה.
- לוחצים על הכפתור או מעתיקים את הקישור שלמטה לדפדפן שבו מחובר המשתמש של מסוף Google Cloud.
- בסיום השלב הזה, המאגר ישוכפל לעורך המקומי של Cloud Shell ותוכלו להריץ את הפקודה הבאה מתיקיית הפרויקט (חשוב לוודא שאתם נמצאים בספריית הפרויקט):
sh run.sh
- עכשיו משתמשים בממשק המשתמש (לוחצים על הקישור בטרמינל או על הקישור "תצוגה מקדימה באינטרנט" בטרמינל.
- כדי להתחיל, מזינים את הפרטים של מזהה הפרויקט, האשכול ושמות המכונות.
- בזמן שהיומנים נגללים, אתם יכולים ללכת להכין קפה ולקרוא כאן איך זה עובד מאחורי הקלעים. התהליך יימשך כ-10 עד 15 דקות.
בעיות נפוצות ופתרון בעיות
בעיית "הסבלנות" | אשכולות של מסדי נתונים הם תשתית כבדה. אם תרעננו את הדף או תסגרו את הסשן של Cloud Shell כי "נראה שהוא תקוע", יכול להיות שתקבלו מכונה "רפאים" שהוקצתה באופן חלקי ואי אפשר למחוק אותה בלי התערבות ידנית. |
חוסר התאמה באזור | אם הפעלתם את ממשקי ה-API ב- |
אשכולות זומבי | אם השתמשתם בעבר באותו שם לאשכול ולא מחקתם אותו, יכול להיות שיופיע בסקריפט שהשם של האשכול כבר קיים. שמות האשכולות חייבים להיות ייחודיים בתוך הפרויקט. |
זמן קצוב לתפוגה של Cloud Shell | אם הפסקת הקפה שלכם נמשכת 30 דקות, יכול להיות ש-Cloud Shell יעבור למצב שינה וינתק את התהליך של |
4. הקצאת סכימה
בשלב הזה נסביר על:

אחרי שהאשכול והמכונה של AlloyDB פועלים, עוברים לעורך ה-SQL של AlloyDB Studio כדי להפעיל את תוספי ה-AI ולהקצות את הסכימה.
יכול להיות שתצטרכו להמתין עד שהמכונה תיווצר. אחרי שהיא תסתיים, נכנסים ל-AlloyDB באמצעות פרטי הכניסה שיצרתם כשיצרתם את האשכול. כדי לאמת את PostgreSQL, צריך להשתמש בנתונים הבאים:
- שם משתמש : "
postgres" - מסד נתונים : "
postgres" - סיסמה : "
alloydb" (או כל סיסמה אחרת שהגדרתם בזמן היצירה)
אחרי שתאמתו את הזהות שלכם ב-AlloyDB Studio, תוכלו להזין פקודות SQL בכלי העריכה. אפשר להוסיף כמה חלונות של הכלי לעריכת סקריפטים באמצעות סימן הפלוס שמשמאל לחלון האחרון.

מזינים פקודות ל-AlloyDB בחלונות של כלי העריכה, ומשתמשים באפשרויות 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;
צור טבלה
אנחנו צריכים מערך נתונים כדי להדגים את קנה המידה. במקום לייבא קובץ CSV, ניצור באופן מיידי 50,000 שורות של "מאמרי עזרה" סינתטיים באמצעות SQL.
אתם יכולים ליצור טבלה באמצעות הצהרת ה-DDL הבאה ב-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;
העמודה item_vector תאפשר אחסון של ערכי הווקטור של הטקסט.
מאמתים את הנתונים:
SELECT count(*) FROM help_articles;
-- Output: 50000
הפעלת דגלים לניהול מסדי נתונים
עוברים למסוף Instance configuration, לוחצים על Edit Primary, עוברים ל-Advanced Configuration ולוחצים על Add Database Flags.
אם לא, מזינים אותו בתפריט הנפתח של הדגלים, מגדירים אותו כ-ON ומעדכנים את המכונה.
אם לא, מזינים אותו בתפריט הנפתח של הדגלים, מגדירים אותו כ-ON ומעדכנים את המכונה.
שלבים להגדרת דגלים לניהול מסדי נתונים:
- נכנסים לדף Clusters במסוף Google Cloud.
- לוחצים על אשכול בעמודה Resource Name.
- בדף Overview, עוברים לקטע Instances באשכול, בוחרים מכונה ולוחצים על Edit.
- הוספה, שינוי או מחיקה של דגל לניהול מסד נתונים מהמכונה:
הוספת דגל
- כדי להוסיף דגל לניהול מסד נתונים למכונה, לוחצים על Add flag.
- בוחרים דגל מהרשימה New database flag.
- צריך לספק ערך לדגל.
- לוחצים על 'סיום'.
- לוחצים על Update instance.
- מוודאים שהתוסף google_ml_integration הוא בגרסה 1.5.2 ואילך:
כדי לבדוק את גרסת התוסף, מריצים את הפקודה הבאה:
SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
אם צריך לעדכן את התוסף לגרסה חדשה יותר, משתמשים בפקודה:
ALTER EXTENSION google_ml_integration UPDATE;
מתן הרשאה
- כדי לאפשר למשתמש לנהל את היצירה האוטומטית של הטמעות, צריך לתת הרשאות INSERT, UPDATE ו-DELETE בטבלאות google_ml.embed_gen_progress ו-google_ml.embed_gen_settings:
GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO postgres;
'postgres' הוא ה-USER_NAME שההרשאות ניתנות לו.
- מריצים את ההצהרה הבאה כדי להעניק הרשאת הפעלה לפונקציה "embedding":
GRANT EXECUTE ON FUNCTION embedding TO postgres;
הקצאת התפקיד "משתמש ב-Vertex AI" לחשבון השירות של AlloyDB
במסוף Google Cloud IAM, נותנים לחשבון השירות של AlloyDB (שנראה כך: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) גישה לתפקיד Vertex AI User. PROJECT_NUMBER הוא מספר הפרויקט שלכם.
לחלופין, אפשר להריץ את הפקודה הבאה מהטרמינל של 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"
בעיות נפוצות ופתרון בעיות
הלולאה של "שכחת סיסמה" | אם השתמשתם בהגדרה "בלחיצה אחת" ואתם לא זוכרים את הסיסמה, עברו לדף המידע הבסיסי של המכונה במסוף ולחצו על "עריכה" כדי לאפס את הסיסמה של |
השגיאה "התוסף לא נמצא" | אם הפעולה |
5. יצירת וקטורים ב "ניסיון אחד"
זה החלק העיקרי של ה-Lab. במקום לכתוב לולאת Python כדי לעבד את 50,000 השורות האלה, נשתמש בפונקציה ai.initialize_embeddings.
הפקודה הזו מבצעת שתי פעולות:
- ממלא את כל השורות הקיימות.
- יוצר טריגר להטמעה אוטומטית של שורות עתידיות.
מריצים את הצהרת ה-SQL הבאה מעורך השאילתות של 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'
);
אימות ההטמעות
מוודאים שהעמודה embedding מאוכלסת:
SELECT id, left(content_body, 30), substring(embedding::text, 1, 30) as vector_partial
FROM help_articles;
אמורה להופיע תוצאה דומה לזו:

מה קרה?
- מילוי חוסרים בהיקף נרחב: המערכת סורקת באופן אוטומטי את 50,000 השורות הקיימות ויוצרת הטמעות באמצעות Vertex AI.
- אוטומציה: כשמגדירים את incremental_refresh_mode => 'transactional', AlloyDB מגדיר באופן אוטומטי את הטריגרים הפנימיים. כל שורה חדשה שתוסיפו ל-help_articles תכלול הטמעה שתיווצר באופן מיידי.
- אפשר גם להגדיר את incremental_refresh_mode => ‘None' כדי לקבל רק את ההצהרה לביצוע עדכון מספר פריטים בו-זמנית, ולקרוא באופן ידני ל-ai.refresh_embeddings() כדי לעדכן את ההטמעות של כל השורות.
החלפתם תור של Kafka, קובץ Python וסקריפט העברה ב-6 שורות של SQL. במסמכים הרשמיים מופיע פירוט של כל המאפיינים.
בדיקת טריגר בזמן אמת
בואו נוודא שהאוטומציה של "אפס לולאות" פועלת על נתונים חדשים.
- הוספת שורה חדשה:
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.');
- בדיקה מיידית:
SELECT embedding FROM help_articles WHERE title = 'New Scaling Guide';
התוצאה:
הווקטור אמור להיווצר באופן מיידי בלי להריץ סקריפט חיצוני.
גודל אצווה לכוונון
כרגע, גודל ברירת המחדל של האצווה ב-AlloyDB הוא 50. למרות שברירות המחדל פועלות מצוין, 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',
batch_size => 20
);
עם זאת, המשתמשים צריכים להיות מודעים למגבלות המכסה שיכולות להגביל את הביצועים. כדי לבדוק את המכסות המומלצות של AlloyDB, עיינו בקטע "לפני שמתחילים" במסמכי התיעוד.
בעיות נפוצות ופתרון בעיות
הפער בהפצה של IAM | הפעלתם את פקודת ה-IAM |
חוסר התאמה בין מאפייני וקטורים | הטבלה |
6. חיפוש לפי הקשר גמיש
עכשיו נבצע חיפוש היברידי. אנחנו משלבים הבנה סמנטית (וקטור) עם לוגיקה עסקית (מסנני SQL).
כדי למצוא בעיות חיוב שקשורות ספציפית לגרסה 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;
זהו הקשר גמיש. החיפוש "גמיש" כדי להבין את כוונת המשתמש ("בעיות בחיוב") תוך כיבוד האילוצים העסקיים הנוקשים (גרסה 2.0).

למה זה טוב לסטארט-אפים ולהעברות
- אפס חובות בתשתית: לא הפעלתם מסד נתונים וקטורי נפרד (Pinecone/Milvus). לא כתבתם משימת ETL נפרדת. הכול ב-Postgres.
- עדכונים בזמן אמת: כשמשתמשים במצב "טרנזקציונלי", אינדקס החיפוש אף פעם לא מיושן. ברגע שהנתונים נשמרים, הם מוכנים לווקטורים.
- סקיילינג: AlloyDB מבוסס על התשתית של Google. הוא יכול ליצור מיליוני וקטורים בבת אחת, הרבה יותר מהר מסקריפט Python.
בעיות נפוצות ופתרון בעיות
בעיה בביצועים בסביבת הייצור | הבעיה: מהיר ל-50,000 שורות. איטי מאוד למיליון שורות אם סינון לפי קטגוריות לא מספיק סלקטיבי.פתרון:מוסיפים אינדקס וקטורי: בשביל קנה מידה של ייצור, צריך ליצור אינדקס:CREATE INDEX ON help_articles USING hnsw (embedding vector_cosine_ops);אימות השימוש באינדקס: מריצים את |
האסון של "חוסר התאמה בין מודלים" | הבעיה: הפעלתם את העמודה באמצעות text-embedding-005 בפרוצדורה CALL. אם משתמשים בטעות במודל אחר (למשל, text-embedding-004 או מודל OSS) בפונקציית השאילתה SELECT embedding('model-name', ...), יכול להיות שהמאפיינים יהיו תואמים (768), אבל מרחב הווקטורים יהיה שונה לגמרי. השאילתה פועלת בלי שגיאה, אבל התוצאות לא רלוונטיות בכלל (ציוני רלוונטיות חסרי משמעות). פתרון בעיות:מוודאים שה-model_id ב-ai.initialize_embeddings תואם בדיוק ל-model_id בשאילתת SELECT. |
התוצאה "ריק ושקט" (סינון יתר) | הבעיה: חיפוש היברידי הוא פעולת "AND". היא דורשת התאמה סמנטית וגם התאמת SQL.אם משתמש מחפש "עזרה בנושא חיוב" אבל בעמודה
|
4. שגיאות שקשורות להרשאות או למכסות (שגיאה 500) | הבעיה:הפונקציה
|
5. הטמעות ריקות | הבעיה:אם מוסיפים נתונים לפני שהמודל מאותחל לגמרי או אם ה-background worker נכשל, יכול להיות שבחלק מהשורות יופיע הערך
|
7. הסרת המשאבים
בסיום ה-Lab, אל תשכחו למחוק את האשכול והמכונה של AlloyDB.
הוא אמור לנקות את האשכול יחד עם המכונות שלו.
8. מזל טוב
יצרתם בהצלחה אפליקציית חיפוש במאגר ידע שניתן להתאים לעומס. במקום לנהל צינור עיבוד נתונים מורכב של ETL עם סקריפטים ולולאות של Python כדי ליצור הטמעות וקטורים, השתמשתם ב-AlloyDB AI כדי לטפל ביצירת הטמעות באופן מקורי בתוך מסד הנתונים באמצעות פקודת SQL אחת.
מה למדנו
- הפסקנו להשתמש ב-Python For-Loop לעיבוד נתונים.
- יצרנו 50,000 וקטורים באמצעות פקודת SQL אחת.
- הגדרנו טריגרים כדי להפוך את יצירת הווקטורים לאוטומטית.
- ביצענו חיפוש היברידי.
השלבים הבאים
- נסו את זה עם מערך נתונים משלכם.
- מסמכי התיעוד של AlloyDB AI
- באתר Code Vipassana יש סדנאות נוספות.