התקנה והגדרה של ארגז הכלים של MCP למסדי נתונים עבור בינה מלאכותית גנרטיבית ואפליקציות Agentic ב- AlloyDB

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

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

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

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

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

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

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

מה תפַתחו

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

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

דרישות

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

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

יצירת פרויקט

1. ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
2. מוודאים שהחיוב מופעל בפרויקט ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
3. תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud. לוחצים על 'הפעלת 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. הגדרת מסד נתונים

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

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

יצירת אשכול ומופע

1. עוברים לדף AlloyDB במסוף Cloud.

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

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

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

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

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

חשוב לשנות את מזהה המופע ל-

vector-instance"

.

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

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

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

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

• שם משתמש : "postgres"
• מסד נתונים : "postgres"
• סיסמה : "alloydb"

אחרי שתעברו את תהליך האימות ב-AlloyDB Studio, תוכלו להזין פקודות SQL בעורך. אפשר להוסיף כמה חלונות של Editor באמצעות סימן הפלוס שמימין לחלון האחרון.

אפשר להזין פקודות ל-AlloyDB בחלונות עריכה, ולהשתמש באפשרויות 'הפעלה', 'עיצוב' ו'ניקוי' לפי הצורך.

הפעלת תוספים

כדי ליצור את האפליקציה הזו, נשתמש בתוספים 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. שאר השדות ימולאו בהמשך במעבדה.

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

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

מתן הרשאה

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

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

עוברים לטרמינל של 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. יצירת הטמעות להקשר

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

לדוגמה, מיקום ליד הים יכול להיקרא "על המים", "מול החוף", "הליכה מהחדר לאוקיינוס", "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;

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

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

6. ביצוע חיפוש וקטור

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

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

‫"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. אנחנו ממירים אותו להטמעות בשיטה embedding() באמצעות המודל: text-embedding-005. השלב הזה אמור להיראות מוכר אחרי השלב הקודם, שבו הפעלנו את פונקציית ההטמעה על כל הפריטים בטבלה.
3. ‫<=> מייצג את השימוש בשיטת המרחק COSINE SIMILARITY. אפשר למצוא את כל מדדי הדמיון שזמינים בתיעוד של pgvector.
4. אנחנו ממירים את התוצאה של שיטת ההטמעה לסוג וקטור כדי שתהיה תואמת לווקטורים שמאוחסנים במסד הנתונים.
5. הערך LIMIT 5 מייצג את העובדה שאנחנו רוצים לחלץ 5 שכנים קרובים ביותר לטקסט החיפוש.

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

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

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

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

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

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

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

8. התקנה של MCP Toolbox for Databases

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

mkdir toystore

cd toystore

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

# 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 --tools_file "tools.yaml"

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

9. פריסה של MCP Toolbox למסדי נתונים ב-Cloud Run

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

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

טיפים:

פועלים בקפידה לפי ההוראות שבדף.

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

10. חיבור האפליקציה ל-MCP Toolbox for Databases

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

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

!pip install toolbox-core
from toolbox_core import ToolboxClient

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

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

# 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. העברה ל-Cloud!!!

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

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

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

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

{

           "search": "White plush toy"

}

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

12. מזל טוב

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