‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

‫Google Cloud MCP ל-AlloyDB לסוכני AI

1. מבוא

ב-Codelab הזה נסביר איך להתחיל להשתמש בשרת Google Cloud MCP ל-AlloyDB, להפעיל אותו כחלק מערכת הכלים של סוכן AI ולהשתמש בו כחלק מהאפליקציה.

דרישות מוקדמות

הבנה בסיסית של Google Cloud ושל המסוף
מיומנויות בסיסיות בממשק שורת הפקודה וב-Cloud Shell

מה תלמדו

איך יוצרים אשכול AlloyDB ומייבאים נתונים לדוגמה
איך מפעילים את AlloyDB Data access API
איך מפעילים את Google Cloud MCP ל-AlloyDB NL
איך מוסיפים את Google Cloud MCP ל-AlloyDB לסוכן ADK
איך משתמשים ב-Google Cloud MCP ל-AlloyDB באפליקציה
איך משתמשים בסוכנים עם AlloyDB MCP לניתוח

מה תצטרכו

חשבון Google Cloud ופרויקט Google Cloud
דפדפן אינטרנט כמו Chrome שתומך במסוף Google Cloud וב-Cloud Shell

2. הגדרה ודרישות

הגדרת פרויקט

נכנסים ל-Google Cloud Console. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

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

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

בחלון Select a project (בחירת פרויקט), לוחצים על הלחצן New Project (פרויקט חדש) כדי לפתוח תיבת דו-שיח לפרויקט החדש.

בתיבת הדו-שיח, מזינים את שם הפרויקט המועדף ובוחרים את המיקום.

שם הפרויקט הוא השם המוצג למשתתפים בפרויקט. שם הפרויקט לא משמש את Google APIs, ואפשר לשנות אותו בכל שלב.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו אחרי שהוא מוגדר. מסוף Google Cloud יוצר באופן אוטומטי מזהה ייחודי, אבל אפשר להתאים אותו אישית. אם לא אהבתם את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר או לספק מזהה משלכם כדי לבדוק אם הוא זמין. ברוב ה-codelabs, תצטרכו להתייחס למזהה הפרויקט שלכם, שבדרך כלל מזוהה באמצעות placeholder בשם PROJECT_ID.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. מידע נוסף על שלושת הערכים האלה מופיע במאמרי העזרה.

הפעלת החיוב

הגדרה של חשבון לחיוב לשימוש אישי

אם הגדרתם חיוב באמצעות קרדיטים ב-Google Cloud, אתם יכולים לדלג על השלב הזה.

כדי להגדיר חשבון לחיוב לשימוש אישי, עוברים לכאן כדי להפעיל את החיוב ב-Cloud Console.

הערות:

העלות של השלמת ה-Lab הזה במשאבי Cloud צריכה להיות פחות מ-3 דולר ארה"ב.
כדי למנוע חיובים נוספים, אפשר למחוק את המשאבים לפי השלבים שמפורטים בסוף ה-Lab הזה.
משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$.

מפעילים את Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-Codelab הזה נשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-מסוף Google Cloud, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הפעלת Cloud Shell

אפשר גם ללחוץ על G ואז על S. אם אתם במסוף Google Cloud, או אם אתם משתמשים בקישור הזה, הרצף הזה יפעיל את Cloud Shell.

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

צילום מסך של טרמינל Google Cloud Shell שבו מוצג שהסביבה מחוברת

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

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

הפעלת ה-API

כדי להשתמש ב-AlloyDB, ב-Compute Engine, ב-Networking services וב-Vertex AI, צריך להפעיל את ממשקי ה-API שלהם בפרויקט Google Cloud.

במסוף Cloud Shell, מוודאים שמזהה הפרויקט מוגדר:

gcloud config get-value project

הפקודה אמורה להחזיר את מזהה הפרויקט ב-Google.

מגדירים את משתנה הסביבה PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

מפעילים את כל השירותים הנדרשים:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com

