שילוב של QueryData עם אפליקציה

במדריך הזה מוסבר איך להגדיר את QueryData ב-Spanner באמצעות מסוף Google Cloud , להשתמש בו ולשלב אותו באפליקציה. איך יוצרים את קובץ קבוצות ההקשר, יוצרים קבוצת הקשר שמשתמשת בקובץ קבוצות ההקשר, משתמשים ב-MCP Toolbox כדי להפעיל את ה-method‏ QueryData ב-Conversational Analytics API כדי ליצור שאילתות SQL לשאלות בשפה טבעית, ומשלבים את זה באפליקציה.

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

מטרות

המדריך הזה עוסק ביעדים הבאים:

  • ליצור מסדי נתונים ולמלא אותם בנתונים.
  • יוצרים קובץ של קבוצת הקשר באמצעות סוכן עם מנוע תלוי הקשר.
  • יוצרים קבוצת הקשרים ומעלים קובץ של קבוצת הקשרים.
  • בודקים את QueryData ויוצרים שאילתות SQL ב-Spanner Studio.
  • משלבים את QueryData באפליקציה באמצעות הכלי Gemini Data Analytics QueryData ב-MCP Toolbox.
  • הוספת ביסוס לתשובות של מודל שפה גדול (LLM) באמצעות שאילתות חיפוש של ערכים.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

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

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

לפני שיוצרים קבוצת הקשר, צריך לבצע את הפעולות הבאות.

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

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

הכנת מכונה של Spanner

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

  • מוסיפים למכונה חשבון משתמש או חשבון שירות ב-IAM. מידע נוסף זמין במאמר החלת תפקידי IAM.
  • מקצים למשתמש ב-IAM את התפקידים roles/spanner.databaseReader,‏ roles/serviceusage.serviceUsageConsumer ו-roles/geminidataanalytics.queryDataUser ברמת הפרויקט. מידע נוסף זמין במאמר הוספת קישור למדיניות IAM בפרויקט.
  • כדי ליצור, להעלות ולנהל קבוצות של הקשרים, צריך להקצות למשתמש ה-IAM את התפקיד "עריכה של Dataplex Catalog"‏ (roles/dataplex.catalogEditor) או "אדמין של Dataplex Catalog"‏ (roles/dataplex.catalogAdmin) ברמת הפרויקט. מידע נוסף זמין במאמר הרשאות לקבוצות של הגדרות הקשר.
  • להקצות תפקידים והרשאות למשתמש ב-IAM ברמת הפרויקט למסדי הנתונים הנדרשים.

יצירת הסכימה והטבלאות של flights ו-airports

בקטע הזה יוצרים את טבלאות מסד הנתונים flights ו-airports בשביל המדריך.

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.

  3. בתפריט הניווט, לוחצים על Spanner Studio.

  4. לוחצים על New SQL editor tab או על New tab כדי לפתוח כרטיסייה חדשה.

  5. כדי ליצור את הטבלה והסכימה של airports, מריצים את הצהרת ה-SQL הבאה:

    CREATE TABLE IF NOT EXISTS airports (
      id INT64 PRIMARY KEY,
      iata STRING(MAX),
      name STRING(MAX),
      city STRING(MAX),
      country STRING(MAX)
    );
    
  6. יוצרים את הטבלה והסכימה של flights:

    CREATE TABLE flights (
      id INT64 NOT NULL,
      airline STRING(10),
      flight_number INT64,
      departure_airport STRING(5),
      arrival_airport STRING(5),
      departure_time TIMESTAMP,
      arrival_time TIMESTAMP,
      departure_gate STRING(10),
      arrival_gate STRING(10)
    ) PRIMARY KEY (id);
    

אכלוס הטבלאות flights ו-airports

בקטע הזה תאכלסו את הטבלאות flights ו-airports באמצעות הסקריפטים של SQL שסופקו.

  1. מאכלסים את הטבלה airports.

  2. מאכלסים את הטבלה flights.

  3. מריצים את השאילתה הבאה כדי לוודא שהטבלאות מכילות נתונים:

    SELECT * FROM flights LIMIT 10;
    SELECT * FROM airports LIMIT 10;
    

יצירת עמודות עם אסימונים ואינדקסים של חיפוש

