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

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

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

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

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

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

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

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

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

הכנת מכונת Spanner

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

הכנת הסביבה

אפשר ליצור קובצי הקשר של הסוכן מכל סביבת פיתוח מקומית או 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-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫INSTANCE_ID: המזהה של מכונת Spanner.
    • ‫DATABASE_ID: השם של מסד הנתונים שאליו רוצים להתחבר.

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

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

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