שילוב של QueryData עם אפליקציה

במדריך הזה מוסבר איך להגדיר את 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

תפקידים והרשאות נדרשים

  • מוסיפים למכונה חשבון משתמש או חשבון שירות ב-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:

  1. כדי ליצור את הטבלאות Person,‏ Account,‏ PersonOwnAccount ו-AccountTransferAccount ואת הגדרת תרשים המאפיינים FinGraph, פועלים לפי ההוראות במאמר יצירת מסד נתונים של תרשים באמצעות סכימה.
  2. פועלים לפי ההוראות בקטע הוספת נתוני תרשים כדי להוסיף ל-FinGraph את האנשים לדוגמה (Alex,‏ Dana ו-Lee), החשבונות (7,‏ 16 ו-20), קצוות הבעלות על החשבון וקצוות העברת הכספים.

יצירת קבוצת הקשרים

יוצרים קבוצה ריקה של הקשרים בשם fingraph-assistant. בהמשך המדריך תעלו אליו קובץ של קבוצת הקשרים.

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

    כניסה ל-Spanner

  2. בוחרים את המכונה מהרשימה, ואז בוחרים את מסד הנתונים שמכיל את FinGraph.

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

  4. בחלונית Explorer, לצד Context sets, לוחצים על View actions.

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

  6. בשדה Context set name, מזינים את הערך fingraph-assistant.

  7. לוחצים על יצירה.

בדיקת QueryData בלי הקשר