אתם יכולים להשתמש ביכולות המובנות של Spanner לחיפוש טקסט כדי לאפשר ל-QueryData למפות בצורה מדויקת ביטויים לא מובְנים בשפה טבעית, כמו שגיאות הקלדה או שמות חלקיים, לערכים ספציפיים במסד הנתונים. כדי לעשות את זה, צריך ליצור עמודת TOKENLIST מוסתרת שמפרקת את המחרוזות ל-n-grams, וליצור אינדקס חיפוש בעמודה הזו.

כדי ליצור עמודות עם אסימונים ואינדקסי חיפוש, מריצים את הצהרות ה-SQL הבאות:

  1. יוצרים את עמודת הטוקנים ואת האינדקס לשמות של שדות תעופה:

    ALTER TABLE `airports` ADD COLUMN `name_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`name`)) STORED HIDDEN;
    CREATE SEARCH INDEX `airports_name_idx` ON `airports`(`name_tokens`);
    
  2. יוצרים את עמודת הטוקן והאינדקס לערים עם שדות תעופה:

    ALTER TABLE `airports` ADD COLUMN `city_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`city`)) STORED HIDDEN;
    CREATE SEARCH INDEX `airports_city_idx` ON `airports`(`city_tokens`);
    

יצירת קבוצת הקשרים ב-Spanner Studio

בקטע הזה, יוצרים קבוצת הקשרים בשם flights-assistant. קבוצת ההקשר הזו לא כוללת קובץ של קבוצת הקשר שהועלה אליה.

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.

  3. בתפריט הניווט, לוחצים על Spanner Studio.

  4. בחלונית Explorer, לצד Context sets, לוחצים על View actions ().

  5. לוחצים על יצירת קבוצת הקשרים.

  6. בשדה Context set name, מזינים flights-assistant.

  7. לוחצים על יצירה.

בדיקת QueryData ב-Studio

בקטע הזה, תשתמשו בקבוצת ההקשר flights-assistant כדי לשאול שאלות בשפה טבעית וליצור שאילתת SQL. מכיוון שלא הועלה קובץ לקבוצת ההקשר, גם אחרי ששואלים שאלה עם הקשר כמו nighttime traffic, הכלי QueryData יוצר שאילתה לא אופטימלית.

  1. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על View actions ().
  2. לוחצים על קבוצת הקשר לבדיקה.
  3. בעורך השאילתות, לוחצים על Generate SQL using QueryData with: flights-assistant.
  4. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על Generate.

    Find flights from SFO to JFK.
    

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

      SELECT
        *
      FROM
        flights
      WHERE
        departure_airport = 'SFO'
        AND arrival_airport = 'JFK';
    
  5. בחלון Generate SQL using QueryData with: flights-assistant, לוחצים על Edit.

  6. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על Update.

    Tell me flights that can help me beat nighttime traffic if traveling from New York
    

    מסד הנתונים לא מבין את המונח "תנועה ב-nighttime". יכול להיות שהמערכת לא תיצור שאילתת SQL או תיצור שאילתה שמתעלמת מהמונח, כמו בשאילתה הבאה.

    -- The database schema does not contain information about traffic.
    -- Returning all flights departing from New York airports.
    SELECT
      f.airline,
      f.flight_number,
      a.name AS departure_airport_name,
      f.departure_time,
      b.name AS arrival_airport_name,
      f.arrival_time
    FROM
      flights AS f
    JOIN
      airports AS a
      ON f.departure_airport = a.iata
    JOIN
      airports AS b
      ON f.arrival_airport = b.iata
    WHERE
      a.city = 'New York'
    ORDER BY
      f.departure_time;
    
  7. בחלון Generate SQL using QueryData with: flights-assistant, לוחצים על Edit.

  8. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על Update.

    Show me the flight to Houston Intercontinental
    

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

    SELECT
      f.*
    FROM
      `flights` AS f
    JOIN
      `airports` AS a
    ON
      f.arrival_airport = a.id
    WHERE
      a.name LIKE '%Houston Intercontinental%';
    

יצירת הקשר לקבוצת ההקשרים

בקטע הזה מכינים את הסביבה ויוצרים קובץ הקשר שעוזר לשפר את יכולות השאילתות של קבוצת ההקשר.

מגדירים את הסביבה

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

