במסמך הזה מוסבר איך לבדוק את QueryData ל-Spanner Graph באמצעות קריאה ל-method QueryData של Conversational Analytics API, ואיך לעדכן את קובץ קבוצת ההקשר. אתם יכולים לבדוק את היכולת של QueryData ליצור שאילתות ב-Graph Query Language (GQL) משאלות בשפה טבעית. אם שאילתת GQL שנוצרה לא מדויקת, אתם יכולים לעדכן את קובץ קבוצת ההקשר.
סקירה כללית על קבוצות הקשרים ב-Spanner Graph
לפני שמתחילים
- מוודאים שבמסד הנתונים ב-Spanner מוגדרים סכימת תרשים המאפיינים
FinGraphונתונים לדוגמה. הוראות ליצירת הסכימה שלFinGraphולהוספת הנתונים לדוגמה מפורטות במאמר הגדרה ושליחת שאילתות ב-Spanner Graph. - מוודאים שכבר נוצרה קבוצת הקשרים ושהקובץ של קבוצת ההקשרים הועלה למסד הנתונים. מידע נוסף זמין במאמר ניהול קבוצות הקשר ב-Spanner Studio.
- מתקינים ומפעילים את ה-CLI של Google Cloud.
איך מוצאים את המזהה של קבוצת ההקשרים הקיימת
כדי לבדוק את QueryData עם קבוצת ההקשרים, או כדי לחבר אפליקציית נתונים ל-QueryData, אתם צריכים את המזהה של קבוצת ההקשרים.
נכנסים לדף Spanner במסוף Google Cloud .
בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.
בתפריט הניווט, לוחצים על Spanner Studio.
בחלונית Explorer, לוחצים על View actions ליד קבוצת ההקשר שבה משתמשים.
לוחצים על עריכת קבוצת ההקשר.
שימו לב למזהה של קבוצת ההקשרים בקטע מזהה קבוצת ההקשרים. הפורמט של מזהה קבוצת ההקשר דומה ל-
projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
בדיקת QueryData באמצעות HTTP POST
כדי לבדוק את QueryData ב-Spanner Graph, שולחים בקשת POST מסוג QueryData שכוללת את השדה graph_ids ואת מזהה קבוצת ההקשר:
יוצרים קובץ בשם
request.jsonעם התוכן הבא:{ "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "PROJECT_ID", "instance_id": "INSTANCE_ID", "database_id": "DATABASE_ID", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "CONTEXT_SET_ID" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } }
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
INSTANCE_ID: מזהה המכונה של Spanner. -
DATABASE_ID: מזהה מסד הנתונים ב-Spanner. -
CONTEXT_SET_ID: המזהה המלא של קבוצת ההקשרים שרשמתם לעצמכם בקטע איתור המזהה של קבוצת ההקשרים.
-
שולחים את הבקשה:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \ -d @request.json
בתשובה, בודקים את השדה
generatedQuery(GRAPH FinGraph MATCH ...) כדי לוודא שהוא מדויק, ובודקים את השדהqueryResultבשורות שהוחזרו.
כדי לבדוק שאלות אחרות, משנים את הערך של prompt ב-request.json ושולחים שוב את הבקשה. כדי לראות איך QueryData פועל בלי הקשר שנוצר, מסירים את האובייקט agent_context_reference.
כדי לבדוק אם QueryData משתמש בהקשר שהגדרתם, אתם יכולים לשאול שאלה שתלויה בו (למשל, "מי הבעלים של החשבון ליום גשום?") ולהשוות בין התשובות עם האובייקט agent_context_reference ובלעדיו. בלי להגדיר את ההקשר, יכול להיות ש-QueryData יסנן לפי 'rainy day' ולא יחזיר שורות. אחרי הגדרת ההקשר, הפונקציה מסננת לפי 'Rainy Day Fund' ומחזירה את הערך "דנה".
מורידים ומעדכנים את קבוצת ההקשר הקיימת
אם התשובות לבדיקה מראות שצריך לשפר את שאילתת ה-GQL שנוצרה לשאלה בשפה טבעית, הורידו את קובץ קבוצת ההקשר הקיים. לאחר מכן, אתם יכולים לבדוק ולעדכן את תבניות השאילתות ב-GQL, את ההיבטים או את החיפושים לפי ערכים, ולהעלות את קובץ קבוצת ההקשרים המעודכן לקבוצת ההקשרים.
כדי להוריד ולעדכן קבוצת הקשר, מבצעים את השלבים הבאים:
- בחלונית Explorer, לוחצים על View actions לצד קבוצת ההקשרים.
- לוחצים על הורדת קובץ ההקשר.
- כדי לעדכן את קבוצת ההקשר עם עוד צמדים של שאילתות בשפה טבעית ושאילתות GQL, פועלים לפי השלבים שמפורטים בקטע יצירת קבוצות הקשר באמצעות סוכן עם מנוע הקשר.
- בחלונית Explorer, לוחצים על View actions ליד קבוצת ההקשר שבה משתמשים.
- לוחצים על עריכת קבוצת ההקשר.
- בקטע העלאת קובץ של קבוצת הקשרים, לוחצים על עיון ובוחרים את הקובץ המעודכן של קבוצת ההקשרים.
- לוחצים על שמירה כדי לעדכן את קבוצת ההקשרים.
- בודקים שוב את QueryData כדי לאמת את שאילתת ה-GQL שנוצרה.
אחרי שאתם מרוצים מהדיוק של התשובות, אתם יכולים להשתמש בנקודת הקצה QueryData כדי לחבר את האפליקציה לקבוצת ההקשר.
קישור של QueryData לאפליקציה
כדי לספק הקשר שנוצר על ידי משתמשים ולאפשר יצירת שאילתות GQL ל-Spanner Graph, צריך להגדיר את מזהה קבוצת ההקשרים ואת היעד graph_ids בהפעלת ה-method QueryData. מידע נוסף על השימוש ב-QueryData עם מקורות נתונים של מסדי נתונים זמין במאמר הגדרת הקשר של סוכן לאינטראקציה עם נתונים למקורות נתונים של מסדי נתונים. לדוגמה שמחברת אפליקציית סוכן ל-QueryData באמצעות כלי HTTP בהתאמה אישית ששולח קריאה ל-QueryData API בארכיטקטורת REST, ראו שילוב של QueryData באפליקציה.
דוגמה לבקשה מ-QueryData עם הקשר שנוצר על ידי המשתמש
בדוגמה הבאה מוצגת בקשת QueryData שמשתמשת במקור הנתונים של מסד הנתונים spanner_reference עבור תרשים המאפיינים FinGraph. צריך לספק את graph_ids בתוך spanner_reference.database_reference כדי ש-QueryData יטרגט את תרשים המאפיינים וייצור שאילתות GQL. השדה agent_context_reference.context_set_id מקשר להקשר שנוצר מראש ומאוחסן במסד הנתונים:
{ "parent": "projects/my-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "my-project", "instance_id": "my-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
גוף הבקשה מכיל את השדות הבאים:
-
parent: אופציונלי. הפרויקט והמיקום של הבקשה, בפורמטprojects/PROJECT_ID/locations/LOCATION. משתמשים באותו פרויקט ובאותו מיקום כמו בכתובת ה-URL של הבקשה. -
prompt: השאלה בשפה טבעית ממשתמש הקצה. -
context: מכיל מידע על מקורות הנתונים.-
datasource_references: מציין את מקור הנתונים. השדה הזה הוא אובייקט, לא רשימה.-
spanner_reference: נדרש כששולחים שאילתה למסד נתונים של Spanner.-
database_reference: מציין מידע שקשור למסד הנתונים של Spanner ולתרשימי המאפיינים.-
engine: הניב של מסד הנתונים. צריך להגדיר את הערךGOOGLE_SQLלמסדי נתונים של Spanner Graph. -
project_id: מזהה הפרויקט של מכונת Spanner. -
instance_id: מזהה המכונה של מכונת Spanner. -
database_id: המזהה של מסד הנתונים ב-Spanner. -
graph_ids: נדרש ל-Spanner Graph. רשימה של שמות תרשימי מאפיינים במסד הנתונים לשליחת שאילתות (לדוגמה,["FinGraph"]). כשמציינים אתgraph_ids, הפונקציה QueryData יוצרת שאילתות GQL לגבי תרשימי המאפיינים שצוינו. אם משמיטים אתgraph_ids, QueryData יוצר רק שאילתות SQL יחסיות בטבלאות הבסיסיות.
-
agent_context_reference: קישורים להקשר שנוצר במסד הנתונים.-
context_set_id: המזהה המלא של קבוצת ההקשרים ששמורה במסד הנתונים, למשלprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.
-
-
-
-
-
generation_options: מגדיר את סוג הפלט שייווצר.-
generate_query_result: צריך להגדיר את הערךtrueכדי להריץ את שאילתת ה-GQL שנוצרה ולהחזיר את תוצאות השאילתה. -
generate_natural_language_answer: אופציונלי. אם הערך הואtrue, נוצרת תשובה בשפה טבעית שמסכמת את תוצאות השאילתה. -
generate_explanation: אופציונלי. אם הערך הואtrue, נוצר הסבר על שאילתת ה-GQL. -
generate_disambiguation_question: אופציונלי. אם הערך הואtrue, המערכת יוצרת שאלות להפגת עמימות אם ההנחיה בשפה טבעית לא ברורה.
-
תשובה לדוגמה של QueryData
בדוגמה הבאה מוצגת תגובה מוצלחת מקריאה ל-QueryData בתרשים המאפיינים FinGraph. ה-API בארכיטקטורת REST מחזיר שמות של שדות ב-camelCase, כמו generatedQuery ו-queryResult. מכיוון שיצירת GQL היא לא דטרמיניסטית, השאילתה, שמות העמודות וטקסט התשובה שנוצרים יכולים להיות שונים בין קריאות.
{
"generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
"intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
"queryResult": {
"columns": [
{
"name": "recipient_name",
"type": "STRING"
},
{
"name": "recipient_account_id",
"type": "INT64"
},
{
"name": "transfer_amount",
"type": "FLOAT64"
}
],
"rows": [
{
"values": [
{
"value": "Alex"
},
{
"value": "7"
},
{
"value": "500"
}
]
},
{
"values": [
{
"value": "Lee"
},
{
"value": "16"
},
{
"value": "200"
}
]
}
],
"totalRowCount": "2"
},
"naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n* **Alex**: Account ID **7**, with a transfer amount of **500**\n* **Lee**: Account ID **16**, with a transfer amount of **200**"
}