התקנה והגדרה של Toolbox לאפליקציות של AI גנרטיבי ו-Agentic ב-AlloyDB

1. סקירה כללית

Gen AI Toolbox for Databases הוא שרת בקוד פתוח של Google שמאפשר ליצור בקלות כלים של בינה מלאכותית גנרטיבית ליצירת אינטראקציה עם מסדי נתונים. הוא מאפשר לפתח כלים בקלות, במהירות ובאופן מאובטח יותר, על ידי טיפול בבעיות מורכבות כמו מאגר חיבורים, אימות ועוד. הוא עוזר לכם ליצור כלים של AI גנרטיבי שמאפשרים לנציגים לגשת לנתונים במסד הנתונים שלכם. ארגז הכלים מספק:

פיתוח פשוט יותר: שילוב כלים בסוכנות בפחות מ-10 שורות קוד, שימוש חוזר בכלים בין כמה סוכני או מסגרות, ופריסה קלה יותר של גרסאות חדשות של כלים.

ביצועים משופרים: שיטות מומלצות כמו מאגר חיבורים, אימות ועוד.

אבטחה משופרת: אימות משולב לגישה מאובטחת יותר לנתונים.

יכולת תצפית מקצה לקצה: מדדים ומעקב מובנים עם תמיכה מובנית ב-OpenTelemetry.

Toolbox נמצא בין מסגרת התזמור של האפליקציה לבין מסד הנתונים, ומספק מישור בקרה שמשמש לשינוי, להפצה או להפעלה של כלים. הכלי הזה מפשט את ניהול הכלים על ידי מתן מיקום מרכזי לאחסון ולעדכון של כלים, ומאפשר לכם לשתף כלים בין סוכנים ואפליקציות ולעדכן את הכלים האלה בלי שתצטרכו לפרוס מחדש את האפליקציה.

מה תפַתחו

במסגרת הסדנה הזו, תלמדו ליצור אפליקציה שמשתמשת בכלי כדי לבצע שאילתת מסד נתונים פשוטה (AlloyDB) שאפשר להפעיל מהסוכן או מאפליקציית ה-AI הגנרטיבית. לשם כך, צריך

1. התקנת ארגז הכלים
2. מגדירים את הכלי (שמיועד לבצע משימה ב-AlloyDB) בשרת Toolbox
3. פריסת Toolbox ב-Cloud Run
4. בדיקת הכלי באמצעות נקודת הקצה של Cloud Run שנפרסה
5. פיתוח הפונקציה של Cloud Run להפעלת Toolbox

דרישות

• דפדפן, כמו Chrome או Firefox
• פרויקט ב-Google Cloud שבו החיוב מופעל (השלבים מפורטים בקטע הבא).

2. לפני שמתחילים

יצירת פרויקט

1. בדף לבחירת הפרויקט במסוף Google Cloud, בוחרים או יוצרים פרויקט ב-Google Cloud.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
3. תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud. לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.

4. אחרי שמתחברים ל-Cloud Shell, בודקים אם כבר בוצע אימות ואם הפרויקט מוגדר למזהה הפרויקט הנכון באמצעות הפקודה הבאה:

gcloud auth list

5. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהפקודה gcloud מכירה את הפרויקט.

gcloud config list project

6. אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

7. מפעילים את ממשקי ה-API הנדרשים על ידי הרצת הפקודות הבאות בטרמינל של Cloud Shell, אחת אחרי השנייה:

יש גם פקודה אחת להפעלת הפקודות הבאות, אבל אם אתם משתמשים בחשבון לניסיון, יכול להיות שתתקלו בבעיות שקשורות למכסות אם תנסו להפעיל אותן בכמות גדולה. לכן, כל פקודה מופיעה בשורה נפרדת.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

החלופה לפקודה gcloud היא דרך המסוף, על ידי חיפוש של כל מוצר או באמצעות הקישור הזה.

אם חסר ממשק API כלשהו, תמיד תוכלו להפעיל אותו במהלך ההטמעה.

במסמכי העזרה מפורטות הפקודות של gcloud והשימוש בהן.

3. הגדרת מסד נתונים

במעבדה הזו נשתמש ב-AlloyDB כמסד הנתונים שיאחסן את נתוני הקמעונאות. הוא משתמש באשכולות כדי לאחסן את כל המשאבים, כמו מסדי נתונים יומנים. לכל אשכול יש מכונה ראשית שמספקת נקודת גישה לנתונים. הטבלאות יכללו את הנתונים בפועל.

נלמד ליצור אשכול, מכונה וטבלה ב-AlloyDB שבהם ייטען מערך הנתונים של המסחר האלקטרוני.

יצירת אשכול ומכונה

1. נכנסים לדף AlloyDB במסוף Cloud.