כדי להגדיר את הסביבה, מבצעים את השלבים הבאים:

  1. מתקינים את Antigravity CLI. מידע נוסף זמין במאמר תחילת העבודה עם Antigravity CLI.
  2. מתקינים את Google Cloud CLI.
  3. הגדרת Application Default Credentials ‏(ADC). כדי לאמת ולבחור את הפרויקט, מריצים את הפקודות הבאות בטרמינל:

    gcloud auth application-default login
    gcloud auth application-default set-quota-project PROJECT_ID
  4. מתקינים את uv, מנהל פרויקטים וחבילות של Python שנדרש לסוכן הנדסת ההקשר. אם עדיין לא התקנתם את Python במערכת, uv יכול להתקין אותה בשבילכם.

  5. התקנת סוכן הנדסת ההקשר:

    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  6. בטרמינל, מפעילים את Antigravity CLI.

    agy
  7. מגדירים חיבור למסד נתונים כדי ליצור הקשר באמצעות MCP Toolbox. החיבור מוגדר בקובץ התצורה .context-engineering/tools.yaml.

    כדי ליצור את קובץ התצורה של .context-engineering/tools.yaml, מזינים הנחיה כמו:

    Help me set up a database connection.
    

    פועלים לפי ההוראות של המיומנות. מידע נוסף על הקובץ tools.yaml זמין במאמרי העזרה של MCP Toolbox.

  8. כדי לטעון מחדש את ההגדרות אחרי שיוצרים את הקובץ .context-engineering/tools.yaml, מריצים את הפקודה הבאה ב-Antigravity CLI ופועלים לפי ההוראות לטעינה מחדש של שרת ה-MCP של ארגז הכלים:

    /mcp
    1. לוחצים על db-context-engineering_toolbox.

    2. לוחצים על Restart.

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

    /mcp

יצירת הקשר לתבנית

בקטע הזה, כדי לטפל בבעיה מהקטע הקודם שבו QueryData לא זיהה את המונח nighttime traffic, מגדירים את המונח בקובץ של קבוצת ההקשר כתנועה שמתרחשת בין 5:00 PM ל-7:00 PM.

כדי ליצור הקשר לתבנית:

  1. מזינים את ההנחיה הבאה ב-Antigravity CLI:

    Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query:
    
    SELECT
      f.airline,
      f.flight_number,
      a.name AS airport_name,
      f.departure_time
    FROM
      flights f
    JOIN
      airports a
      ON f.departure_airport = a.iata
    WHERE
      a.city = 'New York'
      AND (
        EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19
      )
    ORDER BY
      f.departure_time;
    
  2. הנציג ממיר את הקלט שלכם לפורמט ספציפי שמשפר את הביצועים של קבוצת ההקשר במגוון רחב של שאילתות משתמשים. מידע נוסף זמין במאמר סקירה כללית בנושא קבוצות הקשר.

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

  4. מבקשים מהסוכן לשמור את התבנית:

    Save it to context_set.json.
    

    ה-agent יוצר את הקובץ באותה ספרייה, עם התוכן הבא:

    {
      "templates": [
        {
          "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
          "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;",
          "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
          "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
          "parameterized": {
            "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;",
            "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
          }
        }
      ]
    }
    

יצירת הקשר לחיפוש ערך

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

כדי ליצור הקשר לחיפוש ערכים, פועלים לפי השלבים הבאים:

  1. מזינים את ההנחיה הבאה במעטפת האג'נטית:

    Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "TRIGRAM_STRING_MATCH".
  2. בודקים את הגדרת החיפוש של הערך שנוצר. אתם יכולים לשמור את הגדרת החיפוש של הערך כקובץ חדש של קבוצת הקשרים, או להוסיף אותה לקובץ קיים של קבוצת הקשרים.

  3. נותנים לסוכן את ההנחיה Append the context to context_set.json. הפעולה הזו מוסיפה את הגדרת החיפוש של הערך לקובץ ההקשר שנוצר בקטע הקודם.

  4. מזינים את המכונה של מסד הנתונים ואת שם מסד הנתונים שעבורו נוצר קובץ קבוצת ההקשר.

    קובץ ההקשר הקיים מתעדכן בהגדרת החיפוש של הערך, עם התוכן הבא:

      {
    "templates": [
      {
        "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;",
        "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
        "parameterized": {
          "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;",
          "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
        }
      }
    ],
    "facets": [],
    "value_searches": [
      {
        "query": "SELECT CAST(T.`name` AS STRING) AS value, 'name' AS `columns`, 'airport name' AS concept_type, 1 - SCORE_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) ",
        "concept_type": "airport name",
        "description": "String similarity using Spanner Search Indexes."
      },
      {
        "query": "SELECT CAST(T.`city` AS STRING) AS value, 'city' AS `columns`, 'airport city' AS concept_type, 1 - SCORE_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) ",
        "concept_type": "airport city",
        "description": "String similarity using Spanner Search Indexes."
      }
    ]
    }
    

