יצירת קבוצות הקשר באמצעות סוכן הנדסת ההקשר

במסמך הזה מוסבר איך ליצור ולבצע אופטימיזציה של קבוצות ההקשר שעוזרות להשיג דיוק גבוה של QueryData באפליקציות של סוכנים לאינטראקציה עם נתונים ב-Spanner Graph. סוכן ה-context engineering עוזר לכם ליצור, להעריך ולשפר קבוצות הקשר של Graph Query Language ‏(GQL) באמצעות אוטומציה של היצירה והאופטימיזציה שלהן.

מידע נוסף על קבוצות הקשר ו-QueryData ל-Spanner Graph זמין במאמרים סקירה כללית על קבוצות הקשר וסקירה כללית על QueryData.

כדי ליצור אפליקציות לנתוני גרפים ארגוניים, בדרך כלל צריך להגיע לדיוק של כמעט 100% בתרגום משפה טבעית ל-GQL. דפוסי מעבר שגויים בגרף או מסנני קצוות חסרים משפיעים על נוחות השימוש באפליקציה ועל חוויית המשתמש. כדי לקבל תשובות מוסברות, רלוונטיות לעסק וברמת דיוק גבוהה, צריך לבצע הנדסת הקשר – תהליך של יצירה ואופטימיזציה חוזרת של קבוצת ההקשר.

כשמספקים ל-QueryData טירגוט לפי הקשר שמטורגט לסכימה של Spanner Graph ולאפליקציה העסקית, נותנים למערכת את הכללים המדויקים למעבר בגרף ואת הגדרות הדומיין שהיא צריכה כדי לפתור את כוונת המשתמש (Intent) המורכבת.

הדוגמאות במסמך הזה משתמשות בסכימת תרשים המאפיינים FinGraph ובמערך הנתונים לדוגמה (צמתים Person ו-Account שמחוברים באמצעות קצוות Owns ו-Transfers). כדי ליצור את הסכימה של FinGraph ולהוסיף את הנתונים לדוגמה, קראו את המאמר הגדרה ושליחת שאילתות ב-Spanner Graph.

סוכן להנדסת הקשר

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

