יצירת הקשרים באמצעות Gemini CLI

‫MySQL   |  PostgreSQL   |  SQL Server

גרסת טרום-השקה — Data agents

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות, ושל התנאים הנוספים למוצרי AI גנרטיבי בגרסת טרום-GA. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. אתם יכולים לקרוא מידע נוסף בקטע תיאור שלבי ההשקה.

אתם יכולים לקרוא מידע נוסף על הגישה לגרסה הזו בדף בקשת הגישה.

במאמר הזה מוסבר איך להשתמש ב-Gemini CLI ובארגז הכלים של MCP כדי ליצור קובצי הקשר של הסוכן. הקבצים האלה מכילים תבניות ופנים שנותנים הקשר ליצירת שאילתות SQL משפה טבעית. תשתמשו גם בשרת DB Context Enrichment MCP.

מידע נוסף על סוכני נתונים זמין במאמר סקירה כללית על סוכני נתונים.

כדי ליצור קובץ הקשר של הסוכן, מבצעים את השלבים הבאים:

• הכנת הסביבה
• יצירת תבניות מטורגטות
• יצירת היבטים מטורגטים
• זה שינוי אופציונלי. יצירת תבניות בכמות גדולה

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

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

הפעלת שירותים נדרשים

מפעילים את השירותים הבאים בפרויקט:

• ‫Gemini Data Analytics API
• ‫Gemini for Google Cloud API

הכנת מכונה של Cloud SQL

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

תפקידים והרשאות נדרשים

• מוסיפים משתמש IAM או חשבון שירות ברמת המופע. מידע נוסף זמין במאמר בנושא הוספת קשר בין כללי מדיניות של IAM למשתמש, לחשבון שירות או לקבוצה.
• מקצים למשתמש IAM את התפקידים cloudsql.studioUser ו-cloudsql.instanceUser ברמת הפרויקט. מידע נוסף זמין במאמר הוספת קשירת מדיניות IAM לפרויקט.
• בנוסף, צריך להעניק הרשאות למסד הנתונים למשתמש IAM או לחשבון שירות. כדי לעשות זאת, צריך להתחבר למסד הנתונים כמשתמש שמבוסס על סיסמה.
  
  GRANT ALL PRIVILEGES ON * TO "IAM_USERNAME";.
  
  מידע נוסף זמין במאמר איך מעניקים הרשאות למסד נתונים למשתמש יחיד ב-IAM או לחשבון שירות.

מתן הרשאה ל-executesql למופע Cloud SQL

כדי להעניק את ההרשאה executesql למכונת Cloud SQL ולהפעיל את Cloud SQL Data API, מריצים את הפקודה הבאה:

‫

gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

מחליפים את INSTANCE_ID במזהה של מופע Cloud SQL.

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

הכנת הסביבה

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

• התקנת Gemini CLI
• התקנה והגדרה של MCP toolbox
• התקנה והגדרה של שרת MCP להעשרת הקשר של מסד הנתונים

התקנת Gemini CLI

הוראות להתקנת Gemini CLI מופיעות במאמר תחילת העבודה עם Gemini CLI. חשוב להתקין את Gemini CLI בספרייה נפרדת, שמשמשת גם להתקנת ערכת הכלים של MCP ושרת ה-MCP של DB Context Enrichment.

התקנה והגדרה של ערכת הכלים MCP

1. באותה ספרייה שבה התקנתם את Gemini CLI, מתקינים את התוסף MCP Toolbox ל-Gemini CLI:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. יוצרים קובץ תצורה tools.yaml באותה ספרייה שבה התקנתם את ערכת הכלים של MCP, כדי להגדיר את החיבור למסד הנתונים:

     sources:
       my-cloud-sql-mysql-source:
         kind: cloud-sql-mysql
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
   • ‫REGION_ID: האזור של מופע Cloud SQL, לדוגמה, us-central1.
   • ‫INSTANCE_ID: המזהה של מופע Cloud SQL.
   • ‫DATABASE_ID: השם של מסד הנתונים שאליו רוצים להתחבר.
   • ‫USER_NAME: משתמש מסד הנתונים. מידע נוסף על הגדרת הערך הזה זמין במאמר מקורות בערכת הכלים של MCP.
   • ‫PASSWORD: הסיסמה של משתמש מסד הנתונים. מידע נוסף על הגדרת הערך הזה זמין במאמר מקורות בערכת הכלים של MCP.