העלאת קובץ קבוצת ההקשר ל-QueryData

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

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

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.

  3. בתפריט הניווט, לוחצים על Spanner Studio.

  4. בחלונית Explorer, בקטע Context sets, לוחצים על הסמל View actions () ליד קבוצת ההקשר flights-assistant.

  5. לוחצים על עריכת קבוצת ההקשר.

  6. בקטע Upload context file, לוחצים על Browse ובוחרים את קובץ קבוצת ההקשרים שנוצר קודם.

  7. לוחצים על Save.

יצירת שאילתת SQL באמצעות QueryData

בקטע הזה, תשתמשו בקובץ של קבוצת ההקשר שהעליתם כדי לשאול שאלות בשפה טבעית. כך אתם יכולים לוודא ש-QueryData מבין ומיישם בצורה נכונה הגדרות של מונחים כמו nighttime traffic וביטויים קשורים אחרים.

כדי ליצור שאילתות SQL:

  1. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על View actions ().
  2. לוחצים על קבוצת הקשר לבדיקה.
  3. בעורך השאילתות, לוחצים על Generate SQL using QueryData with: flights-assistant.
  4. כדי ליצור שאילתת SQL, מזינים את השאלה הבאה בשפה טבעית ולוחצים על Generate.

    Tell me flights that can help me beat nighttime traffic if traveling from New York
    

    שאילתת ה-SQL שנוצרת נראית בערך כך:

    SELECT
      f.airline,
      f.flight_number,
      a.name AS airport_name,
      f.departure_time
    FROM
      flights f
    JOIN
      airports a ON f.departure_airport = a.iata
    WHERE
      a.city = 'New York'
      AND (
        EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19
      )
    ORDER BY
      f.departure_time;
    

    זו אותה שאלה שהוספתם להקשר של QueryData. עכשיו QueryData יכול לפרש בצורה מדויקת את המונח nighttime traffic.

    למרות שההקשר מגיע משאלה ספציפית, QueryData משתמש בו כדי לשפר את יצירת ה-SQL למגוון רחב של שאלות דומות.

  5. בחלון Generate SQL using QueryData with: flights-assistant, לוחצים על Edit.

  6. כדי ליצור שאילתת SQL, מזינים את השאלה הבאה ולוחצים על Update.

    What are the flights that can help me avoid evening traffic if departing from Boston
    

    מכיוון שהשאלה מחליפה את המונח nighttime traffic במונח דומה, evening traffic, QueryData מספק תשובה עקבית לשאלה הזו על ידי החלת אותו פירוש.

    שאילתת ה-SQL שנוצרת נראית בערך כך:

    -- What are the flights that can help me avoid evening traffic if departing from Boston
    SELECT
      f.airline,
      f.flight_number,
      a.name AS airport_name,
      f.departure_time
    FROM
      flights f
    JOIN
      airports a
    ON
      f.departure_airport = a.iata
    WHERE
      a.city = 'Boston'
      AND (
        EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19
      )
    ORDER BY
      f.departure_time;
    
  7. כדי ליצור שאילתת SQL, מזינים את השאלה הבאה ולוחצים על Update.

    Show me the flight to Houston Intercontinental
    

    שאילתת ה-SQL שנוצרת נראית בערך כך:

    SELECT
      f.*
    FROM
      flights AS f
    INNER JOIN
      airports AS a
    ON
      f.arrival_airport = a.iata
    WHERE
      a.name = 'George Bush Intercontinental Houston Airport'
    

    שימו לב ש-QueryData יכול עכשיו לפרש בצורה מדויקת ש-"Houston Intercontinental" קשור ל-"George Bush Intercontinental Houston Airport" במסד הנתונים.

