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

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

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

מטרות

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

עלויות

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

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

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

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

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

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

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

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

הכנת מסד נתונים ב-Firestore

מוודאים שיש לכם מסד נתונים במהדורת Firestore Enterprise עם תאימות ל-MongoDB.

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

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

איך מאכלסים את האוספים flights ו-airports

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

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

    כניסה ל-Firestore

  2. בוחרים מסד נתונים מהרשימה. לדוגמה, אם יצרתם מסד נתונים חדש קודם, בחרו אותו. מסד הנתונים חייב להיות במהדורת Enterprise עם תאימות ל-MongoDB.

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

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

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

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

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

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

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

    כניסה ל-Firestore

  2. בוחרים מסד נתונים מהרשימה. מסד הנתונים חייב להיות מסוג Enterprise במצב תאימות ל-MongoDB.

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

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

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

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

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

בדיקת QueryData ב-Studio

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

  1. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על More actions ().
  2. לוחצים על הגדרת הקשר של הבדיקה.
  3. בעורך השאילתות, לוחצים על Generate MQL using QueryData with: flights-assistant.

  4. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת MQL, ולוחצים על Generate.

    Find flights from SFO to JFK.

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

      db.flights.find({"departure_airport": "SFO", "arrival_airport": "JFK"})

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

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

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

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

    // The database schema does not contain information about traffic.
// Returning all flights departing from New York airports.
db.flights.find({
  $and: [
    {
      "departure_airport": {"$regex": "New York", "$options": "i"}
    },
    {
      "$or": [
        {"departure_time": {"$exists": true}},
        {"arrival_time": {"$exists": true}}
      ]
    }
  ]
})

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

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

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

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

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

  1. מתקינים את Antigravity CLI. מידע נוסף זמין במאמר תחילת העבודה עם Antigravity CLI.
  2. מתקינים את Google Cloud CLI.

  3. הגדרת Application Default Credentials ‏ (ADC). מריצים את הפקודות הבאות בטרמינל כדי לאמת ולבחור את הפרויקט:

    gcloud auth application-default login

  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. החיבור מוגדר בקובץ התצורה tools.yaml.

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

    Help me set up context generation for a Firestore database with MongoDB compatibility.

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

  8. כדי לטעון מחדש את ההגדרות אחרי שיוצרים את הקובץ 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 MQL query:

db.flights.aggregate([
  {
    "$lookup": {
      "from": "airports",
      "localField": "departure_airport",
      "foreignField": "iata",
      "as": "departure_airport_info",
      "pipeline": [{ "$project": { "_id": 0, "name": 1, "city": 1 } }]
    }
  },
  { "$unwind": { "path": "$departure_airport_info" } },
  {
    "$match": {
      "$expr": {
        "$and": [
          { "$eq": ["$departure_airport_info.city", "New York"] },
          {
            "$or": [
              { "$lte": [{ "$hour": "$departure_time" }, 17] },
              { "$gte": [{ "$hour": "$departure_time" }, 19] }
            ]
          }
        ]
      }
    }
  },
])

  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": "db.flights.aggregate([\n  {\n    \"$lookup\": {\n      \"from\": \"airports\",\n      \"localField\": \"departure_airport\",\n      \"foreignField\": \"iata\",\n      \"as\": \"departure_airport_info\",\n      \"pipeline\": [{ \"$project\": { \"_id\": 0, \"name\": 1, \"city\": 1 } }]\n    }\n  },\n  { \"$unwind\": { \"path\": \"$departure_airport_info\" } },\n  {\n    \"$match\": {\n      \"$expr\": {\n        \"$and\": [\n          { \"$eq\": [\"$departure_airport_info.city\", \"New York\"] },\n          {\n            \"$or\": [\n              { \"$lte\": [{ \"$hour\": \"$departure_time\" }, 17] },\n              { \"$gte\": [{ \"$hour\": \"$departure_time\" }, 19] }\n            ]\n          }\n        ]\n      }\n    }\n  }\n])",
      "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": "db.flights.aggregate([\n  {\n    \"$lookup\": {\n      \"from\": \"airports\",\n      \"localField\": \"departure_airport\",\n      \"foreignField\": \"iata\",\n      \"as\": \"departure_airport_info\",\n      \"pipeline\": [{ \"$project\": { \"_id\": 0, \"name\": 1, \"city\": 1 } }]\n    }\n  },\n  { \"$unwind\": { \"path\": \"$departure_airport_info\" } },\n  {\n    \"$match\": {\n      \"$expr\": {\n        \"$and\": [\n          { \"$eq\": [\"$departure_airport_info.city\", \"$1\"] },\n          {\n            \"$or\": [\n              { \"$lte\": [{ \"$hour\": \"$departure_time\" }, 17] },\n              { \"$gte\": [{ \"$hour\": \"$departure_time\" }, 19] }\n            ]\n          }\n        ]\n      }\n    }\n  }\n])",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from $1"
      }
    }
  ]
}

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

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

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

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

    כניסה ל-Firestore

  2. בוחרים מסד נתונים מהרשימה. מסד הנתונים חייב להיות במהדורת Enterprise במצב תאימות ל-MongoDB.

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

  4. בחלונית Explorer, לצד Context sets, לוחצים על סמל הפעולות ().

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

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

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

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

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

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

  1. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על More actions ().
  2. לוחצים על קבוצת הקשר לבדיקה.
  3. בעורך השאילתות, לוחצים על Generate MQL using QueryData with: flights-assistant.

  4. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת MQL ולוחצים על יצירה.

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

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

    // Tell me flights that can help me beat nighttime traffic if traveling from New York