3. מוודאים שהקובץ tools.yaml מוגדר בצורה נכונה:

   ./toolbox --tools-file "tools.yaml"

התקנת שרת ה-MCP של DB Context Enrichment

שרת ה-MCP של DB Context Enrichment מספק תהליך עבודה מודרך ואינטראקטיבי ליצירת תבניות מובנות של NL2SQL מסכימות מסד הנתונים שלכם. היא מסתמכת על התוסף MCP Toolbox לקישוריות למסד נתונים. מידע נוסף על התקנת שרת ה-MCP של DB Context Enrichment זמין במאמר DB Context Enrichment MCP Server.

כדי להתקין את שרת ה-MCP של DB Context Enrichment:

1. באותה ספרייה שבה התקנתם את Gemini CLI, מתקינים את כלי ההתקנה של חבילת Python‏ uv באמצעות pip.

   pip install uv

   אם pip לא מותקן, צריך להתקין אותו קודם.

2. מטמיעים את שרת ה-MCP של DB Context Enrichment.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

השרת משתמש ב-Gemini API ליצירה. חשוב לוודא שמייצאים את מפתח ה-API כמשתנה סביבה. מידע נוסף על איתור מפתח API זמין במאמר שימוש במפתחות API של Gemini.

מייצאים את מפתח Gemini API:

export GEMINI_API_KEY="YOUR_API_KEY"

מחליפים את הערך YOUR_API_KEY במפתח Gemini API.

יצירת תבניות מטורגטות

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

כדי להוסיף תבנית שאילתה להקשר של הסוכן:

1. באותה ספרייה שבה התקנתם את Gemini CLI, מפעילים את Gemini:

   gemini

2. משלימים את הגדרת האימות של Gemini CLI.

3. מוודאים שערכת הכלים של MCP והתוסף להעשרת מסד הנתונים מוכנים לשימוש:

   /mcp list

4. מריצים את הפקודה /generate_targeted_templates:

   /generate_targeted_templates

5. מזינים את השאילתה בשפה טבעית שרוצים להוסיף לתבנית השאילתה.

6. מזינים את שאילתת ה-SQL המתאימה לתבנית השאילתה.

7. בודקים את תבנית השאילתה שנוצרה. אפשר לשמור את תבנית השאילתה כקובץ הקשר של הסוכן או לצרף אותה לקובץ הקשר הקיים.

קובץ ההקשר של הסוכן, בדומה ל-my-cluster-psc-primary_postgres_templates_20251104111122.json, נשמר בספרייה שבה הפעלתם את הפקודות.

מידע נוסף על קובץ ההקשר ותבנית השאילתה זמין במאמר הקשר של הסוכן.

יצירת היבטים מטורגטים

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

כדי להוסיף היבט להקשר של הסוכן:

1. מריצים את הפקודה /generate_targeted_facets:

   /generate_targeted_facets

2. מזינים את השאילתה בשפה טבעית שרוצים להוסיף לתבנית השאילתה.

3. מזינים את שאילתת ה-SQL המתאימה לתבנית השאילתה.

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

קובץ ההקשר של הסוכן, בדומה ל-my-cluster-psc-primary_postgres_templates_20251104111122.json, נשמר בספרייה שבה הפעלתם את הפקודות.

מידע נוסף על קובץ ההקשר וההיבטים זמין במאמר הקשר של הסוכן.

אופציונלי: יצירת תבניות בכמות גדולה

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

כדי ליצור אוטומטית תבניות בכמות גדולה:

1. מריצים את הפקודה /generate_bulk_templates:

   /generate_bulk_templates

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

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

4. מזינים את השאילתה בשפה טבעית שרוצים להוסיף לתבנית השאילתה.

5. מזינים את שאילתת ה-SQL המתאימה לתבנית השאילתה.

6. בודקים את תבנית השאילתה שנוצרה. אפשר לשמור את תבנית השאילתה כקובץ הקשר של הסוכן או לצרף אותה לקובץ הקשר הקיים.

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

קובץ ההקשר של הסוכן, בדומה ל-my-cluster-psc-primary_postgres_templates_20251104111122.json, נשמר בספרייה שבה הפעלתם את הפקודות.

מידע נוסף על קובץ ההקשר של הסוכן זמין במאמר הקשר של הסוכן.

המאמרים הבאים

• מידע נוסף על סוכני נתונים
• איך יוצרים או מוחקים סוכן נתונים ב-Cloud SQL Studio
• איך בודקים את סוכן הנתונים ויוצרים איתו קשר