שילוב של QueryData באפליקציה

בקטע הזה תיצרו סוכן לאינטראקציה עם נתונים בשביל אפליקציה לחיפוש טיסות. סוכן לאינטראקציה עם נתונים זה מספק ממשק שיחה לטבלאות flights ו-airports שיצרתם קודם. בנוסף, מוסבר איך ליצור ולשלב את הסוכן לאינטראקציה עם נתונים באפליקציה באמצעות הערכה לפיתוח סוכנים (ADK), הכלי QueryData MCP של Gemini Data Analytics וקבוצת הקשר לשיפור איכות התשובות.

  1. מורידים את MCP Toolbox בגרסה 1.14.0 ואילך. ‫MCP Toolbox חושף את הסוכן לאינטראקציה עם נתונים ככלי שאפליקציות יכולות להתחבר אליו. ארגז הכלים של MCP שונה מסוכן הנדסת ההקשר שהתקנתם קודם, שיוצר הקשר.

  2. מגדירים את Application Default Credentials (ADC).

    gcloud auth application-default login
    gcloud auth application-default set-quota-project PROJECT_ID
  3. מוצאים את המזהה של קבוצת ההקשר שיצרתם קודם. איך מוצאים את מזהה קבוצת ההקשר

  4. כדי להתחבר לסוכן הנתונים באמצעות MCP Toolbox, מוסיפים את הטקסט הבא להגדרות של .context-engineering/tools.yaml (או tools.yaml בספריית העבודה). מידע נוסף זמין במאמרים מקור הנתונים של Gemini Data Analytics והכלי QueryData של Gemini Data Analytics.

    ---
    kind: source
    name: gda-api-source
    type: cloud-gemini-data-analytics
    projectId: "PROJECT_ID"
    ---
    kind: tool
    name: cloud_gda_query_tool
    type: cloud-gemini-data-analytics-query
    source: gda-api-source
    description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
    location: "REGION_ID"
    context:
      datasourceReferences:
        spannerReference:
          databaseReference:
            engine: "GOOGLE_SQL"
            projectId: "PROJECT_ID"
            instanceId: "INSTANCE_ID"
            databaseId: "DATABASE_ID"
          agentContextReference:
            contextSetId: "CONTEXT_SET_ID"
    generationOptions:
      generateQueryResult: true
      generateNaturalLanguageAnswer: true
      generateExplanation: true
      generateDisambiguationQuestion: true
    

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫REGION_ID: האזור של מכונת Spanner (לדוגמה, us-central1).
    • ‫INSTANCE_ID: המזהה של מכונת Spanner.
    • ‫DATABASE_ID: השם של מסד הנתונים שאליו רוצים להתחבר.
    • ‫CONTEXT_SET_ID: המזהה של קבוצת ההקשרים. איך מוצאים את מזהה קבוצת ההקשר
  5. מפעילים את שרת MCP Toolbox עם הקובץ tools.yaml.

    ./toolbox --config PATH_TO_TOOLS_YAML

    מחליפים את PATH_TO_TOOLS_YAML בנתיב לקובץ tools.yaml שיצרתם קודם (לדוגמה, .context-engineering/tools.yaml או tools.yaml).

  6. יוצרים אפליקציית ADK שמפעילה את הכלי QueryData של Gemini Data Analytics באמצעות Python SDK של MCP Toolbox. למידע נוסף על השימוש ב-Python SDK של MCP Toolbox, עיינו במדריך למתחילים של Toolbox, ולמידע על Python ADK, עיינו במדריך למתחילים של ADK.

    1. יוצרים ספרייה לאחסון האפליקציה, לדוגמה flight-assistant-app.
    2. עוברים לספרייה flight-assistant-app.

      mkdir flight-assistant-app
      cd flight-assistant-app
    3. מריצים את הפקודות הבאות בספרייה flight-assistant-app כדי ליצור סביבה וירטואלית ולהתקין את הרכיבים הנדרשים.

      uv init
      uv add google-adk toolbox-core google-genai
    4. מגדירים סוכן ADK.

      1. יוצרים סוכן ADK.

        uv run adk create my_agent
      2. בוחרים את הדגם gemini-2.5-flash או דגם חדש יותר.

      3. בוחרים באפשרות Google AI ומזינים את מפתח ה-API של Gemini. איך מוצאים את מפתח ה-API של Gemini? (לחלופין, אם אתם לא צריכים תקופת ניסיון בחינם, אתם יכולים לבחור באפשרות Vertex AI, לציין פרויקט Google Cloud עם חיוב מופעל ולהזין global כשתתבקשו להזין את האזור Google Cloud (Enter Google Cloud region) כדי ש-GOOGLE_CLOUD_LOCATION=global יוגדר ב-my_agent/.env).

    5. מחליפים את התוכן של הקובץ agent.py בקוד האפליקציה לדוגמה Flight Data Assistant.

      from typing import cast
      
      from google.adk.agents.llm_agent import Agent
      from google.adk.agents.llm_agent import ToolUnion
      
      from toolbox_core import ToolboxSyncClient
      
      TOOLBOX_URL = "http://127.0.0.1:5000"
      
      INSTRUCTION = """
      # ROLE
      You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
      - use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.
      
      # OPERATIONAL CONSTRAINTS
      - TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
      - TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
      - SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.
      
      # COMMUNICATION STYLE
      - Be concise and scannable when listing answers.
      - Maintain a helpful, professional persona.
      
      =====
      
      # QUERY DATA TOOL
      
      Inputs:
      1. query: A natural language formulation of a database query.
      
      Outputs: (all optional)
      1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
      2. generated_query: The generated query for the user query.
      3. intent_explanation: An explanation for why the tool produced `generated_query`.
      4. query_result: The result of executing `generated_query`.
      5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.
      
      Usage guidance:
      1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
      2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
      3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
      """
      
      client = ToolboxSyncClient(TOOLBOX_URL)
      
      mcp_tool = client.load_tool("cloud_gda_query_tool")
      
      root_agent = Agent(
          model="gemini-2.5-flash",  # Or newer.
          name="root_agent",
          instruction=INSTRUCTION,
          tools=cast(list[ToolUnion], [mcp_tool]),
      )
      
  7. כדי להפעיל את האפליקציה, מריצים את הפקודות הבאות בספרייה flight-assistant-app. נכנסים לשרת האינטרנט של ADK בכתובת http://127.0.0.1:8000.

    uv run adk web --port 8000
  8. כדי להתחיל אינטראקציה עם הסוכן, מזינים טקסט כלשהו, למשל hello.

    הסוכן של ADK עונה על שאלות כלליות וקורא לכלי ה-MCP הנדרשים.

  9. מזינים את השאלה הבאה שקשורה לטיסה.

    How many flights depart from the west side?
    

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

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:
    
    1. How many flights depart from a specific airport?
    
    2. What are the departure airports for all flights?
    
    3. How many flights depart from each airport? Would you like to rephrase your question based on these options?
    
  10. מזינים שאלה שדומה לשאלה בתבנית השאילתה שנוצרה בשביל הסוכן.

    Help me find flights from San Francisco that avoid the evening rush hour.
    

    על סמך ההקשר של QueryData שנוסף קודם, כלי ה-MCP מבין שevening traffic מתרחש בין 17:00 ל-19:00. כלי ה-MCP מחזיר את הנתונים המשויכים, והסוכן משתמש בהם כדי ליצור את התשובה שלו.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):
    
    * UA 1532 departing at 05:50:00
    * UA 1158 departing at 05:57:00
    * CY 922 departing at 06:38:00
    * OO 5441 departing at 07:08:00
    * UA 616 departing at 07:14:00
    * AA 24 departing at 07:14:00
    * B6 434 departing at 08:00:00
    * AA 242 departing at 08:18:00
    * UA 1739 departing at 08:22:00
    * OO 6336 departing at 08:32:00
    * US 1784 departing at 08:47:00
    * DL 1631 departing at 09:00:00
    * DL 1106 departing at 09:06:00
    * OO 5427 departing at 09:06:00
    * CY 352 departing at 09:25:00
    
  11. מזינים שאלה על סמך סוג המושג שהוספתם בהקשר של סוכן QueryData.

    Show me the flight to Houston Intercontinental
    

    על סמך הקשר החיפוש של הערך שנוסף קודם, הסוכן מבין שהמונח "Houston Intercontinental" קשור ל-"George Bush Intercontinental Houston Airport" (קוד שדה התעופה IAH) ומחזיר את הנתונים המשויכים כדי שהסוכן יוכל להשתמש בהם ליצירת התשובה.

    Here are the flights heading to Houston Intercontinental (IAH):
    
    * Flight UA 1285 departs from SFO and arrives at IAH on 2025-01-01 at 15:20:00Z.
    * Flight F9 1056 departs from SFO and arrives at IAH on 2025-01-02 at 12:09:00Z.
    * Flight UA 1722 departs from SFO and arrives at IAH on 2025-01-02 at 18:29:00Z.
    * Flight UA 1705 departs from SFO and arrives at IAH on 2025-01-02 at 18:50:00Z.
    * Flight UA 1762 departs from SFO and arrives at IAH on 2025-01-02 at 23:11:00Z.
    