db.flights.aggregate([
  {
    "$lookup": {
      "from": "airports",
      "localField": "departure_airport",
      "foreignField": "iata",
      "as": "departure_airport_info",
      "pipeline": [{ "$project": { "_id": 0, "name": 1, "city": 1 } }]
    }
  },
  { "$unwind": { "path": "$departure_airport_info" } },
  {
    "$match": {
      "$expr": {
        "$and": [
          { "$eq": ["$departure_airport_info.city", "New York"] },
          {
            "$or": [
              { "$lte": [{ "$hour": "$departure_time" }, 17] },
              { "$gte": [{ "$hour": "$departure_time" }, 19] }
            ]
          }
        ]
      }
    }
  }
])

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

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

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

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

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

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

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

    // What are the flights that can help me avoid evening traffic if departing from Boston
db.flights.aggregate([
  {
    "$lookup": {
      "from": "airports",
      "localField": "departure_airport",
      "foreignField": "iata",
      "as": "departure_airport_info",
      "pipeline": [{ "$project": { "_id": 0, "name": 1, "city": 1 } }]
    }
  },
  { "$unwind": { "path": "$departure_airport_info" } },
  {
    "$match": {
      "$expr": {
        "$and": [
          { "$eq": ["$departure_airport_info.city", "Boston"] },
          {
            "$or": [
              { "$lte": [{ "$hour": "$departure_time" }, 17] },
              { "$gte": [{ "$hour": "$departure_time" }, 19] }
            ]
          }
        ]
      }
    }
  }
])

שילוב של 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

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

  4. מוסיפים את ההגדרה הבאה ל-tools.yaml כדי להתחבר לסוכן הנתונים באמצעות MCP Toolbox. מידע נוסף זמין במאמרים מקור הנתונים של 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 MongoDB-compatible query language (MQL), natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    firestoreReference:
      databaseReference:
        projectId: "PROJECT_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫DATABASE_ID: השם של מסד הנתונים שאליו רוצים להתחבר.
    • ‫REGION_ID: האזור של מסד הנתונים (לדוגמה, us-central1).
    • ‫CONTEXT_SET_ID: המזהה של קבוצת ההקשרים. איך מוצאים את מזהה קבוצת ההקשר

  5. מריצים את השרת MCP Toolbox עם הקובץ tools.yaml.

    ./toolbox --config autoctx/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-3.8-flash או דגם חדש יותר.

      3. בוחרים באפשרות Google AI ומזינים את מפתח Gemini API. מידע נוסף על איתור מפתח API זמין במאמר שימוש במפתחות API של Gemini. (לחלופין, אם אתם לא צריכים תקופת ניסיון בחינם, אתם יכולים לבחור באפשרות Vertex AI ולציין פרויקט ב- Google Cloud שהחיוב מופעל בו).

    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 MQL. 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-3.8-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

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

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

לדוגמה, לוחצים על בועת הסוכן של טקסט הקלט 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. משתמשים בסוכן עם מנוע תלוי הקשר כדי ליצור הקשר, ואז מעלים את קובץ קבוצת ההקשר המעודכן לסוכן הנתונים הקיים flights-assistant. מידע נוסף זמין במאמר בנושא ניהול של ערכות הקשר ב-Firestore 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.

בקרת גישה ושיקולי אבטחה

בגרסת טרום-השקה, QueryData ל-Firestore עם תאימות ל-MongoDB לא תומך בבקרת גישה מפורטת. כשמשלבים את QueryData באפליקציה, חשוב להביא בחשבון את אופן השליטה בגישה לנתונים:

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

הסרת המשאבים

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

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

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

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

    כניסה ל-Firestore

  2. בוחרים מסד נתונים מהרשימה. מסד הנתונים חייב להיות מסוג Enterprise במצב תאימות ל-MongoDB.

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

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

  5. בחלון מחיקת קבוצת הקשר, מזינים flight-assistant בתיבת האישור.

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

מחיקת מסד הנתונים

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

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

    כניסה ל-Firestore

  2. מוצאים את השורה של שם מסד הנתונים שרוצים למחוק.

  3. לוחצים על סמל הפעולות () ואז על מחיקה.

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

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