במדריך הזה מוסבר איך להגדיר את QueryData ב-Spanner Graph ולהשתמש בו באמצעות מסוף Google Cloud , ואיך לשלב אותו באפליקציה. תלמדו איך להגדיר את תרשים המאפיינים של FinGraph, ליצור קובץ של קבוצת הקשר ב-Graph Query Language (GQL) באמצעות סוכן עם מנוע תלוי הקשר, ליצור קבוצת הקשר ב-Spanner Studio, לבדוק את QueryData על ידי קריאה לשיטה QueryData ב-Conversational Analytics API כשההגדרה של graph_ids מופעלת, ולהשתמש בכלי HTTP בהתאמה אישית ב-MCP Toolbox כדי לקשר אפליקציית סוכן ל-QueryData.
מידע נוסף זמין במאמר סקירה כללית על QueryData.
מטרות
- יוצרים את סכימת תרשים המאפיינים של
FinGraphומאכלסים אותה בנתוני תרשים לדוגמה. - צריך ליצור קובץ של קבוצת הקשר בשביל
FinGraphבאמצעות הסוכן עם מנוע תלוי הקשר. - יוצרים קבוצת הקשרים ומעלים את הקובץ של קבוצת ההקשרים ב-Spanner Studio.
- בודקים את QueryData ויוצרים שאילתות GQL על ידי קריאה ל-API בארכיטקטורת REST של
QueryDataעםgraph_idsשצוין ב-spanner_reference. - משלבים את QueryData באפליקציה באמצעות כלי HTTP בהתאמה אישית ב-MCP Toolbox, ששולח קריאה ל-API בארכיטקטורת REST של
QueryData. - מבססים את התשובות של ה-LLM על נתוני התרשים באמצעות תבניות שאילתות, מאפייני שאילתות ושאילתות חיפוש של ערכי
GRAPH_TABLE.
עלויות
במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:
כדי להעריך את העלויות בהתאם לשימוש הצפוי, אתם יכולים להשתמש במחשבון העלויות.
משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.
כדי להימנע מחיובים נוספים, מחקו את המשאבים שיצרתם אחרי שסיימתם את המשימות שבמסמך הזה. מידע נוסף זמין בקטע הסרת המשאבים.
לפני שמתחילים
לפני שיוצרים קבוצת הקשר, צריך לוודא שעומדים בדרישות הבאות:
הפעלת השירותים הנדרשים
מפעילים את השירותים הבאים בפרויקט:הכנת מכונה של Spanner
- מוודאים שיש מכונה זמינה של Spanner. מידע נוסף זמין במאמר יצירת מכונה.
- חשוב לוודא שאתם יוצרים מסד נתונים במכונה שבה תיצרו את הטבלאות. מידע נוסף זמין במאמר יצירת מסד נתונים במכונה של Spanner.
תפקידים והרשאות נדרשים
- מוסיפים למכונה חשבון משתמש או חשבון שירות ב-IAM. מידע נוסף זמין במאמר החלת תפקידי IAM.
- מקצים למשתמש ב-IAM את התפקידים
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumerו-roles/geminidataanalytics.queryDataUserברמת הפרויקט. מידע נוסף זמין במאמר הוספת קישור למדיניות IAM בפרויקט. - כדי ליצור, להעלות ולנהל קבוצות של הקשרים, צריך להקצות למשתמש ה-IAM את התפקיד "עריכה של Dataplex Catalog" (
roles/dataplex.catalogEditor) או "אדמין של Dataplex Catalog" (roles/dataplex.catalogAdmin) ברמת הפרויקט. מידע נוסף זמין במאמר הרשאות לקבוצות של הגדרות הקשר. - להקצות תפקידים והרשאות למשתמש ב-IAM ברמת הפרויקט למסדי הנתונים הנדרשים.
יצירת הסכימה FinGraph והוספת נתוני תרשים
במדריך הזה משתמשים במערך הנתונים של תרשים המאפיינים הפיננסיים FinGraph, שיוצר מודלים של צומתי Person ו-Account שמחוברים באמצעות קצוות של Owns (PersonOwnAccount) ו-Transfers (AccountTransferAccount).
כדי ליצור את הסכימה של FinGraph ולאכלס את נתוני התרשים במסד הנתונים של Spanner, מבצעים את השלבים הבאים במדריך להגדרת Spanner Graph:
- כדי ליצור את הטבלאות
Person,Account,PersonOwnAccountו-AccountTransferAccountואת הגדרת תרשים המאפייניםFinGraph, פועלים לפי ההוראות במאמר יצירת מסד נתונים של תרשים באמצעות סכימה. - פועלים לפי ההוראות בקטע הוספת נתוני תרשים כדי להוסיף ל-
FinGraphאת האנשים לדוגמה (Alex,Danaו-Lee), החשבונות (7,16ו-20), קצוות הבעלות על החשבון וקצוות העברת הכספים.
יצירת קבוצת הקשרים
יוצרים קבוצה ריקה של הקשרים בשם fingraph-assistant. בהמשך המדריך תעלו אליו קובץ של קבוצת הקשרים.
נכנסים לדף Spanner במסוף Google Cloud .
בוחרים את המכונה מהרשימה, ואז בוחרים את מסד הנתונים שמכיל את
FinGraph.בתפריט הניווט, לוחצים על Spanner Studio.
בחלונית Explorer, לצד Context sets, לוחצים על View actions.
לוחצים על יצירת קבוצת הקשרים.
בשדה Context set name, מזינים את הערך
fingraph-assistant.לוחצים על יצירה.
בדיקת QueryData בלי הקשר
בקטע הזה, אתם שולחים קריאה ל-API בארכיטקטורת REST של QueryData כדי ליצור שאילתות GQL לשאלות בשפה טבעית בלי להגדיר הקשר. בלי הקשר, QueryData יכול לענות על שאלות שממופות ישירות לסכימה של FinGraph, אבל הוא לא יכול לפרש מונחים עסקיים מותאמים אישית כמו high-risk transfers או לפתור הבדלים בפורמט של ערכים כמו Czech Republic לעומת Czech_Republic.
במסוף, מגדירים את משתני הסביבה הבאים:
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
INSTANCE_ID: מזהה המכונה של Spanner. -
DATABASE_ID: המזהה של מסד הנתונים שמכיל אתFinGraph.
-
יוצרים סקריפט עזר בשם
query_data.shששולח שאלה ל-API בארכיטקטורת REST שלQueryData, כשהערך שלgraph_idsמוגדר כ-FinGraph. אם משתנה הסביבהCONTEXT_SET_IDמוגדר, הסקריפט שולח גם את מזהה קבוצת ההקשר:cat > query_data.sh <<'EOF' #!/bin/bash # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION" if [[ -n "${CONTEXT_SET_ID}" ]]; then AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}" fi curl -sS -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 @- <<JSON { "prompt": "$1", "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} } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } } JSON EOF chmod +x query_data.shהסקריפט מוסיף את השאלה לגוף הבקשה כמו שהיא, אז אל תשתמשו במירכאות כפולות (
") בשאלה.שואלים שאלה שקשורה ישירות לסכימה של
FinGraph:./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
בתגובה, בודקים את השדות
generatedQueryו-queryResult. לשאלה החד-משמעית הזו, QueryData יוצר שאילתת GQL שדומה לזו:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account), (recipient:Person)-[:Owns]->(dst) RETURN recipient.name AS recipient_name, dst.id AS recipient_account_id, t.amount AS transfer_amount;התוצאות שיתקבלו יהיו דומות לתוצאות הבאות:
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+שואלים שאלה שכוללת את המונח העסקי
high-risk transfers:./query_data.sh "Find all high-risk transfers initiated by Alex"
מכיוון שהסכימה
FinGraphלא מגדירה מה נחשב ל-high-risk transfer(שבלוגיקה העסקית שלכם פירושו העברה של200או יותר לחשבון חסום שבוis_blocked = true), QueryData לא מחיל את מסנני הסף של החשבון החסום והסכום, או שהוא מחיל פרשנות משלו למונח. לדוגמה, QueryData עשוי להמציא סף סכום שלא מחזיר שורות, או להתעלם מהמונח וליצור שאילתה דומה לזו:-- Returning transfers initiated by Alex because 'high-risk' is not defined in the schema. GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account) RETURN src.id AS source_account_id, dst.id AS destination_account_id, t.amount AS transfer_amount, t.order_number;השאילתה הזו מחזירה את שתי ההעברות של אלכס, כולל ההעברה בסך
100שלא עומדת בתנאי הסף:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+שואלים שאלה שמתייחסת למדינה:
./query_data.sh "Find accounts owned by people from Czech Republic"
בלי קישור הקשר או ערך, QueryData יוצר שאילתת GQL שמסננת לפי
'Czech Republic'עם רווח. המאפייןPerson.countryב-FinGraphשומר את הערך בתור'Czech_Republic'עם קו תחתון, ולכן השאילתה לא מחזירה שורות:GRAPH FinGraph MATCH (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;
יצירת הקשר לקבוצת ההקשרים
בקטע הזה תכינו את הסביבה המקומית ותשתמשו בסוכן עם מנוע תלוי הקשר כדי ליצור קובץ של קבוצת הקשר (context_set.json) לתרשים המאפיינים FinGraph במסד הנתונים של Spanner.
מגדירים את הסביבה
כדי להגדיר את הסביבה של הסוכן להנדסת הקשר:
- מתקינים את Antigravity CLI. מידע נוסף זמין במאמר תחילת העבודה עם Antigravity CLI.
- מתקינים את Google Cloud CLI.
הגדרת Application Default Credentials (ADC). מריצים את הפקודה הבאה במסוף כדי לבצע אימות:
gcloud auth application-default loginבטרמינל, מפעילים את Antigravity CLI:
agyמגדירים את החיבור למסד הנתונים של Spanner. מזינים הנחיה שמציינת במפורש שאתם יוצרים הקשר לתרשימי המאפיינים במסד הנתונים של Spanner, וכוללת את שם תרשים המאפיינים
FinGraphכדי שהנציג יפעיל את תהליך העבודה של הנדסת ההקשר הספציפי ל-GQL:Help me set up the database connection for the FinGraph property graph in my Spanner database.פועלים לפי ההוראות של הנציג כדי ליצור את
autoctx/tools.yamlו-autoctx/state.md. אחר כך פותחים אתautoctx/state.mdומוודאים שהקטע## Active Databaseמכיל את השורה- **Graph Ids**: ["FinGraph"]. סוכן הנדסת ההקשר קורא את שמות תרשימי המאפיינים מהשורה הזו כשהוא יוצר הגדרות הערכה. מידע נוסף עלtools.yamlזמין במסמכי התיעוד של MCP Toolbox.כדי לטעון מחדש את ההגדרות אחרי שיוצרים את
autoctx/tools.yaml, מריצים את הפקודה הבאה ב-Antigravity CLI:/mcpלוחצים על
toolboxואז עלRestart.מוודאים שארגז הכלים של MCP והפלאגין של סוכן הנדסת ההקשר מחוברים ומוכנים לשימוש:
/mcp
יצירת הקשר לתבנית GQL
כדי לפתור את הבעיה שבה QueryData לא זיהה את המונח העסקי high-risk transfers, צריך להגדיר את high-risk transfers בקובץ של קבוצת ההקשר כהעברות של 200 או יותר שנשלחו לחשבון חסום (dst.is_blocked = true).
כדי ליצור את ההקשר של תבנית GQL:
מזינים את ההנחיה הבאה במעטפת האג'נטית, ומציינים ש-
FinGraphהוא תרשים מאפיינים במסד הנתונים של Spanner:For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;הנציג ממיר את הקלט שלכם לתבנית GQL עם פרמטרים, שמתאימה לשמות של אנשים באופן כללי. מידע נוסף זמין במאמר סקירה כללית בנושא קבוצות הקשר.
בודקים את תבנית השאילתה ב-GQL שנוצרה, ואז מזינים את ההנחיה
Save it to context_set.jsonלסוכן. הסוכן יוצר אתcontext_set.jsonבספרייה עם התוכן הבא:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ] }
יצירת הקשר לחיפוש של מאפיינים וערכים
בקטע הזה, מוסיפים ל-context_set.json מאפיין GQL ושתי שאילתות חיפוש של ערכי GRAPH_TABLE. התבנית שהוספתם בקטע הקודם עונה על שאלות עם מבנה זהה ל-"Find all high-risk transfers initiated by Alex". ההיבט מתעד את התבנית של החשבון החסום, כך ש-QueryData יכול להחיל אותה גם על שאלות שלא תואמות לתבנית, כמו "מצא את כל העברות הכספים שכוללות חשבון חסום". החיפושים של הערכים מאפשרים ל-QueryData למפות ביטויי ערכים כמו Czech Republic לערך המאוחסן Czech_Republic ב-Person.country, ולהתאים כינויים של חשבונות ב-Account.nick_name בלי קשר לאותיות רישיות.
מזינים את ההנחיה הבאה במעטפת האג'נטית, ומציינים ש-
FinGraphהוא תרשים מאפיינים במסד הנתונים של Spanner:For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.בודקים את קובץ
context_set.jsonהמעודכן, שמכיל עכשיו את התבנית של GQL, את המאפיין של GQL ואת ההגדרות של חיפוש הערכים:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ], "facets": [ { "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "intent": "transfers involving a blocked account", "manifest": "transfers involving a blocked account", "parameterized": { "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "parameterized_intent": "transfers involving a blocked account" } } ], "value_searches": [ { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Person country", "description": "Match for country names on Person nodes in FinGraph that ignores case and treats underscores as spaces" }, { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE LOWER(a.nick_name) = LOWER($value) RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Account nickname", "description": "Case-insensitive match for account nicknames on Account nodes in FinGraph" } ] }כל חיפוש ערך משתמש באופרטור
GRAPH_TABLEכדי להתאים תווית צומת ב-FinGraphומחזיר את ערך המאפיין המאוחסן, את מיקום המאפיין (FinGraph.Person.country), את סוג הקונספט, מרחק של0להתאמה והקשר JSON ריק. מידע נוסף זמין במאמר שאילתות חיפוש של ערכים.
העלאת קובץ קבוצת ההקשר ל-QueryData
בקטע הזה מעלים את הקובץ context_set.json לקבוצת ההקשר fingraph-assistant ב-Spanner Studio.
נכנסים לדף Spanner במסוף Google Cloud .
בוחרים את המכונה מהרשימה ואז בוחרים את מסד הנתונים ב-Spanner.
בתפריט הניווט, לוחצים על Spanner Studio.
בחלונית Explorer, לצד קבוצת ההקשר
fingraph-assistant, לוחצים על View actions.לוחצים על עריכת קבוצת ההקשר.
אופציונלי: עורכים את תיאור קבוצת ההקשרים.
בקטע העלאת קובץ של קבוצת הקשר, לוחצים על עיון ובוחרים את קובץ ה-
context_set.jsonשיצרתם.לוחצים על Save.
יצירת שאילתות GQL באמצעות QueryData
בקטע הזה, אתם שולחים קריאה ל-API בארכיטקטורת REST של QueryData עם ההקשר של fingraph-assistant כדי לוודא ש-QueryData מתרגם בצורה מדויקת מונחים עסקיים כמו high-risk transfers ופותר את Czech Republic ל-Czech_Republic בשאילתות GQL.
- מאתרים את המזהה של קבוצת ההקשרים של
fingraph-assistant. הוראות מפורטות זמינות במאמר איך למצוא את המזהה של קבוצת ההקשר. מגדירים את משתנה הסביבה
CONTEXT_SET_IDכדי ש-query_data.shישלח את קבוצת ההקשר:export CONTEXT_SET_ID="CONTEXT_SET_ID"
מחליפים את
CONTEXT_SET_IDבמזהה המלא של קבוצת ההקשרים, למשלprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.שואלים שוב את השאלה לגבי העברות בסיכון גבוה:
./query_data.sh "Find all high-risk transfers initiated by Alex"
שאילתת ה-GQL שנוצרה מחילה עכשיו את המסנן של חשבון היעד החסום (
is_blocked: true) ואת סף הסכום (t.amount >= 200):GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;השאילתה הזו לא כוללת את ההעברה של אלכס בסך
100לחשבון החסום16, ומחזירה תוצאות שדומות לתוצאות הבאות:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+אפשר לשאול שאלה דומה לגבי
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
מכיוון שתבנית ה-GQL ב-
context_set.jsonכוללת פרמטרים ({name: ?}), הפונקציה QueryData מחילה את אותה הגדרה שלhigh-risk transfersעלDana:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;השאילתה הזו לא כוללת את ההעברה של דנה בסך
500לחשבון הלא חסום7, ומחזירה תוצאות שדומות לאלה:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+שואלים שוב את השאלה לגבי המדינה:
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData מריצה את החיפוש של הערך
Person country, מקשרת אתCzech Republicלערך המאוחסןCzech_Republicויוצרת שאילתה שדומה לזו:GRAPH FinGraph MATCH (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;התוצאות שיתקבלו יהיו דומות לתוצאות הבאות:
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+שואלים שאלה שמשתמשת בהיבט של החשבון החסום:
./query_data.sh "Find all money transfers involving a blocked account."
QueryData משתמשת ב-facet כדי להתאים העברות בכל כיוון שכוללות את החשבון החסום
16, ומחזירה ארבע העברות.
שילוב של QueryData באפליקציה
בקטע הזה תיצרו אפליקציה של סוכן לאינטראקציה עם נתונים בשיחה ל-FinGraph באמצעות הערכה לפיתוח סוכנים (ADK), MCP Toolbox וקבוצת ההקשר של fingraph-assistant. כדי להפעיל יצירת שאילתות GQL ל-Spanner Graph, מגדירים כלי HTTP בהתאמה אישית בקובץ tools.yaml שקורא ל-API בארכיטקטורת REST של QueryData עם graph_ids שמוגדר ב-spanner_reference.database_reference.
- מורידים את MCP Toolbox בגרסה 1.4.0 ואילך. MCP Toolbox חושף את ה-API בארכיטקטורת REST של
QueryDataככלי MCP שאפליקציות יכולות להתחבר אליו. מגדירים את Application Default Credentials (ADC):
gcloud auth application-default loginיוצרים קובץ תצורה של
tools.yamlשמגדיר מקור HTTP ל-Conversational Analytics API וכלי HTTP שקורא ל-methodQueryData. חשוב לציין אתgraph_ids(מוגדר כ-["FinGraph"]) בקטעspanner_reference.database_referenceבגוף הבקשה:kind: source name: gda-rest-source type: http baseUrl: https://geminidataanalytics.googleapis.com timeout: 120s headers: Authorization: Bearer ${GDA_ACCESS_TOKEN} Content-Type: application/json x-goog-user-project: ${PROJECT_ID} --- kind: tool name: fingraph_query_data_tool type: http source: gda-rest-source method: POST path: /v1beta/projects/${PROJECT_ID}/locations/global:queryData description: Use this tool to send natural language questions about the FinGraph property graph to the QueryData API and receive GQL queries, query results, natural language answers, and explanations. requestBody: | { "parent": "projects/${PROJECT_ID}/locations/global", "prompt": {{json .query}}, "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, "generate_disambiguation_question": true } } bodyParams: - name: query type: string description: A natural language question about the FinGraph property graph.MCP Toolbox מחליף את ההפניות של
${...}בערכים של משתני הסביבה המתאימים כשהוא טוען אתtools.yaml, ומחליף את{{json .query}}בשאלה שהנציג שולח לכלי, בקידוד של מחרוזת JSON.בטרמינל שבו מפעילים את MCP Toolbox, מגדירים את משתני הסביבה ש-
tools.yamlמפנה אליהם:export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID" export CONTEXT_SET_ID="CONTEXT_SET_ID" export GDA_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud . -
INSTANCE_ID: המזהה של מכונת Spanner. -
DATABASE_ID: המזהה של מסד הנתונים ב-Spanner שמכיל אתFinGraph. -
CONTEXT_SET_ID: המזהה המלא של קבוצת ההקשרים שלfingraph-assistant.
-
מריצים את שרת MCP Toolbox עם הקובץ
tools.yaml:./toolbox --config "tools.yaml"יוצרים אפליקציית ADK שמפעילה את הכלי
fingraph_query_data_toolבאמצעות MCP Toolbox Python SDK:יוצרים ספרייה לאפליקציה, למשל
fingraph-assistant-app, ועוברים אליה:mkdir fingraph-assistant-appcd fingraph-assistant-appיוצרים סביבה וירטואלית ומתקינים את החבילות הנדרשות:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkיוצרים סוכן ADK:
adk create my_agentבוחרים את המודל
gemini-2.5-flash, בוחרים באפשרות Google AI ומזינים את מפתח Gemini API. מידע נוסף זמין במאמר שימוש במפתחות Gemini API.מחליפים את התוכן של
my_agent/agent.pyבקוד האפליקציה לדוגמה Financial Graph Assistant:from typing import cast from google.adk.agents.llm_agent import Agent from google.adk.agents.llm_agent import ToolUnion from toolbox_core import ToolboxSyncClient TOOLBOX_URL = "http://127.0.0.1:5000" INSTRUCTION = """ # ROLE You are a factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone. - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query. # OPERATIONAL CONSTRAINTS - TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides. - TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating GQL. Frame all responses as your own direct assistance. - SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task and guide the user toward what you can help with. # COMMUNICATION STYLE - Be concise and scannable when listing answers. - Maintain a helpful, professional persona. ===== # QUERY DATA TOOL Inputs: 1. query: A natural language formulation of a graph database query. Outputs: (all optional) 1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input. 2. generatedQuery: The generated GQL query for the user query. 3. intentExplanation: An explanation for why the tool produced `generatedQuery`. 4. queryResult: The result of executing `generatedQuery`. 5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`. Usage guidance: 1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification. 2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` to see if you need to clarify any assumptions for the user. 3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning. """ client = ToolboxSyncClient(TOOLBOX_URL) mcp_tool = client.load_tool("fingraph_query_data_tool") root_agent = Agent( model="gemini-2.5-flash", name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
מפעילים את שרת האינטרנט של ADK בכתובת
http://127.0.0.1:8000:adk web --port 8000מזינים שאלה על תרשים עם כמה קפיצות בממשק המשתמש של ADK באינטרנט:
Who did Dana transfer money to, and what were the amounts?הנציג מפעיל את הכלי
fingraph_query_data_tool, ששולח את השאלה ל-API בארכיטקטורת REST שלQueryData, כשהפרמטרgraph_idsמוגדר ל-FinGraph. הפונקציה QueryData מריצה את שאילתת ה-GQL שנוצרה, והנציג מחזיר תשובה שדומה לזו:Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200מזינים שאלה שמשתמשת בתבנית
high-risk transfersGQL שהוספתם לקבוצת ההקשר:What are the high-risk transfers initiated by Alex?על סמך תבנית ה-GQL ב-
fingraph-assistant, QueryData מזהה העברות של לפחות200לחשבון חסום, והנציג מחזיר תשובה שדומה לזו:Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
שיפור ביצועי הסוכן
ממשק המשתמש של ADK באינטרנט מאפשר לבדוק את המטען הייעודי (payload) של הבקשה והתגובה מהכלי fingraph_query_data_tool. בכרטיסייה Event בחלונית הניווט, מרחיבים את functionResponse כדי לבדוק את שאילתת ה-GQL שנוצרה ב-FinGraph (generatedQuery), queryResult, intentExplanation, disambiguationQuestion ו-naturalLanguageAnswer. ה-API בארכיטקטורת REST של QueryData מחזיר את שמות השדות האלה ב-camelCase.
שיפור הדיוק של התשובות
כדי לשפר את הדיוק של התשובות מ-QueryData, אתם יכולים להוסיף תבניות GQL, מאפיינים וחיפושי ערכים. משתמשים בסוכן עם מנוע תלוי הקשר כדי ליצור ולהעריך הקשר מעודכן לתרשים המאפיינים FinGraph במסד הנתונים ב-Spanner, ואז מעלים את קובץ קבוצת ההקשר המעודכן ב-Spanner Studio. מידע נוסף זמין במאמר ניהול קבוצות הקשר ב-Spanner Studio.
כמה נציגים
בסביבת הפיתוח, אתם יכולים לבצע בדיקות A/B בכמה קבוצות הקשר של Spanner Graph. כדי לעשות את זה, מגדירים כמה כלי HTTP בקובץ tools.yaml (למשל fingraph_query_data_tool_v1 ו-fingraph_query_data_tool_v2). גוף הבקשה של כל כלי מגדיר את graph_ids ל-["FinGraph"] ואת context_set_id אחר.
הסרת המשאבים
כדי להימנע מחיובים נוספים, מחקו את המשאבים שיצרתם אחרי שסיימתם את המדריך.
מחיקת קבוצת ההקשרים
לפני שמוחקים את מסד הנתונים או המכונה של Spanner, צריך למחוק את קבוצת ההקשר fingraph-assistant:
נכנסים לדף Spanner במסוף Google Cloud .
בוחרים את המכונה מהרשימה ואז בוחרים את מסד הנתונים ב-Spanner.
בתפריט הניווט, לוחצים על Spanner Studio.
בחלונית Explorer, לצד
fingraph-assistant, לוחצים על View actions.לוחצים על מחיקת קבוצת ההקשר, מזינים
fingraph-assistantבשדה האישור ולוחצים על אישור.
מחיקת מסד הנתונים והמכונה
כדי למחוק את תרשים המאפיינים FinGraph, את מסד הנתונים של Spanner ואת המכונה של Spanner, פועלים לפי השלבים שמפורטים במאמר הגדרה ושליחת שאילתות ב-Spanner Graph: ניקוי.