הפלט הצפוי

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. פריסת AlloyDB

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

פריסת AlloyDB באמצעות סקריפט אוטומטי

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

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

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

מריצים את סקריפט הפריסה.

./deploy_alloydb.sh

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

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------

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

5. הכנת מסד הנתונים

כדי להשתמש בפונקציות ובאופרטורים של AI, צריך להפעיל את השילוב של Vertex AI, להפעיל את Data access API וליצור מסד נתונים למערך נתונים לדוגמה.

מתן ההרשאות הנדרשות ל-AlloyDB

מוסיפים הרשאות Vertex AI לסוכן השירות של AlloyDB.

פותחים כרטיסייה נוספת ב-Cloud Shell באמצעות הסימן '+' בחלק העליון.

בכרטיסייה החדשה של 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"

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/discoveryengine.viewer"

הפלט הצפוי בקונסולה:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ 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"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
... < redacted > 
etag: BwYIEbe_Z3U=
version: 1

הפעלת Data Access API

כדי להשתמש בכלי MCP כמו execute_sql, צריך להפעיל את Data Access API באשכול AlloyDB.

מריצים באותה כרטיסייה במסוף.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

Update Instance Flags

כדי להשתמש בפונקציות מתקדמות של AI ב-AlloyDB, צריך להפעיל כמה דגלים של מסד הנתונים. אחרי שמפעילים את Data Access API, יכול להיות שיחלפו כמה דקות עד שהמופע יהיה מוכן לשינויים הבאים. כדי לוודא שהמכונה מסומנת בסימן וי ירוק, צריך לבדוק את הסטטוס שלה במסוף.

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

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

התחברות ל-AlloyDB Studio

בפרקים הבאים אפשר להריץ את כל פקודות ה-SQL שדורשות חיבור למסד הנתונים ב-AlloyDB Studio.

עוברים אל הדף Clusters ב-AlloyDB ל-Postgres.

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

אחר כך לוחצים על AlloyDB Studio בצד ימין:

בוחרים את מסד הנתונים של postgres, את המשתמש postgres ומזינים את הסיסמה שרשמתם כשיצרתם את האשכול. לאחר מכן לוחצים על הלחצן 'אימות'.

אם הסיסמה לא עובדת או ששכחתם לרשום אותה, אתם יכולים לשנות אותה. בתיעוד מוסבר איך עושים את זה.

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

הממשק ייפתח ותוכלו להריץ בו פקודות SQL

יצירת מסד נתונים

יצירת מסד נתונים – מדריך למתחילים

בעורך של AlloyDB Studio, מריצים את הפקודה הבאה.

יצירת מסד נתונים:

CREATE DATABASE quickstart_db

הפלט אמור להיראות כך:

Statement executed successfully

התחברות ל-quickstart_db

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

בוחרים מהרשימה הנפתחת את מסד הנתונים החדש quickstart_db ומשתמשים באותו משתמש ובאותה סיסמה כמו קודם.

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

6. נתונים לדוגמה

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

יצירת קטגוריית אחסון

תשתמשו ב-Google SDK‏ (gcloud) כדי לייבא נתונים מהמאגר המשוכפל שלנו למסד הנתונים של AlloyDB, ותצטרכו ליצור קטגוריית אחסון בשביל זה ולתת גישה לחשבון השירות של AlloyDB. אפשרות נוספת היא לנסות לעשות זאת באמצעות מסוף האינטרנט, כפי שמתואר במסמכי התיעוד.

בטרמינל של Google Cloud Shell, מריצים את הפקודה:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

טעינת נתונים

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

מעתיקים את קובץ ה-SQL הדחוס לקטגוריית האחסון החדשה:

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

לאחר מכן טוענים את הנתונים למסד הנתונים quickstart_db:

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

הפקודה תטען את מערך הנתונים לדוגמה למסד הנתונים quickstart_db. אפשר לאמת את הטבלאות והרשומות באמצעות AlloyDB Studio.

