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

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

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

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

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

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

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

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

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

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

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

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

מתן הרשאה ל-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-pg-source:
      kind: cloud-sql-postgres
      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, נשמר בספרייה שבה הפעלתם את הפקודות.

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

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