בקטע הזה, אתם שולחים קריאה ל-API בארכיטקטורת REST של QueryData כדי ליצור שאילתות GQL לשאלות בשפה טבעית בלי להגדיר הקשר. בלי הקשר, QueryData יכול לענות על שאלות שממופות ישירות לסכימה של FinGraph, אבל הוא לא יכול לפרש מונחים עסקיים מותאמים אישית כמו high-risk transfers או לפתור הבדלים בפורמט של ערכים כמו Czech Republic לעומת Czech_Republic.

  1. במסוף, מגדירים את משתני הסביבה הבאים:

    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.
  2. יוצרים סקריפט עזר בשם 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
    

    הסקריפט מוסיף את השאלה לגוף הבקשה כמו שהיא, אז אל תשתמשו במירכאות כפולות (") בשאלה.

  3. שואלים שאלה שקשורה ישירות לסכימה של 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             |
    +----------------+----------------------+-----------------+
    
  4. שואלים שאלה שכוללת את המונח העסקי 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 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. שואלים שאלה שמתייחסת למדינה:

    ./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.

מגדירים את הסביבה

כדי להגדיר את הסביבה של הסוכן להנדסת הקשר:

  1. מתקינים את Antigravity CLI. מידע נוסף זמין במאמר תחילת העבודה עם Antigravity CLI.
  2. מתקינים את Google Cloud CLI.
  3. הגדרת Application Default Credentials ‏(ADC). מריצים את הפקודה הבאה במסוף כדי לבצע אימות:

    gcloud auth application-default login
  4. התקנת סוכן הנדסת ההקשר.

  5. בטרמינל, מפעילים את Antigravity CLI:

    agy
  6. מגדירים את החיבור למסד הנתונים של 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.

  7. כדי לטעון מחדש את ההגדרות אחרי שיוצרים את autoctx/tools.yaml, מריצים את הפקודה הבאה ב-Antigravity CLI:

    /mcp
  8. לוחצים על toolbox ואז על Restart.

  9. מוודאים שארגז הכלים של MCP והפלאגין של סוכן הנדסת ההקשר מחוברים ומוכנים לשימוש:

    /mcp

יצירת הקשר לתבנית GQL

כדי לפתור את הבעיה שבה QueryData לא זיהה את המונח העסקי high-risk transfers, צריך להגדיר את high-risk transfers בקובץ של קבוצת ההקשר כהעברות של 200 או יותר שנשלחו לחשבון חסום (dst.is_blocked = true).

כדי ליצור את ההקשר של תבנית GQL:

  1. מזינים את ההנחיה הבאה במעטפת האג'נטית, ומציינים ש-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;
  2. הנציג ממיר את הקלט שלכם לתבנית GQL עם פרמטרים, שמתאימה לשמות של אנשים באופן כללי. מידע נוסף זמין במאמר סקירה כללית בנושא קבוצות הקשר.

  3. בודקים את תבנית השאילתה ב-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 בלי קשר לאותיות רישיות.

  1. מזינים את ההנחיה הבאה במעטפת האג'נטית, ומציינים ש-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.
    
  2. בודקים את קובץ 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.

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

    כניסה ל-Spanner

  2. בוחרים את המכונה מהרשימה ואז בוחרים את מסד הנתונים ב-Spanner.

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

  4. בחלונית Explorer, לצד קבוצת ההקשר fingraph-assistant, לוחצים על View actions.

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

  6. אופציונלי: עורכים את תיאור קבוצת ההקשרים.

  7. בקטע העלאת קובץ של קבוצת הקשר, לוחצים על עיון ובוחרים את קובץ ה-context_set.json שיצרתם.

  8. לוחצים על Save.

יצירת שאילתות GQL באמצעות QueryData

בקטע הזה, אתם שולחים קריאה ל-API בארכיטקטורת REST של QueryData עם ההקשר של fingraph-assistant כדי לוודא ש-QueryData מתרגם בצורה מדויקת מונחים עסקיים כמו high-risk transfers ופותר את Czech Republic ל-Czech_Republic בשאילתות GQL.

  1. מאתרים את המזהה של קבוצת ההקשרים של fingraph-assistant. הוראות מפורטות זמינות במאמר איך למצוא את המזהה של קבוצת ההקשר.
  2. מגדירים את משתנה הסביבה 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.

  3. שואלים שוב את השאלה לגבי העברות בסיכון גבוה:

    ./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             |
    +------------------------+-----------------+
    
  4. אפשר לשאול שאלה דומה לגבי 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             |
    +------------------------+-----------------+
    
  5. שואלים שוב את השאלה לגבי המדינה:

    ./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 |
    +------------+------------+----------------+
    
  6. שואלים שאלה שמשתמשת בהיבט של החשבון החסום:

    ./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.

  1. מורידים את MCP Toolbox בגרסה 1.4.0 ואילך. ‫MCP Toolbox חושף את ה-API בארכיטקטורת REST של QueryData ככלי MCP שאפליקציות יכולות להתחבר אליו.
  2. מגדירים את Application Default Credentials (ADC):

    gcloud auth application-default login
  3. יוצרים קובץ תצורה של tools.yaml שמגדיר מקור HTTP ל-Conversational Analytics API וכלי HTTP שקורא ל-method‏ QueryData. חשוב לציין את 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.

  4. בטרמינל שבו מפעילים את 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.
  5. מריצים את שרת MCP Toolbox עם הקובץ tools.yaml:

    ./toolbox --config "tools.yaml"
  6. יוצרים אפליקציית ADK שמפעילה את הכלי fingraph_query_data_tool באמצעות MCP Toolbox Python SDK:

    1. יוצרים ספרייה לאפליקציה, למשל fingraph-assistant-app, ועוברים אליה:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. יוצרים סביבה וירטואלית ומתקינים את החבילות הנדרשות:

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. יוצרים סוכן ADK:

      adk create my_agent
    4. בוחרים את המודל gemini-2.5-flash, בוחרים באפשרות Google AI ומזינים את מפתח Gemini API. מידע נוסף זמין במאמר שימוש במפתחות Gemini API.

    5. מחליפים את התוכן של 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]),
      )
      
  7. מפעילים את שרת האינטרנט של ADK בכתובת http://127.0.0.1:8000:

    adk web --port 8000
  8. מזינים שאלה על תרשים עם כמה קפיצות בממשק המשתמש של 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
    
  9. מזינים שאלה שמשתמשת בתבנית high-risk transfers GQL שהוספתם לקבוצת ההקשר:

    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:

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

    כניסה ל-Spanner

  2. בוחרים את המכונה מהרשימה ואז בוחרים את מסד הנתונים ב-Spanner.

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

  4. בחלונית Explorer, לצד fingraph-assistant, לוחצים על View actions.

  5. לוחצים על מחיקת קבוצת ההקשר, מזינים fingraph-assistant בשדה האישור ולוחצים על אישור.

מחיקת מסד הנתונים והמכונה

כדי למחוק את תרשים המאפיינים FinGraph, את מסד הנתונים של Spanner ואת המכונה של Spanner, פועלים לפי השלבים שמפורטים במאמר הגדרה ושליחת שאילתות ב-Spanner Graph: ניקוי.

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