7. עבודה עם סוכן הנתונים

נתחיל מסוכן AI לדוגמה שנוצר באמצעות Google ADK ל-Python, ונדגים איך להגדיר אותו כך שיפעל עם שרת Google Cloud MCP ל-AlloyDB.

בדיקת קוד המקור של הסוכן

מאמתים את קוד הסוכן במאגר המשוכפל באמצעות עורך Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py

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

# Google Cloud MCP Server for AlloyDB

MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
    "Authorization": f"Bearer {creds.token}",
    "X-Goog-User-Project": project_id
}
    
connection_params = StreamableHTTPConnectionParams(
    url=MCP_SERVER_URL,
    headers=headers,
    timeout=300.0,
    sse_read_timeout=600.0
)

mcp_toolset = McpToolset(connection_params=connection_params)

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

MODEL_ID = "gemini-3.5-flash"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3.5-flash with the functions from the schema.
    """,
    tools=[mcp_toolset],
)

לשירות Google Cloud MCP ל-AlloyDB יש קבוצה מוגדרת מראש של כלים. כדי לראות רשימה של כל הכלים הזמינים, אפשר להשתמש בפקודה curl ממסוף Cloud Shell באמצעות הפקודה הבאה. תמיד אפשר לבדוק את ההפניה האחרונה לשרת Google Cloud MCP ל-AlloyDB במסמכי העזרה.

curl -s -X POST http://alloydb.googleapis.com/mcp \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.result.tools[].name'
{
  "id": "my_id_01",
  "jsonrpc": "2.0",
  "method": "tools/list"
}
EOF

הפעלת הסוכן

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

קודם נתקין את כל החבילות הנדרשות ל-Python באמצעות מנהל החבילות uv.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync

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

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

אחר כך אפשר להפעיל את הסוכן

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

אמור להופיע פלט כמו זה שבהמשך, עם נקודת הקצה כמו http://127.0.0.1:8000 .

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

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

8. בדיקת AlloyDB MCP עם סוכן

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

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

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

Hello, can you tell me how many trips we've done in February this year?

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

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

לפי הרשומות במסד הנתונים שלנו, הושלמו 108 נסיעות בפברואר 2026.

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

עכשיו נבקש השוואה בין התוצאות לבין החודש הקודם.

How is it in comparison in numbers and mileage with the January?

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

In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage:

January 2026: 114 trips with a total mileage of 185,597 km.
February 2026: 108 trips with a total mileage of 177,893 km.
This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.

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

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

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

9. אפליקציה לדוגמה

באותו מאגר משוכפל יש לנו אפליקציה לדוגמה לחברת הלוגיסטיקה Cymbol. האפליקציה משתמשת ב-framework של Python‏ Mesop של Google .

כדי לנתח את קוד האפליקציה, פותחים את הקובץ app.py בעורך של Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py

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

def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
    local_runner = FrontendRunner()
    
    instruction = f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3.5-flash with the functions from the schema.
    """
    ...

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

מריצים את הפקודה ב-Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080

אחר כך משתמשים בתצוגה מקדימה באינטרנט ב-Google Cloud Shell על ידי לחיצה על http://localhost:8080

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

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

What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.

ואז לוחצים על הלחצן Submit Request.

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

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

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

10. פונקציות AI ב-AlloyDB