דרך קלה למצוא את רוב הדפים במסוף Cloud היא לחפש אותם באמצעות סרגל החיפוש במסוף.

2. בוחרים באפשרות CREATE CLUSTER (יצירת אשכול) בדף הזה:

3. יוצג מסך כמו זה שבהמשך. יוצרים אשכול ומכונה עם הערכים הבאים (חשוב לוודא שהערכים תואמים במקרה שמשכפלים את קוד האפליקציה מהמאגר):

• מזהה האשכולות: vector-cluster
• סיסמה: "alloydb"
• תאימות ל-PostgreSQL 15
• אזור: 'us-central1'
• רשתות: "default"

4. כשבוחרים את רשת ברירת המחדל, מוצג מסך כמו זה שבהמשך. בוחרים באפשרות 'הגדרת חיבור'.
   
5. לאחר מכן, בוחרים באפשרות 'שימוש בטווח כתובות IP שהוקצה באופן אוטומטי' וממשיכים. אחרי שבודקים את המידע, בוחרים באפשרות 'יצירת חיבור'.
6. אחרי שמגדירים את הרשת, אפשר להמשיך ליצור את האשכולות. לוחצים על CREATE CLUSTER כדי להשלים את הגדרת האשכולות, כפי שמתואר בהמשך:

חשוב לשנות את מזהה המכונה ל-"

vector-instance"

.

לתשומת ליבכם: יצירת האשכולות תימשך כ-10 דקות. לאחר השלמת הפעולה, אמור להופיע מסך עם סקירה כללית של האשכולות שיצרתם.

4. הטמעת נתונים

עכשיו הגיע הזמן להוסיף טבלה עם הנתונים על החנות. עוברים אל AlloyDB, בוחרים את האשכול הראשי ואז את AlloyDB Studio:

יכול להיות שתצטרכו להמתין עד לסיום יצירת המכונה. בסיום, נכנסים ל-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;

כדי לבדוק את התוספים שהופעלו במסד הנתונים, מריצים את פקודת ה-SQL הבאה:

select extname, extversion from pg_extension;

צור טבלה

יוצרים טבלה באמצעות משפט ה-DDL הבא:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

אם הפקודה שלמעלה תתבצע בהצלחה, אמורה להופיע לכם הטבלה במסד הנתונים.

הטמעת נתונים

בשיעור ה-Lab הזה יש לנו נתוני בדיקה של כ-72 רשומות בקובץ ה-SQL הזה. הוא מכיל את השדות id, name, description, quantity, price, image_url. השדות האחרים יאוכלסו בשלב מאוחר יותר במהלך הסדנה.

מעתיקים משם את השורות או את הוראות ההוספה, מדביקים את השורות האלה בכרטיסייה ריקה של עורך ומקישים על 'הפעלה'.

כדי לראות את תוכן הטבלה, מרחיבים את הקטע 'כלי המחקר' עד שמופיעה הטבלה apparels. לוחצים על סמל הנקודות השלושה (⋮) כדי להציג את האפשרות לשלוח שאילתה לטבלה. תנאי SELECT ייפתח בכרטיסייה חדשה ב-Editor.

מתן הרשאה

מריצים את ההצהרה הבאה כדי להעניק למשתמש postgres זכויות הפעלה על הפונקציה embedding:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

הקצאת התפקיד Vertex AI User לחשבון השירות של AlloyDB

נכנסים לטרמינל של 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. יצירת הטמעות (embeddings) להקשר

קל יותר למחשבים לעבד מספרים מאשר לעבד טקסט. מערכת הטמעה ממירה טקסט לסדרה של מספרים בנקודה צפה, שנקראים הטמעות וקטוריות, שאמורות לייצג את הטקסט, ללא קשר לאופן שבו הוא מנוסח, לשפה שבה הוא כתוב וכו'.

לדוגמה, מיקום על חוף הים יכול להיקרא 'על המים', 'חוף הים', 'הליכה מהחדר לאוקיינוס', 'sur la mer', 'на берегу океана' וכו'. כל המונחים האלה נראים שונים, אבל המשמעות הסמנטית שלהם, או בטרמינולוגיה של למידת מכונה, הטמעות הנתונים שלהם אמורות להיות קרובות מאוד זו לזו.

עכשיו, כשהנתונים וההקשר מוכנים, נריץ את שאילתת ה-SQL כדי להוסיף את הטמעות התיאור של המוצר לטבלה בשדה embedding. יש מגוון מודלים להטמעה שאפשר להשתמש בהם. אנחנו משתמשים ב-text-embedding-005 מ-Vertex AI. חשוב להשתמש באותו מודל הטמעה לאורך כל הפרויקט.