שיפור ביצועי הסוכן

ממשק המשתמש של ADK מאפשר לבדוק את הבקשה והתגובה מהכלי QueryData MCP של Gemini Data Analytics. אתם יכולים להשתמש בתשובה הזו כדי לבחון את התשובות של הכלי, כמו שאילתת SQL שנוצרה, קבוצת תוצאות, הסבר על הכוונה, שאלה להפגת עמימות ותשובה בשפה טבעית, כדי לוודא שהתשובות של הנציג נכונות.

לדוגמה, לוחצים על בועת הסוכן של טקסט הקלט How many flights depart from the west side? שהזנתם קודם. בכרטיסייה Event שבחלונית הניווט הימנית, מרחיבים את functionResponse כדי לראות את התגובה הבאה.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

שיפור הדיוק של התשובות

אתם יכולים להוסיף הקשר כדי לשפר את הדיוק של התשובות שאתם מקבלים מהכלי QueryData של Gemini Data Analytics. משתמשים בסוכן עם מנוע תלוי הקשר כדי ליצור הקשר, ואז מעלים את קובץ קבוצת ההקשר המעודכן לסוכן לאינטראקציה עם נתונים הקיים של flights-assistant. מידע נוסף זמין במאמר ניהול קבוצות הקשר ב-Spanner Studio. המסוף מטמיע מיד את ההקשר החדש אחרי שמעלים אותו, וכך משפר את הדיוק של הנציג בלי להשבית את האפליקציה.

