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

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

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

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

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

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

הצגת הקשר עם QueryData

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

  • ‫alloydb ל-AlloyDB ל-PostgreSQL
  • ‫spanner_reference ל-GoogleSQL ל-Spanner
  • ‫cloud_sql_reference ל-Cloud SQL ל-MySQL ול-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 ל-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"
           "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 ל-MySQL

{
 "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
 }
}

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": "POSTGRES"
           "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: חובה כשמבצעים שאילתה במסד הנתונים. השדה הזה משתנה בהתאם למסד הנתונים שאתם שולחים אליו שאילתה.
        • ‫database_reference: מציין מידע שקשור למופע מסד הנתונים.
          • ‫engine: מנוע מסד הנתונים או ניב ה-SQL. אופציונלי ב-AlloyDB. במסדי נתונים של Spanner, מגדירים את הערך GOOGLE_SQL. במכונות של Cloud SQL ל-MySQL, מגדירים את הערך MYSQL. במכונות Cloud SQL ל-PostgreSQL, צריך להגדיר את הערך POSTGRESQL.
          • ‫project_id: מזהה הפרויקט של מופע מסד הנתונים.
          • ‫region: האזור של מופע מסד הנתונים.
          • ‫cluster_id: מזהה האשכול של מופע מסד הנתונים.
          • ‫instance_id: מזהה המופע של מסד הנתונים.
          • ‫database_id: מזהה מסד הנתונים.
        • agent_context_reference: קישורים להקשר שנוצר במסד הנתונים.
  • ‫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."
}