הגדרת הקשר של סוכן הנתונים למקורות נתונים של מסדי נתונים

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

הקשר שנוצר על ידי המשתמש הוא הנחיות שבעלי סוכני נתונים יכולים לספק כדי לעצב את ההתנהגות של סוכן נתונים ולשפר את התשובות של ה-API. הקשר יעיל שנוצר על ידי מחבר מספק לסוכני הנתונים של Conversational Analytics API הקשר שימושי למענה על שאלות לגבי מקורות הנתונים שלכם.

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

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

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

הוספת הקשר באמצעות QueryData

כשמתקשרים לשיטה QueryData, מספקים את מקור הנתונים ואת פרטי ההקשר בשדה QueryDataRequest.context.datasourceReferences. למקורות נתונים של מסדי נתונים, צריך להשתמש באחת מהאפשרויות הבאות:

  • ‫alloydb ל-AlloyDB ל-PostgreSQL
  • ‫spanner_reference ל-GoogleSQL ל-Spanner
  • ‫cloud_sql_reference ל-Cloud SQL ול-Cloud SQL ל-PostgreSQL

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

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

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

AlloyDB

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

‫GoogleSQL for Spanner

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "spanner_reference" {
         "database_reference" {
           "engine": "GOOGLE_SQL"
           "project_id": "data-agents-project"
           "region": "us-central1"
           "instance_id": "evalbench"
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

‫Cloud SQL ו-Cloud SQL ל-PostgreSQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/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: חובה כשמבצעים שאילתה במסד הנתונים. השדה הזה משתנה בהתאם למסד הנתונים שאתם שולחים אליו שאילתה.
  • ‫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."
}