הערה: אם אתם משתמשים בפרויקט ישן ב-Google Cloud, יכול להיות שתצטרכו להמשיך להשתמש בגרסאות ישנות יותר של מודל הטמעת הטקסט, כמו textembedding-gecko.

חוזרים לכרטיסייה AlloyDB Studio ומקלידים את ה-DML הבא:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

בודקים שוב את הטבלה toys כדי לראות כמה הטמעות. חשוב להריץ מחדש את ביטוי ה-SELECT כדי לראות את השינויים.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

הפונקציה הזו אמורה להחזיר את וקטור הטמעת הנתונים (embedding), שנראה כמו מערך של מספרים שמוצגים בספרות עשרוניות, של תיאור הצעצוע, כפי שמוצג בהמשך:

הערה: פרויקטים חדשים ב-Google Cloud שנוצרו ברמת התמחור 'חינם' עשויים להיתקל בבעיות במכסות לגבי מספר הבקשות להטמעה שמותר לשלוח בשנייה למודל ההטמעה. מומלץ להשתמש בשאילתת סינון למזהה, ואז לבחור באופן סלקטיבי 1-5 רשומות וכן הלאה, בזמן יצירת ההטמעה.

6. ביצוע חיפוש Vector

עכשיו, כשהטבלה, הנתונים וההטמעות מוכנים, נבצע חיפוש וקטורים בזמן אמת של טקסט החיפוש של המשתמש.

נניח שהמשתמש שואל:

I want a white plush teddy bear toy with a floral pattern.

כדי למצוא התאמות לכך, מריצים את השאילתה הבאה:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

נבחן את השאילתה הזו בפירוט:

בשאילתה הזו,

1. טקסט החיפוש של המשתמש הוא: "I want a white plush teddy bear toy with a floral pattern."
2. אנחנו ממירים אותו להטמעות (embeddings) בשיטה embedding() באמצעות המודל: text-embedding-005. השלב הזה אמור להיראות מוכר אחרי השלב האחרון, שבו החלנו את פונקציית ההטמעה על כל הפריטים בטבלה.
3. הערך '<=>' מייצג את השימוש בשיטת המרחק COSINE SIMILARITY. כל מדדי הדמיון הזמינים מפורטים במסמכי התיעוד של pgvector.
4. אנחנו ממירים את התוצאה של שיטת ההטמעה לסוג וקטור כדי שהיא תהיה תואמת לווקטורים שמאוחסנים במסד הנתונים.
5. LIMIT 5 מייצג שאנחנו רוצים לחלץ 5 שכנים קרובים ביותר לטקסט החיפוש.

התוצאה נראית כך:

כפי שניתן לראות בתוצאות, ההתאמות דומות מאוד לטקסט החיפוש. נסו לשנות את הטקסט כדי לראות איך התוצאות משתנות.

7. הכנת AlloyDB לאינטראקציה עם Toolbox

כהכנה להגדרת Toolbox, נפעיל את היכולת להתחבר לכתובת IP ציבורית במכונה של AlloyDB כדי שהכלי החדש יוכל לגשת למסד הנתונים.

1. עוברים למכונה של AlloyDB, לוחצים על 'עריכה' ומגיעים לדף Edit primary instance (עריכת המכונה הראשית).
2. עוברים לקטע Public IP connectivity (קישוריות של כתובת IP ציבורית), מסמנים את התיבה Enable public IP (הפעלת כתובת IP ציבורית) ומזינים את כתובת ה-IP של המכונה ב-Cloud Shell.
3. כדי לקבל את כתובת ה-IP של המכונה ב-Cloud Shell, עוברים ל-Cloud Shell Terminal ומזינים ifconfig. בתוצאה, מזהים את כתובת ה-inet של eth0 ומחליפים את שתי הספרות האחרונות ב-0.0 עם גודל מסכה של '/16'. לדוגמה, הפורמט הוא 'XX.XX.0.0/16', כאשר XX הם מספרים.
4. מדביקים את כתובת ה-IP הזו בתיבת הטקסט 'רשתות' בקטע 'רשתות חיצוניות מורשות' בדף העריכה של המכונה.

5. בסיום, לוחצים על UPDATE INSTANCE (עדכון המכונה).

התהליך יימשך כמה דקות.

8. התקנת ארגז הכלים

1. אפשר ליצור תיקיית פרויקט לאחסון פרטי הכלי. במקרה הזה, מכיוון שאנחנו עובדים על נתונים של חנות צעצועים, נוצר תיקייה בשם 'toystore' ונכנס אליה. עוברים אל Cloud Shell Terminal ומוודאים שהפרויקט נבחר ומוצג בהודעה שמופיעה בטרמינל. מריצים את הפקודה הבאה בטרמינל של Cloud Shell:

mkdir toystore

cd toystore