ברשימה הבאה מופיעות דוגמאות להנחיות בשפה טבעית שאפשר לתת לסוכן, ותיאור של התגובה של הסוכן:

  • הנחיה לדוגמה להצעת הקשר: "קרא את מסמך הבקשה שלי לתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner והצע פריטי הקשר של GQL להוספה". הסוכן מנתח את מסמכי הבקשה של מערך הנתונים שאתם מספקים, ממפה כללים עסקיים לתוויות של צמתים וקצוות ב-FinGraph, ומציע תבניות והיבטים של GQL.
  • דוגמה להנחיה לניתוח פערים כששאלות של משתמשים לא מחזירות את התוצאות הצפויות: "כשמשתמשים שואלים "העברות מחשבון ליום גשום", QueryData מסנן לפי nick_name = 'rainy day account' ולא מחזיר שום דבר. עדכן את ההקשר של תרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner כדי שהשאלה הזו תיענה בצורה נכונה". הנציג בודק את הסכימה, מזהה שהכינוי מאוחסן בתור Rainy Day Fund וממליץ על חיפוש ערך ב-Account.nick_name (או על תבנית או מאפיין אם הבעיה היא בתבנית).
  • הנחיה לדוגמה לעיבוד בכמות גדולה: "הנה שאלות בשפה טבעית ושאילתות GQL לתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner. הופכים אותם לתבניות:

    • Find everyone that Dana transferred money to, with the amounts: GRAPH FinGraph MATCH (:Person {name: 'Dana'})-[:Owns]->(:Account)-[transfer:Transfers]->(:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS recipient, transfer.amount AS amount
    • אילו העברות בסיכון גבוה אלכס ביצע? GRAPH FinGraph MATCH (: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"

    הנציג מעבד את הקלט בכמות גדולה, מחליף ערכים מילוליים ב-? פלייסהולדרים ומעדכן את קובץ קבוצת ההקשר.

החשיבות של מערך הנתונים המאומתים

כדי לבצע אופטימיזציה של ההקשר, קודם צריך ליצור קבוצת נתונים מושלמת שתואמת לקלט בשפה טבעית של האפליקציה. הסוכן יכול לעזור לכם ליצור את קבוצת הנתונים הזו, שמורכבת משאלות של משתמשים בשילוב עם שאילתות ה-GQL הצפויות שלהן. מערך נתונים מושלם מאפשר לכם:

  • קביעת בסיס להשוואה של ביצועי השאילתות משפה טבעית ל-GQL.
  • מאמתים את עדכוני ההקשר מול שאילתות GQL של אמת קרקע (ground truth).
  • מודדים את השיפורים בדיוק לאורך חזרות האופטימיזציה.

תהליך שיטתי של טיפוס על גבעה

בשיטת טיפוס הגבעות השיטתית, הנציג משפר באופן איטרטיבי את קבוצת ההקשרים באמצעות הערכה של קבוצת הנתונים המושלמת, ניתוח פערים ועדכון הקשר ממוקד של GQL כדי להגיע לדיוק של כמעט 100%:

  • יצירה אוטומטית של הקשר בסיסי: יוצרים קבוצת הקשרים ראשונית של GQL, שמבוססת על סכימת תרשים המאפיינים של Spanner Graph ועל פריטי המידע שנוצרו באפליקציה.
  • תהליך עבודה של אופטימיזציה בשיטת טיפוס הרים: הסוכן יכול להעריך את הדיוק של QueryData באמצעות graph_ids שהוגדר, לבצע ניתוח פערים בשאילתות GQL שנכשלו ולהציע באופן אוטומטי שיפורים כדי להגביר את הדיוק.

התרשים הבא מציג את תהליך העבודה של טיפוס שיטתי על גבעות:

תהליך עבודה ליצירת הקשר באופן איטרטיבי.

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

יש להשלים את הדרישות המוקדמות הבאות לפני השימוש בסוכן עם מנוע תלוי הקשר:

הפעלת השירותים הנדרשים

מפעילים את השירותים הבאים בפרויקט:

הכנת מכונה של 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 ולהוסיף את נתוני התרשים לדוגמה שמופיעים במדריך הזה, פועלים לפי השלבים שמפורטים במאמר הגדרה ושליחת שאילתות של Spanner Graph.

הכנת הסביבה

אתם יכולים ליצור קובצי קבוצות הקשר מכל סביבת פיתוח מקומית או IDE. כדי להכין את הסביבה, פועלים לפי השלבים הבאים:

  • מתקינים את סוכן מנוע תלוי הקשר.
  • מגדירים את החיבור של מסד הנתונים ל-Spanner Graph.

התקנת הסוכן להנדסת הקשר

הסוכן עם מנוע תלוי הקשר מפעיל שרת Model Context Protocol‏ (MCP) שדורש את uv כדי לנהל את חבילות ה-Python הבסיסיות.

  1. מתקינים את uv לפי ההוראות במאמר התקנת uv.
  2. מוודאים ש-uv מותקן ושאפשר לגשת אליו משורת הפקודה:

    uv --version

כדי להכין את הסביבה, מתקינים את סוכן הנדסת ההקשר במעטפת האג'נטית שנבחרה, כמו Antigravity CLI,‏ Claude Code או Gemini CLI.

בהתאם למעטפת האג'נטית שבחרתם, פועלים לפי שלבי ההתקנה המתאימים:

Antigravity CLI

כדי להתקין את סוכן הנדסת ההקשר ב-Antigravity CLI, פועלים לפי השלבים הבאים:

  1. מתקינים את Antigravity CLI. איך מתחילים לעבוד עם Antigravity CLI
  2. מתקינים את הפלאגין של סוכן הנדסת ההקשר, שכולל תהליכי עבודה ליצירת הקשר:
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. מפעילים את Antigravity CLI:
    agy
  4. מעדכנים את הפלאגין:
    agy plugin uninstall google-cloud-db-context-engineering
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

Claude Code

כדי להתקין את סוכן הנדסת ההקשר ב-Claude Code, פועלים לפי השלבים הבאים:

  1. מוסיפים את מאגר הפלאגינים:
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. מתקינים את הפלאגין:
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. טוענים מחדש את הפלאגינים כדי להפעיל את השינויים:
    /reload-plugins
  4. מעדכנים את הפלאגין:
    /plugin update db-context-engineering@db-context-enrichment-marketplace

‫Gemini CLI (יצא משימוש)

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

  1. מתקינים את Gemini CLI. איך מתחילים לעבוד עם Gemini CLI
  2. מתקינים את התוסף:
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. מעדכנים את התוסף:
    gemini extensions update mcp-db-context-enrichment

הגדרת החיבור למסד הנתונים

הנציג צריך חיבור למסד נתונים כדי לאחזר סכימות של גרף מאפיינים (spanner-list-graphs), לבדוק טבלאות בסיסיות (spanner-list-tables) ולאמת את התחביר של שאילתות GQL ו-SQL שנוצרו (spanner-execute-sql). כדי לאפשר לנציג לקיים אינטראקציה עם גרף המאפיינים במסד הנתונים של Spanner, צריך להגדיר את פרטי הכניסה לאימות ואת החיבור למסד הנתונים.

הגדרת Application Default Credentials

מגדירים את Application Default Credentials (ADC) כדי לספק פרטי כניסה של משתמשים לצורך גישה למשאבי Google Cloud מסוכן הנדסת ההקשר:

  • שרת MCP של Toolbox: משתמש בפרטי כניסה כדי להתחבר למסד הנתונים של Spanner, לאחזר סכימות של תרשימי מאפיינים ולהריץ שאילתות GQL לצורך אימות.
  • ‫Evalbench: משתמש בפרטי כניסה כדי לשלוח קריאה ל-API בארכיטקטורת REST של QueryData באמצעות graph_ids, ולהריץ את מדרג ה-LLM ב-Vertex AI במהלך ההערכה.

מריצים את הפקודה הבאה במסוף כדי לבצע אימות:

gcloud auth application-default login

הגדרת קובץ החיבור למסד הנתונים

הסוכן צריך חיבור למסד נתונים כדי ליצור הקשר. MCP Toolbox תומך בחיבור הזה ומגדיר אותו בקובץ תצורה (autoctx/tools.yaml), יחד עם כלי למעקב אחרי מצבים (autoctx/state.md) שמתעד את השמות של תרשימי המאפיינים הפעילים (כמו FinGraph).

  1. מפעילים את סביבת הסוכן.
  2. מבקשים מהסוכן להגדיר את החיבור למסד הנתונים של Spanner ומציינים את שם תרשים המאפיינים. לדוגמה, מזינים את ההנחיה הבאה:

    Help me set up the database connection for my Spanner database with the FinGraph property graph.
    

    פועלים לפי ההוראות של הנציג כדי לספק את מזהה הפרויקט, מזהה המכונה של Spanner, מזהה מסד הנתונים ושם תרשים המאפיינים (FinGraph). הנציג יוצר את autoctx/tools.yaml (עם הכלים spanner-list-graphs,‏ spanner-list-tables ו-spanner-execute-sql) ואת autoctx/state.md.

  3. פותחים את autoctx/state.md ומוודאים שבקטע ## Active Database מופיע תרשים הנכס בפורמט הבא:

    - **Graph Ids**: ["FinGraph"]
    

    תהליך העבודה של ההערכה קורא את מזהי הגרפים של הנכס רק מהשורה הזו. אם השורה חסרה, ריקה ([]) או לא בפורמט הזה, ההערכה קוראת ל-QueryData בלי graph_ids, ו-QueryData יוצר SQL יחסי במקום GQL.

  4. כדי להחיל את ההגדרות האישיות החדשות של tools.yaml, צריך לטעון מחדש את החיבור:

    • ב-Antigravity CLI, מריצים את /mcp ובוחרים באפשרות toolbox כדי להפעיל מחדש.
    • ב-Gemini CLI, מריצים את הפקודה /mcp reload.
    • ב-Claude Code, מריצים את /mcp, בוחרים באפשרות toolbox ואז באפשרות Reconnect.

מידע נוסף על הגדרה ידנית של קובץ התצורה של מסד הנתונים זמין במאמר הגדרת MCP Toolbox.

יצירה ואופטימיזציה של הקשר

סוכן הנדסת ההקשר מספק קבוצה של מיומנויות סוכן וכלים של MCP כדי ליצור קבוצת הקשר בסיסית של GQL, למדוד את היעילות בהשוואה לקבוצת נתונים אידיאלית של GQL וליישם שיפורים באופן איטרטיבי. אתם יכולים להתחיל בכל שלב בתהליך העבודה:

  • אם כבר הגדרתם הקשר, אתם יכולים להמשיך ישירות להערכה.
  • אם יש לכם שאילתות GQL שנכשלו ואתם רוצים לתקן אותן, אתם יכולים להמשיך ישירות לניתוח הפערים.

בכל שלב, הזכירו לנציג שהיעד הוא תרשים מאפיינים במסד הנתונים של Spanner, ותנו שם לתרשים (למשל FinGraph), כדי שהוא יישאר בתהליך העבודה הספציפי ל-GQL.

יצירה והרחבה של מערכי נתונים להערכה

כדי לשפר את הביצועים, קודם צריך למדוד אותם. קבוצת נתונים מושלמת היא קבוצה של שאלות של משתמשים שמשויכות לשאילתות GQL הצפויות שלהן. בלעדיה, להנדסת הקשר אין אימות שיטתי. איתה, כל שינוי בהקשר הוא שיפור מדיד שאפשר לאמת מול אמת קרקע (ground truth).

יצירה ידנית של קבוצת נתונים מייצגת של האמת הבסיסית דורשת זמן רב, וקבוצות נתונים קטנות עלולות לפספס וריאציות בניסוח של המשתמשים. כדי לפתור את הבעיה, הנציג:

  • יצירת שאלות מועמדות בשפה טבעית וזוגות של שאילתות GQL על סמך סכימת גרף המאפיינים.
  • הרחבת קבוצת נתונים ראשונית באמצעות וריאציות של מסננים, מילים נרדפות וניסוחים מחדש של נתיבים עם כמה דילוגים.
  • מריצים את שאילתות ה-GQL שנוצרו במסד הנתונים של Spanner כדי לוודא שכל שאילתה פועלת בצורה חלקה ומחזירה תוצאות תקינות.

בהתאם לשאילתות של FinGraph בסקירה הכללית של שאילתות Spanner Graph, קבוצת הנתונים המושלמת (autoctx/golden.json) היא קובץ JSON שמכיל זוגות של שאלות בשפה טבעית ו-GQL, כמו:

[
  {
    "id": "fingraph_001",
    "database": "example-db",
    "nlq": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
    "golden_sql": "GRAPH FinGraph MATCH (from_person:Person {name: 'Dana'})-[:Owns]->(from_account:Account)-[transfer:Transfers]->(to_account:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS to_account_owner, to_account.id AS to_account_id, transfer.amount AS amount;"
  },
  {
    "id": "fingraph_002",
    "database": "example-db",
    "nlq": "Find all money transfers involving a blocked account.",
    "golden_sql": "GRAPH FinGraph MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) RETURN transfer.order_number, transfer.amount;"
  },
  {
    "id": "fingraph_003",
    "database": "example-db",
    "nlq": "Find destination accounts that are 1 to 3 transfers away from account 7, and show the path length.",
    "golden_sql": "GRAPH FinGraph MATCH (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account) WHERE src != dst RETURN dst.id AS dst_account_id, ARRAY_LENGTH(e) AS path_length;"
  },
  {
    "id": "fingraph_004",
    "database": "example-db",
    "nlq": "Find all high-risk transfers initiated by Alex.",
    "golden_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;"
  }
]

הצמדים שאושרו מאכלסים את הקובץ autoctx/golden.json בסביבת העבודה, ומוכנים להערכה. בכל רשומה, הערך של database צריך להתאים למזהה של מסד הנתונים ב-Spanner (למשל example-db).

אתם יכולים להשתמש בהנחיות לדוגמה הבאות כדי להנחות את הנציג, ולציין ש-FinGraph הוא תרשים מאפיינים במסד הנתונים שלכם ב-Spanner:

  • "צור קבוצת נתונים להערכת GQL מתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner"
  • "הנה שאלה ראשונית ושאילתת GQL לתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner. הרחיבי אותה למערך נתונים רחב יותר להערכת GQL וודאי שהשאילתות פועלות".

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

כדי להימנע מיצירת הקשר מאפס, אתם יכולים לאפשר לסוכן להפיק קבוצת הקשרים ראשונית של GQL‏ (bootstrap_context.json) מסכימת תרשים המאפיינים ומפריטי המידע של האפליקציה, כמו כללים עסקיים, שאילתות GQL לדוגמה או מסמכי עיצוב. מכיוון שמערך הנתונים הוא תרשים מאפיינים במסד הנתונים של Spanner, הסוכן מעדיף תבניות GQL‏ (GRAPH FinGraph MATCH ...) על פני SQL joins יחסיים כשהוא יוצר תבניות והיבטים.

אתם יכולים להשתמש בהנחיות לדוגמה הבאות כדי להנחות את הסוכן:

  • "צור קבוצת הקשר בסיסית של GQL מתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner".
  • "צור הקשר ראשוני של GQL לתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner, באמצעות סכימת תרשים המאפיינים והכללים העסקיים בקובץ requirements.md".

הסוכן מבקש מכם לתת שם לניסוי (לדוגמה, fingraph_tuning), כדי לארגן את פריטי המידע שנוצרו ב-autoctx/experiments/fingraph_tuning/. אחרי שהסוכן יוצר את bootstrap_context.json, פועלים לפי ההוראות במאמר ניהול קבוצות הקשר ב-Spanner Studio כדי להעלות את קובץ קבוצת ההקשר.

הערכת היעילות של ההקשר

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

ב-Spanner Graph, ההערכה קוראת ישירות ל-API בארכיטקטורת REST של QueryData, כך שכל בקשה יכולה לכלול את graph_ids.

כשהמשתנה autoctx/state.md מכיל את הערך - **Graph Ids**: ["FinGraph"], הסוכן יוצר קובץ תצורה של מודל Evalbench‏ (autoctx/experiments/fingraph_tuning/eval_configs/model_config.yaml) שמשתמש ב-API בארכיטקטורת REST וכולל את graph_ids ב-spanner_reference.database_reference, בדומה לדוגמה הבאה:

generator: query_data_api
project_id: PROJECT_ID
location: global
use_rest_api: true
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: projects/PROJECT_ID/locations/REGION/contextSets/CONTEXT_SET_ID

לפני שמריצים הערכה, פותחים את model_config.yaml ומוודאים שהערך של use_rest_api הוא true ושהערך של graph_ids הוא תרשים המאפיינים שלכם.

הרצת הערכה מספקת את הנתונים הבאים:

  • מדדים כמותיים, כמו תוצאות של הצלחה וכישלון וציונים מצטברים, כדי לעקוב אחרי ההתקדמות באיטרציות של ההקשר של GQL.
  • סיכום שיחה מוטבע ודוחות CSV מפורטים שנכתבו בספרייה eval_reports/ בתיקיית הניסוי.

כדי להתחיל הערכה, צריך לציין את הנתיב של קבוצת הנתונים להשוואה (autoctx/golden.json) ואת המזהה של קבוצת ההקשר. איך מוצאים את מזהה קבוצת ההקשר

אתם יכולים להשתמש בהנחיות לדוגמה הבאות כדי להנחות את הסוכן:

  • "Evaluate my context for the FinGraph property graph in my Spanner database against autoctx/golden.json.‎ שולחים קריאה ל-QueryData API בארכיטקטורת REST עם graph_ids שמוגדר ל-FinGraph."
  • "Re-run the evaluation for the FinGraph property graph in my Spanner database using the configuration from my last experiment."

כדי להריץ מחדש הגדרת הערכה שנוצרה בעבר ישירות מהשורש של סביבת העבודה, מריצים את הפקודה הבאה:

uvx google-evalbench --experiment_config=autoctx/experiments/fingraph_tuning/eval_configs/run_config.yaml

לפרטים על סכימת ההגדרות של ההערכה ועל התאמה אישית של הרצות הערכה, קראו את המסמכים של Evalbench.

לבצע ניתוח פערים ולהציע שיפורים

כדי לפתור כשלים בשאילתות GQL, צריך לזהות את שורש הבעיה, למשל:

  • כיווני קצוות הפוכים (-[:Owns]-> לעומת <-[:Owns]-)
  • חסרים גבולות נתיב מכומתים (->{1, 3})
  • הגדרות עסק לא ממופות (כמו high-risk transfers)
  • ערכי נכסים לא פתורים

תחביר השאילתות מפורט במאמר סקירה כללית של שאילתות ב-Spanner Graph ובחומר העזר בנושא GQL.

הסוכן הופך את תהליך הניתוח והתיקון של תרשים המאפיינים במסד הנתונים של Spanner לאוטומטי:

  • ניתוח פערים: הנציג קורא את תוצאות ההערכה ואת ההקשר שהגדרתם כדי לקבץ כשלים דומים ב-GQL ולהמליץ על תוספות ממוקדות, כמו תבניות GQL, מאפיינים או חיפושי ערכים של GRAPH_TABLE במאפייני צומת וקצה.
  • הצעות לתיקונים: הנציג מציע עריכות קונקרטיות של הקשר GQL ובודק את ה-GQL שנוצר מול מסד הנתונים של Spanner באמצעות spanner-execute-sql כדי לאמת את הפתרון.
  • שמירה על קובץ הבסיס: הנציג כותב את השיפורים בקובץ JSON חדש (improved_context_v1.json) לצד ההקשר של קובץ הבסיס, ושומר על הקבצים המקוריים.

אתם יכולים להשתמש בהנחיות לדוגמה הבאות כדי להורות לסוכן, ולציין שמערך הנתונים הוא תרשים מאפיינים במסד הנתונים של Spanner, כדי להפעיל את תהליך העבודה של הנדסת ההקשר הספציפי ל-GQL:

  • "Run gap analysis on my last evaluation for the FinGraph property graph in my Spanner database and propose GQL context fixes."
  • "בצע אופטימיזציה של קבוצת ההקשר הזו לתרשים המאפיינים של FinGraph במסד הנתונים שלי ב-Spanner בהשוואה ל-autoctx/golden.json".

כדי להתכונן לאיטרציה הבאה, מעלים את קובץ קבוצת ההקשר המשופר (improved_context_v1.json) לקבוצת ההקשר המטורגטת ב-Spanner Studio לפי ההוראות במאמר עריכה של קבוצת הקשר.

יצירת פריטי הקשר ספציפיים לפי דרישה

אם אתם כבר יודעים מהו פריט ההקשר שאתם צריכים (למשל תבנית GQL למעבר ספציפי בגרף, פאסט למסנן קצוות חוזר או חיפוש ערך GRAPH_TABLE במאפיין של צומת או קצה), הנציג יכול ליצור את אובייקט ה-JSON עם הפרמטרים המתאימים לפי דרישה בלי להריץ הערכה מלאה.

אתם יכולים להשתמש בהנחיות לדוגמה הבאות כדי להורות לסוכן לגבי תרשים המאפיינים במסד הנתונים שלכם ב-Spanner:

  • "For the FinGraph property graph in my Spanner database, create a template for: 'Find all high-risk transfers initiated by Alex' with the 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;."
  • "For the FinGraph property graph in my Spanner database, create a facet for the GQL clause MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) labeled 'transfers involving a blocked account'."
  • "For the FinGraph property graph in my Spanner database, create a GRAPH_TABLE value search on the nick_name property of Account nodes with concept type 'Account nickname' that matches nicknames case-insensitively."

הסבר על בחירת סוג ההקשר

בחירה של סוג ההקשר המתאים (תבנית GQL, מאפיין או חיפוש ערך) עוזרת למנוע עומס בהקשר ורגרסיות של שאילתות. אתם יכולים לבקש מהסוכן להמליץ על סוג ההקשר המתאים על סמך מבני השאילתות שלכם:

  • "בתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner, אני ממשיך לסנן העברות שכוללות חשבונות חסומים עם MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) בהרבה שאילתות GQL. מה הדרך הכי טובה לצלם את זה?"
  • "המשתמשים מתייחסים לחשבונות בתרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner באמצעות כינויים כמו 'קרן חופשה' או 'קרן ליום גשום'. איזה סוג של חיפוש ערך GRAPH_TABLE צריך להגדיר ב-Account.nick_name?"
  • "מה ההבדל בין תבנית GQL לבין מאפיין בקבוצת הקשרים של Spanner Graph, ומתי כדאי להשתמש בכל אחד מהם?"

החלת פעולות בכמות גדולה על קבוצת הקשר

הסוכן תומך בעדכון מספר פריטים בו-זמנית כדי לנהל קבוצות גדולות של הקשרים ב-GQL באופן עקבי, למשל כשתווית של תרשים מאפיינים מתעדכנת או כשסף עסקי משתנה בכמה תבניות והיבטים:

  • "Read golden.json for the FinGraph property graph in my Spanner database and turn all the question-GQL pairs into templates."
  • "ב-context_set.json של תרשים המאפיינים FinGraph במסד הנתונים שלי ב-Spanner, החלף את t.amount >= 200 ב-t.amount >= 300 בכל פריט GQL שמפנה ל"העברות בסיכון גבוה". אל תגעו בפריטים שלא קשורים."

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