מידע על Codelab זה
1. סקירה כללית
MCP Toolbox for Databases הוא שרת בקוד פתוח של Google שמאפשר לפתח בקלות כלים של AI גנרטיבי לאינטראקציה עם מסדי נתונים. הוא מאפשר לפתח כלים בקלות, במהירות ובאופן מאובטח יותר, על ידי טיפול בבעיות מורכבות כמו מאגר חיבורים, אימות ועוד. הוא עוזר לפתח כלים של AI גנרטיבי שמאפשרים לנציגים לגשת לנתונים במסד הנתונים שלכם. ארגז הכלים מספק:
פיתוח פשוט יותר: אפשר לשלב כלים לנציג בפחות מ-10 שורות קוד, לעשות שימוש חוזר בכלים בין כמה סוכנים או frameworks ולפרוס גרסאות חדשות של כלים בקלות רבה יותר.
ביצועים משופרים: שיטות מומלצות כמו מאגר חיבורים, אימות ועוד.
אבטחה משופרת: אימות משולב לגישה מאובטחת יותר לנתונים.
ניראות (observability) מקצה לקצה: מדדים מחוץ לאריזה ומעקב עם תמיכה מובנית ב-OpenTelemetry.
Toolbox נמצא בין מסגרת התזמור של האפליקציה לבין מסד הנתונים, ומספק מישור בקרה שמשמש לשינוי, להפצה או להפעלה של כלים. הכלי הזה מפשט את ניהול הכלים על ידי מתן מיקום מרכזי לאחסון ולעדכון של כלים, ומאפשר לכם לשתף כלים בין סוכנים ואפליקציות ולעדכן את הכלים האלה בלי שתצטרכו לפרוס מחדש את האפליקציה.
מה תפַתחו
במסגרת שיעור ה-Lab הזה, תיצרו אפליקציה שמתבססת על כלי לביצוע שאילתה פשוטה של מסד נתונים (AlloyDB) שאפשר להפעיל מהסוכן או מאפליקציית הבינה המלאכותית הגנרטיבית. כדי לעשות את זה,
- התקנת ארגז הכלים של MCP למסדי נתונים
- הגדרת הכלי (שמיועד לביצוע משימה ב- AlloyDB) בשרת ארגז הכלים
- פריסת ארגז כלים של MCP למסדי נתונים ב-Cloud Run
- בדיקת הכלי באמצעות נקודת הקצה של Cloud Run שנפרסה
- יצירת הפונקציה של Cloud Run כדי להפעיל את ארגז הכלים
דרישות
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 הנדרשים, מריצים את הפקודות הבאות אחת אחרי השנייה בטרמינל של 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, מכונה וטבלה שבהם ייטען מערך הנתונים של המסחר האלקטרוני.
יצירת אשכול ומכונה
- מנווטים בדף AlloyDB במסוף Cloud.
אחת הדרכים למצוא בקלות את רוב הדפים במסוף Cloud היא לחפש אותם באמצעות סרגל החיפוש של המסוף.
- בוחרים באפשרות 'יצירת אשכול' מהדף הזה:
- יוצג מסך כמו זה שמופיע למטה. יוצרים אשכול ומכונה עם הערכים הבאים (צריך לוודא שהערכים תואמים למקרה שמשכפלים את קוד האפליקציה מהמאגר):
- מזהה האשכול: "
vector-cluster" - סיסמה: "
alloydb" - תואם ל-PostgreSQL 15
- אזור: "
us-central1" - רשתות: "
default"
- כשבוחרים את רשת ברירת המחדל, מופיע מסך כמו זה שמופיע בהמשך. לוחצים על 'הגדרת חיבור'.
- משם, בוחרים באפשרות 'שימוש בטווח IP שמוקצה באופן אוטומטי' ולוחצים על 'המשך'. אחרי שבודקים את המידע, לוחצים על 'יצירת חיבור'.
- אחרי שהרשת מוגדרת, תוכלו להמשיך ביצירת האשכול. לוחצים על CREATE cluster כדי להשלים את הגדרת האשכול כמו שמוצג כאן:
חשוב לשנות את מזהה המופע ל-"
vector-instance"
.
שימו לב שיצירת האשכול תימשך כ-10 דקות. לאחר בהצלחה, אמור להופיע מסך עם הסקירה הכללית של האשכול שיצרתם.
4. הטמעת נתונים
בשלב הזה מוסיפים טבלה עם הנתונים על החנות. עוברים אל AlloyDB, בוחרים את האשכול הראשי ואז את AlloyDB Studio:
יכול להיות שתצטרכו להמתין עד שיצירת המכונה תסתיים. בסיום התהליך, נכנסים ל- AlloyDB באמצעות פרטי הכניסה שיצרתם במהלך יצירת האשכול. צריך להשתמש בנתונים הבאים לצורך אימות ב-PostgreSQL:
- שם המשתמש: "
postgres" - מסד נתונים : "
postgres" - סיסמה : "
alloydb"
אחרי השלמת האימות ב- AlloyDB Studio, ניתן להזין פקודות SQL בעורך. כדי להוסיף כמה חלונות עריכה, לוחצים על סימן הפלוס שמימין לחלון האחרון.
אפשר להזין פקודות ל- 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. השדות האחרים ימולאו בהמשך שיעור ה-Lab.
מעתיקים את השורות/מוסיפים את ההצהרות משם ולאחר מכן מדביקים את השורות האלה בכרטיסיית עריכה ריקה ובוחרים באפשרות 'הרצה'.
כדי לראות את תוכן הטבלה, מרחיבים את הקטע 'סייר' עד שאפשר לראות את הטבלה בשם 'הלבשה'. לוחצים על סימן הטריקולון (⋮) כדי לראות את האפשרות להריץ שאילתות על הטבלה. ההצהרה SELECT תיפתח בכרטיסיית עריכה חדשה.
מתן הרשאה
מריצים את ההצהרה הבאה כדי להעניק למשתמש postgres הרשאות הפעלה בפונקציה embedding:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
הקצאת תפקיד המשתמש של Vertex AI לחשבון השירות של 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. יצירת הטמעות עבור ההקשר
למחשבים הרבה יותר קל לעבד מספרים מאשר לעבד טקסט. מערכת הטמעה ממירה טקסט לסדרה של מספרים עם נקודה צפה (floating-point) שנקראים הטמעות וקטוריות, שאמורות לייצג את הטקסט בלי קשר לאופן שבו הוא מנוסח, באיזו שפה הוא משתמש וכו'.
לדוגמה, מיקום על שפת הים עשוי להיות נקרא "על המים", "חוף הים", "הליכה מהחדר שלך לאוקיינוס", "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;
נבחן את השאילתה הזו לעומק:
בשאילתה הזו,
- הטקסט של המשתמש לחיפוש הוא: "
I want a white plush teddy bear toy with a floral pattern." - אנחנו ממירים אותו להטמעות בשיטה
embedding()באמצעות המודל:text-embedding-005. השלב הזה צריך להיראות מוכר אחרי השלב האחרון שבו החלנו את פונקציית ההטמעה על כל הפריטים בטבלה. - "
<=>" מייצג את השימוש בשיטת המרחק COSINE PREVIEWITY. תוכלו למצוא את כל מדדי הדמיון שזמינים במסמכי התיעוד של pgvector. - אנחנו ממירים את התוצאה של שיטת ההטמעה לסוג וקטור, כדי שתהיה תואמת לווקטורים שמאוחסנים במסד הנתונים.
- הערך LIMIT 5 מייצג שאנחנו רוצים לחלץ 5 שכנים קרובים לטקסט החיפוש.
התוצאה נראית כך:
כפי שאפשר לראות בתוצאות, ההתאמות די קרובות לטקסט החיפוש. אפשר לנסות לשנות את הטקסט כדי לראות איך התוצאות משתנות.
7. הכנה של AlloyDB לאינטראקציה בארגז הכלים
כהכנה להגדרת ארגז הכלים, נפעיל קישוריות IP ציבורית במכונת AlloyDB שלנו, כדי שלכלי החדש תהיה גישה למסד הנתונים.
- נכנסים למופע של AlloyDB, לוחצים על 'עריכה' ומגיעים לדף 'עריכת המופע הראשי'.
- עוברים לקטע Public IP Connect (קישוריות IP ציבורי), מסמנים את התיבה Enable Public IP (הפעלת כתובת IP ציבורית) ומזינים את כתובת ה-IP של מכונת Cloud Shell.
- כדי למצוא את כתובת ה-IP של מכונה ב-Cloud Shell, נכנסים לטרמינל של Cloud Shell ומזינים את הערך ifconfig. בתוצאה, צריך לזהות את הכתובת eth0 inet ולהחליף את שתי הספרות האחרונות ב-0.0 בגודל מסכה '/16'. לדוגמה, ייראה כך: XX.XX.0.0/16, כאשר XX הוא מספרים.
- מדביקים את כתובת ה-IP הזו בתיבת הטקסט 'רשתות חיצוניות מורשות' בדף של עריכת המכונה.
- בסיום, לוחצים על 'עדכון עדכון'.
הפעולה הזאת עשויה להימשך כמה דקות.
8. ארגז כלים של MCP להתקנת מסדי נתונים
- אפשר ליצור תיקיית פרויקט לאחסון פרטי הכלי. במקרה כזה, מכיוון שאנחנו עובדים על נתונים של חנות צעצועים, כדאי ליצור תיקייה בשם "toystore" וננווט אליה. עוברים אל Cloud Shell Terminal ומוודאים שהפרויקט נבחר ומוצג בהנחיה של הטרמינל. מריצים את הפקודה הבאה מהטרמינל של Cloud Shell:
mkdir toystore
cd toystore
- כדי להוריד ולהתקין את ארגז הכלים בתיקייה החדשה, מריצים את הפקודה הבאה:
# 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
- עוברים אל Cloud Shell Editor. מרחיבים את התיקייה החדשה שנוצרה בשם "toystore" ויוצרים קובץ חדש בשם tools.yaml. מעתיקים את התוכן שלמטה. מחליפים את שלכם_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 זמינים במסמכי התיעוד.
- עוברים ל-Cloud Shell Terminal ומזינים את הפקודה הבאה כדי להפעיל את שרת ארגז הכלים עם הגדרת הכלים שלכם:
./toolbox --tools_file "tools.yaml"
- עכשיו, אם פותחים את השרת במצב תצוגה מקדימה לאינטרנט בענן, הוא אמור להופיע כשרת ארגז הכלים עם הכלי החדש בשם
get-toy-price..
9. פריסת Cloud Run של ארגז הכלים של MCP למסדי נתונים
בואו נפרוס אותו ב-Cloud Run כדי שתוכלו להשתמש בכלי בפועל.
- פועלים לפי ההוראות בדף הזה אחת אחרי השנייה, עד שמגיעים לפקודה
gcloud run deploy toolboxשנמצאת בנקודה השלישית בקטע Deploy to Cloud Run. נדרשת האפשרות הראשונה, ולא האפשרות השנייה שמתאימה לשימוש בשיטת רשת VPC. - לאחר הפריסה בהצלחה, תקבלו נקודת קצה (endpoint) של Cloud Run שנפרסה בשרת ארגז הכלים שלכם. אפשר לבדוק אותו באמצעות פקודת CURL.
טיפים:
יש לפעול לפי ההוראות שבדף בקפידה ולא לפספס.
הכול מוכן ואפשר להתחיל להשתמש בכלי החדש שנפרס באפליקציה הסוכןת.
10. קישור האפליקציה באמצעות ארגז הכלים של MCP למסדי נתונים
בחלק הזה נבנה אפליקציה קטנה כדי לבדוק את הכלי שלכם כדי שיוכלו לענות על צורכי האפליקציה ולאחזר תגובות.
- עוברים אל Google Colab ופותחים notebook חדש.
- מריצים את הפקודה הבאה ב-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)
- התוצאה אמורה להיות כך:
זהו הכלי שמופעל באופן מפורש באפליקציית Python שמשתמשת בערכת הכלים toolbox-langchain.
- אם רוצים להשתמש בכלי ולקשר אותו לסוכן בתוך אפליקציה משולבת של LangGraph, אפשר לעשות זאת בקלות באמצעות ערכת הכלים
langgraph. - לשם כך, אפשר לעיין בקטעי הקוד.
11. קחו אותו לענן.
בואו ארוז את קטע קוד Python בפונקציות של Cloud Run כדי להפוך אותו ללא שרת (serverless).
- כדי להעביר את הקובץ ל-Cloud Functions, מעתיקים את המקור מתיקיית מאגר הקודים.
- נכנסים למסוף Cloud Run Functions ולוחצים על CREATE FUNCTION.
- צריך להשאיר אותו לא מאומת באפליקציית ההדגמה ולבחור בסביבת זמן הריצה של Python 3.11 בדף הבא.
- מעתיקים את הקבצים
main.pyו-requirements.txtממאגר המקור ששיתפת בשלב 1 ומדביקים את הקבצים המתאימים. - צריך להחליף את כתובת ה-URL של השרת ב-main.py בכתובת ה-URL של השרת.
- פורסים את הפונקציה ויש לכם נקודת קצה (endpoint) מסוג REST שאפשר לגשת אליה בכלי לחיזוי המחיר באפליקציית האינטרנט של חנות הצעצועים.
- נקודת הקצה אמורה להיראות כך:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- כדי לבדוק אותו ישירות במסוף Cloud Functions, צריך לעבור לכרטיסייה 'בדיקה' ולהזין את הקוד הבא כקלט הבקשה:
{
"search": "White plush toy"
}
- לוחצים על 'בדיקת הפונקציה' או מריצים ב-Cloud Shell Terminal בכל דרך שבה בוחרים להשתמש. התוצאה אמורה להופיע משמאל מתחת לכותרת Output (פלט):
12. מזל טוב
מעולה! יצרתם בהצלחה כלי חזק ומודולרי מאוד שיכול לעבוד עם מסדי נתונים, פלטפורמות ומסגרות תזמור של AI גנרטיבי כדי ליצור אפליקציה סוכן.