הפונקציות של AlloyDB AI מאפשרות סינון ודירוג חכמים של נתונים מולטי-מודאליים (בעיקר תמונות) וטקסט, ומביאות את העוצמה של Gemini לשאילתות שלכם. בפרט, הפונקציות AI.IF ו-AI.RANK של AlloyDB AI יכולות להופיע בהצהרות SQL לצד אופרטורים רגילים של SQL (מסננים, צירופים, צבירה וכו').

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

Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.

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

SELECT 
    d.first_name || ' ' || d.last_name as driver_name,
    SUM(sr.distance_km) as total_distance,
    d.experience_years,
    COUNT(cf.feedback_id) as positive_feedback_count

FROM drivers d

JOIN truck_trips tt ON d.driver_id = tt.driver_id

JOIN customer_feedback cf ON tt.trip_id = cf.trip_id

JOIN shipping_requests sr ON tt.request_id = sr.request_id

WHERE tt.arrival_time >= '2025-12-01' 
AND tt.arrival_time < '2026-05-01'
  
AND cf.rating >= 4

GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years

ORDER BY positive_feedback_count DESC, total_distance DESC

LIMIT 5;

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

אופרטורים של AI.RANK

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

לשנות את הבקשה ולבקש במפורש להשתמש ב-AI.RANK במהלך הניתוח כדי להעריך את הגורמים המניעים על סמך הביצועים והמקצועיות שלהם.

Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function?  Give me top drivers  names, distance, years of experience and rank for each driver.

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

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

WITH fastest_drivers AS (
    SELECT 
        d.driver_id,
        d.first_name || ' ' || d.last_name as driver_name,
        d.experience_years,
        SUM(sr.distance_km) as total_distance,
        AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
        COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
        ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
    
FROM drivers d
    
JOIN truck_trips tt ON d.driver_id = tt.driver_id
    
JOIN shipping_requests sr ON tt.request_id = sr.request_id
    LEFT 
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
    
WHERE tt.arrival_time >= '2026-04-04'
      
AND tt.arrival_time IS NOT NULL 
      
AND tt.departure_time IS NOT NULL
      
AND tt.arrival_time > tt.departure_time
    
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
    
ORDER BY avg_speed DESC
    
LIMIT 5
)
SELECT 
    f.driver_name,
    f.total_distance,
    f.experience_years,
    f.avg_speed,
    f.feedbacks,
    (SELECT r.score 
FROM ai.rank(
        'semantic-ranker-fast-004',
        'excellent customer service, professional, friendly, fast, 
and reliable delivery reviews',
        ARRAY[f.feedbacks],
        1
    ) r 
LIMIT 1) as feedback_score

FROM fastest_drivers f

ORDER BY feedback_score DESC;

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

עד כאן שיעור ה-Lab. מקווה שהצלחת לעבור על כל הדוגמאות וללמוד איך להשתמש בשירות Google Cloud MCP ל-AlloyDB. כדי להשתמש ב-MCP בארגון, מומלץ לשלב אותו עם התכונות של AlloyDB NL2SQL שמתוארות במאמרי העזרה של AlloyDB. אפשר לנסות את התכונה באמצעות ה-codelab בנושא יצירת הצהרות SQL ל-AlloyDB.

11. ניקוי הסביבה

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

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

מחיקת אשכול AlloyDB וכל המכונות

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

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

ב-Cloud Shell, מגדירים את משתני הפרויקט והסביבה אם התנתקתם וכל ההגדרות הקודמות אבדו:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

מחיקת האשכול:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

הפלט הצפוי בקונסולה:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

מחיקת גיבויים של AlloyDB

מחיקת כל הגיבויים של AlloyDB באשכול:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

הפלט הצפוי בקונסולה:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

12. מזל טוב

כל הכבוד, סיימתם את ה-Codelab.

מה נכלל

איך יוצרים אשכול AlloyDB ומייבאים נתונים לדוגמה
איך מפעילים את ממשק ה-API לגישה לנתונים ב-AlloyDB
איך מפעילים את Google Cloud MCP ל-AlloyDB NL
איך מוסיפים את Google Cloud MCP ל-AlloyDB לסוכן ADK
איך משתמשים ב-Google Cloud MCP ל-AlloyDB באפליקציה
איך משתמשים בסוכנים עם AlloyDB MCP לניתוח

סקר

פלט:

איך תשתמשו במדריך הזה?

רק קוראים את הטקסט

קוראים את הטקסט ומבצעים את התרגילים