2. מריצים את הפקודה הבאה כדי להוריד ולהתקין את Toolbox בתיקייה החדשה:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. עוברים ל-Cloud Shell Editor. מרחיבים את התיקייה החדשה 'toystore' ויוצרים קובץ חדש בשם tools.yaml. מעתיקים את התוכן שלמטה. מחליפים את YOUR_PROJECT_ID ובודקים אם כל שאר פרטי החיבור נכונים.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

בכלי הזה אנחנו פשוט מחפשים את ההתאמה הקרובה ביותר לטקסט החיפוש של המשתמש (תיאור מותאם אישית של צעצוע) ומחזירים את המחיר שלו. אפשר גם לשנות את הנוסחה כדי למצוא את המחיר הממוצע של 5 הצעצועים הכי דומים:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

הגדרת הכלי מוכנה!

פרטים נוספים על הגדרת קובץ tools.yaml מופיעים במסמכי העזרה האלה.

4. עוברים למסוף Cloud Shell ומזינים את הפקודה הבאה כדי להפעיל את שרת Toolbox עם הגדרות הכלים:

./toolbox --tools_file "tools.yaml"

5. עכשיו, אם פותחים את השרת במצב תצוגה מקדימה באינטרנט בענן, אמור להופיע שרת Toolbox שפועל עם הכלי החדש בשם get-toy-price.

9. פריסת Toolbox ב-Cloud Run

עכשיו נפרוס אותו ב-Cloud Run כדי שתוכלו להשתמש בכלי הזה בפועל.

1. פועלים לפי ההוראות שמפורטות בדף הזה, אחת אחרי השנייה, עד שמגיעים לפקודה gcloud run deploy toolbox שמופיעה בנקודה השלישית בקטע 'פריסה ב-Cloud Run'. צריך לבחור באפשרות הראשונה ולא באפשרות השנייה, שמתאימה לשימוש בשיטה של רשת VPC.
2. לאחר הפריסה, תקבלו נקודת קצה (endpoint) של Cloud Run שפורסה בשרת Toolbox. בודקים את זה באמצעות פקודת CURL.

הכול מוכן לשימוש בכלי החדש שנפרס באפליקציה של הסוכנות שלך!!!

10. קישור האפליקציה ל-Toolbox

בקטע הזה נבנה אפליקציה קטנה כדי לבדוק את היכולת של הכלי שלכם לתקשר עם הצרכים של האפליקציה ולשלוף תגובה.

1. עוברים אל Google Colab ופותחים מחברת חדשה.
2. מריצים את הקוד הבא ב-notebook

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. התוצאה אמורה להיראות כך:

זהו הכלי שמופעל במפורש באפליקציית Python שמשתמשת בכלי toolbox-langchain.

4. אם רוצים להשתמש בכלי הזה ולקשר אותו לסוכנות באפליקציה משולבת של LangGraph, אפשר לעשות זאת בקלות באמצעות ערכת הכלים langgraph.
5. אפשר לעיין בקטעי הקוד לקבלת מידע נוסף.

11. העברה לענן!!!

עכשיו נארוז את קטע הקוד הזה ב-Python ב-Cloud Run Functions כדי להפוך אותו ללא שרת.

1. מעתיקים את המקור מתיקיית מאגר הקוד כדי להעביר אותו ל-Cloud Functions.
2. נכנסים למסוף Cloud Run Functions ולוחצים על CREATE FUNCTION.
3. משאירים את האימות מושבת באפליקציית הדגמה ובוחרים את סביבת זמן הריצה Python 3.11 בדף הבא.
4. מעתיקים את הקבצים main.py ו-requirements.txt מהמאגר המקור ששותף בשלב 1 ומדביקים אותם בקבצים המתאימים.
5. פורסים את הפונקציה ומקבלים נקודת קצה מסוג REST שדרכה ניתן לגשת לכלי החיזוי של המחירים באפליקציית האינטרנט של חנות הצעצועים.
6. נקודת הקצה אמורה להיראות כך:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. אפשר לבדוק אותה ישירות במסוף Cloud Functions. לשם כך, עוברים לכרטיסייה TESTING ומזינים את הקלט הבא לבקשת הבדיקה:

{

               "`search`"`:` "`White plush toy`"

}

3. לוחצים על 'בדיקת הפונקציה' או מריצים את הקוד ב-Cloud Shell Terminal, לפי האפשרות שבחרתם. התוצאה אמורה להופיע בצד שמאל, מתחת לכותרת 'פלט':

12. מזל טוב

מעולה! סיימתם ליצור כלי חזק ומעולה שמבוסס על מודולים, שיכול לקיים אינטראקציה עם מסדי נתונים, פלטפורמות ומסגרות תזמור של AI גנרטיבי כדי לעזור לכם ליצור את האפליקציה של הסוכן.