בדיקת QueryData

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

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

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

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

כדי להוריד, לעדכן ולהעלות קבצים של קבוצות הקשר, ודאו שלמשתמש ב-IAM יש את התפקיד "עריכה של Dataplex Catalog"‏ (roles/dataplex.catalogEditor) או "אדמין של Dataplex Catalog"‏ (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 using QueryData with: CONTEXT_SET_NAME כדי לפתוח את חלונית יצירת השאילתות.

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

  9. בודקים ששאילתת ה-SQL מדויקת. לוחצים על Insert כדי להוסיף את השאילתה לעורך.

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

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

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

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

אחרי שאתם מרוצים מהדיוק של התשובות, אתם יכולים להעביר את המזהה של קבוצת ההקשר לנקודת הקצה (endpoint) ללא שמירת מצב (stateless) של QueryData בבקשות מהאפליקציה.

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

כדי להפנות לקבוצת ההקשרים שיצרתם ושמורה ב-Knowledge Catalog כשאתם שולחים קריאה לנקודת הקצה (endpoint) ללא שמירת מצב (stateless) QueryData מהאפליקציה, אתם צריכים את המזהה של קבוצת ההקשרים.

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

    כניסה ל-AlloyDB

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

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

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

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

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

  7. שימו לב לשם המשאב של קבוצת ההקשר במזהה קבוצת ההקשר. נקודת הקצה QueryData תומכת בשני הפורמטים הבאים של שמות משאבים של קבוצות הקשר ב-Knowledge Catalog:

    • פורמט של 6 קטעים: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, למשל projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • פורמט של 8 מקטעים: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (לדוגמה, @v1)

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

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

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

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

בדוגמה הבאה נשלחת בקשת QueryData בלי שמירת מצב באמצעות מקור הנתונים של מסד הנתונים alloydb. השדה agent_context_reference.context_set_id מקשר את הבקשה לקבוצת ההקשרים שיצרתם מראש, שמאוחסנת ב-Knowledge Catalog ולא במסד הנתונים שלכם:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "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": "PROJECT_ID",
          "region": "LOCATION",
          "cluster_id": "CLUSTER_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

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

  • ‫PROJECT_ID: המזהה של הפרויקט בענן ב-Google Cloud ששימש לבקשה.
  • ‫LOCATION: האזור של הבקשה, למשל us-central1.
  • ‫CLUSTER_ID: מזהה האשכול של AlloyDB.
  • ‫INSTANCE_ID: מזהה המכונה של AlloyDB.
  • ‫DATABASE_ID: מזהה מסד הנתונים.
  • ‫CONTEXT_SET_ID: המזהה של קבוצת ההקשרים.

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

  • ‫prompt: השאלה בשפה טבעית ממשתמש הקצה.
  • ‫context: מכיל מידע על מקורות הנתונים.
    • ‫datasource_references: מציין את סוג מקור הנתונים.
      • ‫alloydb: נדרש כששולחים שאילתה למסד הנתונים.
        • ‫database_reference: מידע שקשור למכונה של מסד הנתונים.
          • ‫cluster_id: מזהה האשכול של המכונה של מסד הנתונים.
          • ‫project_id: מזהה הפרויקט של המכונה של מסד הנתונים.
          • ‫region: האזור של מכונת AlloyDB.
          • ‫instance_id: המזהה של מכונת AlloyDB.
          • ‫database_id: מזהה מסד הנתונים.
        • agent_context_reference: מקשר את הבקשה ללא שמירת מצב (stateless) של QueryData לקבוצת ההקשרים שיצרתם, שמאוחסנת ב-Knowledge Catalog ולא במסד הנתונים שלכם.
          • ‫context_set_id: שם המשאב המלא של קבוצת ההקשרים ששמורה ב-Knowledge Catalog. אפשר לציין את הפורמט של 6 מקטעים, projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, או את הפורמט של 8 מקטעים, projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (לדוגמה, @v1).
  • ‫generation_options: מגדיר את סוג הפלט שנוצר.
    • ‫generate_query_result: צריך להגדיר כ-true כדי ליצור ולהחזיר את תוצאות השאילתה.
    • ‫generate_natural_language_answer: אופציונלי. אם הערך מוגדר כ-true, נוצרת תשובה בשפה טבעית.
    • ‫generate_explanation: אופציונלי. אם הערך הוא True, נוצר הסבר על שאילתת ה-SQL.
    • ‫generate_disambiguation_question: אופציונלי. אם המדיניות מוגדרת כ-True, נוצרות שאלות להפגת עמימות אם השאילתה לא ברורה.

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

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

{
  "generatedQuery": "-- 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",
  "intentExplanation": "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.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

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