כמה נציגים

בסביבת הפיתוח, אתם יכולים לבצע בדיקות A/B בכמה הקשרים של סוכנים לאינטראקציה עם נתונים על ידי הקצאת שמות נפרדים לכלים בקובץ tools.yaml. לדוגמה, אתם יכולים ליצור הגדרות ייחודיות של tools.yaml על ידי הגדרת שני כלים של cloud-gemini-data-analytics-query עם שמות שונים, כמו cloud_gda_query_tool_v1 ו-cloud_gda_query_tool_v2. ההגדרה הזו מאפשרת לכם להטמיע לוגיקה של אפליקציה שבוחרת באופן פרוגרמטי את גרסת ההקשר הנדרשת על ידי בחירת שם הכלי המתאים.

בדוגמה הבאה של tools.yaml מוסבר איך להגדיר כמה סוכנים לאינטראקציה עם נתונים למקור של מסד נתונים:

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: PROJECT_ID
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    DB_SOURCE:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    DB_SOURCE:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫V1_YOUR_CONTEXT_SET_ID: המזהה של קבוצת ההקשרים של גרסה 1.
  • ‫V2_YOUR_CONTEXT_SET_ID: המזהה של קבוצת ההקשרים של גרסה 2.
  • ‫DB_SOURCE: הגדרות המקור של מסד הנתונים.

הסרת המשאבים

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

מחיקת קבוצת ההקשרים

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

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.

  3. בתפריט הניווט, לוחצים על Spanner Studio.

  4. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על View actions ().

  5. לוחצים על מחיקת קבוצת ההקשר.

  6. בחלון Delete context set, מזינים flights-assistant.

  7. לוחצים על אישור.

מחיקת המכונה

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

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. לוחצים על השם של המכונה שרוצים למחוק, לדוגמה Test Instance.

  3. לוחצים על Delete instance.

  4. כדי לאשר שרוצים למחוק את המכונה, מזינים את שם המכונה ולוחצים על Delete.

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