בדיקת QueryData

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

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

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

מוודאים שקבוצת הקשר כבר נוצרה וקובץ קבוצת הקשר הועלה לסוכן QueryData. מידע נוסף זמין במאמר ניהול של ערכות הקשר ב-AlloyDB Studio.

כדי להוריד, לעדכן ולהעלות קבצים של הגדרות הקשר, צריך לוודא שלמשתמש ה-IAM יש את התפקיד 'עריכת קטלוג Dataplex' (roles/dataplex.catalogEditor) או 'אדמין קטלוג Dataplex' (roles/dataplex.catalogAdmin) בפרויקט. מידע נוסף זמין במאמר הרשאות לקבוצות של הגדרות הקשר.

בדיקת QueryData

כדי לבדוק QueryData, פועלים לפי השלבים הבאים:

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

    כניסה ל-AlloyDB

  2. בוחרים אשכול מהרשימה.

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

  4. נכנסים ל-Studio באמצעות אימות של ניהול זהויות והרשאות גישה (IAM).

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

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

  7. בעורך השאילתות, לוחצים על Generate SQL כדי לפתוח את החלונית עזרה בתכנות.

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

  9. בודקים ששאילתת ה-SQL מדויקת.

הורדה ועדכון של קבוצת הקשרים

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

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

  1. בחלונית Explorer, לוחצים על הצגת פעולות.
  2. לוחצים על הורדת קובץ ההקשר.
  3. כדי לעדכן את ההקשר עם זוגות נוספים של שאילתות, פועלים לפי השלבים שמפורטים בקטע יצירת קבוצות הקשר באמצעות סוכן עם מנוע הקשר.
  4. בחלונית Explorer, לוחצים על View actions (הצגת פעולות) לצד קבוצת ההקשר שבה משתמשים.
  5. לוחצים על עריכת קבוצת ההקשרים.
  6. בקטע העלאת קובץ של קבוצת הקשרים, לוחצים על עיון ובוחרים את הקובץ המעודכן של קבוצת ההקשרים.
  7. לוחצים על שמירה כדי לעדכן את קבוצת ההקשרים.

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

איך מוצאים את המזהה של קבוצת ההקשרים

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

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

    כניסה ל-AlloyDB

  2. בוחרים אשכול מהרשימה.

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

  4. נכנסים ל-Studio באמצעות אימות של ניהול זהויות והרשאות גישה (IAM).

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

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

  7. שימו לב למזהה ההקשר במזהה קבוצת ההקשרים. הפורמט של מזהה קבוצת ההקשר דומה ל-projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates.

חיבור QueryData לאפליקציה

מגדירים את מזהה קבוצת ההקשרים בהפעלת ה-method‏ QueryData כדי לספק הקשר שנוצר על ידי משתמשים למקורות נתונים של מסדי נתונים כמו AlloyDB,‏ Spanner,‏ Cloud SQL,‏ Cloud SQL ל-PostgreSQL ו-Firestore. מידע נוסף זמין במאמר הגדרת הקשר של סוכן נתונים למקורות נתונים של מסדי נתונים.

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

דוגמה לבקשה ב-QueryData עם הקשר שנוצר על ידי המשתמש

הדוגמה הבאה מציגה בקשת QueryData שמשתמשת במקור נתונים של מסד נתונים ב-alloydb. השדה agent_context_reference.context_set_id משמש לקישור להקשר שנוצר מראש ומאוחסן במסד הנתונים.

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "context-set-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

גוף הבקשה מכיל את השדות הבאים:

  • ‫prompt: השאלה בשפה טבעית ממשתמש הקצה.
  • ‫context: מכיל מידע על מקורות הנתונים.
    • ‫datasource_references: מציין את הסוג של מקור הנתונים.
      • ‫alloydb: חובה כשמבצעים שאילתה במסד הנתונים. השדה הזה משתנה בהתאם למסד הנתונים שאתם שולחים אליו שאילתה.
        • ‫database_reference: מציין מידע שקשור למכונה של מסד הנתונים.
          • ‫cluster_id: מזהה האשכול של מכונת מסד הנתונים.
          • ‫project_id: מזהה הפרויקט של המכונה של מסד הנתונים.
          • ‫region: האזור של מכונת AlloyDB.
          • ‫instance_id: מזהה המכונה של מכונת AlloyDB.
          • ‫database_id: מזהה מסד הנתונים.
        • agent_context_reference: קישורים להקשר שנוצר במסד הנתונים.
          • ‫context_set_id: המזהה המלא של קבוצת ההקשרים ששמורה במסד הנתונים. לדוגמה, projects/context-set-project/locations/us-central1/contextSets/bdf_gsql_gemini_all_templates.
  • ‫generationOptions: מגדיר את סוג הפלט שייווצר.
    • ‫generate_query_result: צריך להגדיר את הערך כ-true כדי ליצור ולהחזיר את תוצאות השאילתה.
    • ‫generate_natural_language_answer: אופציונלי. אם הערך מוגדר כ-true, נוצרת תשובה בשפה טבעית.
    • ‫generate_explanation: אופציונלי. אם הערך הוא True, נוצר הסבר על שאילתת ה-SQL.
    • ‫generate_disambiguation_question: אופציונלי. אם המדיניות מוגדרת כ-True, נוצרות שאלות להפגת עמימות אם השאילתה לא ברורה.

דוגמה לתגובה QueryData

דוגמה לתשובה מוצלחת מקריאה ל-QueryData:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

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