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

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

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

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

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

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

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

  • הנחיה לדוגמה לניתוח כשלים: "עדכן את ההקשר כדי שנוכל לזהות נכון את שדה התעופה בשאילתות כמו 'טיסות לדיסני וורלד'". הסוכן מנתח את הכישלון, מסיק מסקנות לגבי הפער וממליץ להוסיף פריט הקשר מתאים, כמו שאילתת חיפוש של ערך.
  • פרומפט לדוגמה להצעות תלויות הקשר: "קרא את קוד האפליקציה שלי והצע הקשר להוספה" הסוכן מנתח את הקוד, מסיק מסקנות לגבי הדומיין של האפליקציה ומציע פריטי הקשר רלוונטיים.
  • הנחיה לדוגמה לעיבוד בכמות גדולה: "הנה 10 דוגמאות לשאלות ולשאילתות SQL. הפכו אותן לתבניות." הסוכן מעבד את הקלט בכמות גדולה ומעדכן את קבוצת ההקשר.

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

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

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

תהליך שיטתי של חיפוש מקסימום מקומי

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

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

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

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

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

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

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

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

הכנת מכונה של Spanner


כדי לבצע את המדריך הזה, צריך להיות מסד נתונים במכונה של Spanner. מידע נוסף זמין במאמר יצירת מסד נתונים.

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

  • מוסיפים לחשבון משתמש או לחשבון שירות ב-IAM את האשכול. מידע נוסף זמין במאמר החלת תפקידי IAM.
  • מקצים למשתמש ב-IAM את התפקידים spanner.databaseReader ו-geminidataanalytics.queryDataUser ברמת הפרויקט. מידע נוסף זמין במאמר הוספת קישור למדיניות IAM בפרויקט.
  • כדי ליצור, להעלות ולנהל קבוצות של הקשרים, צריך להקצות למשתמש ה-IAM את התפקיד "עריכה של Dataplex Catalog"‏ (roles/dataplex.catalogEditor) או "אדמין של Dataplex Catalog"‏ (roles/dataplex.catalogAdmin) ברמת הפרויקט. מידע נוסף זמין במאמר הרשאות לקבוצות הקשר.
  • נותנים תפקידים והרשאות למשתמש IAM ברמת הפרויקט עבור מסדי הנתונים הנדרשים.

הכנת הסביבה

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

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

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

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

  1. מתקינים את uv לפי ההוראות במאמר התקנת uv.

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

    uv --version

כדי להכין את הסביבה, מתקינים את סוכן הנדסת ההקשר ב-agent harness שבחרתם, כמו 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

כדי לעדכן את הפלאגין לגרסה העדכנית:

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

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

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

הגדרת Application Default Credentials

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

  • שרת MCP של Toolbox: משתמש בפרטי הכניסה כדי להתחבר למסד הנתונים, לאחזר סכימות ולהריץ SQL לאימות.
  • ‫Evalbench: משתמש בפרטי כניסה כדי להפעיל את QueryData לצורך הערכה.

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

gcloud auth application-default login

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

הסוכן צריך חיבור למסד נתונים כדי ליצור הקשר, ו-MCP Toolbox תומך בזה ומגדיר את החיבור בקובץ תצורה.

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

  1. מפעילים את סביבת הסוכן.

  2. מבקשים מהסוכן לעזור בהגדרת החיבור למסד הנתונים – לדוגמה, מזינים את ההנחיה "עזרה בהגדרת החיבור למסד הנתונים". פועלים לפי ההוראות של הנציג כדי ליצור את קובץ התצורה בספריית העבודה הנוכחית בתור autoctx/tools.yaml.

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

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

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

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

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

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

כל יכולת מתארת את הפעולות, תרחישי השימוש ופקודות ההפעלה של הנציג.

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

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

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

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

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

אופציונלי: אתם יכולים לאפשר לסוכן להריץ את ה-SQL שנוצר מול מסד הנתונים שלכם. האימות הזה מאשר שהשאילתות פועלות בהצלחה לפני שמוסיפים אותן למערך הנתונים.

מערך הנתונים הוא קובץ JSON שמכיל זוגות של שאלות ו-SQL:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

הזוגות שאושרו יופיעו בקובץ autoctx/golden.json בסביבת העבודה, ויהיו מוכנים להערכה. אתם יכולים לספק קובץ קיים או לכתוב כמה דוגמאות להערכה כדי שהנציג ירחיב אותן.

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

  • "Generate an evaluation dataset from my schema."
  • "הנה שאילתת SQL ושאלה ראשונית. אפשר להרחיב אותו למערך נתונים רחב יותר ולאמת את השאילתות שמופעלות'.

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

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

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

  • "צור קבוצת הקשר מהסכימה שלי".
  • "תייצר הקשר ראשוני באמצעות הסכימות האלה והכללים העסקיים ב-requirements.md".

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

הערכת האפקטיביות של ההקשר

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

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

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

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

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

  • "תבדוק את ההקשר שלי בהשוואה לgolden.json".
  • "Re-run the evaluation using the config from my last experiment."

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

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

במסמכי התיעוד של Evalbench מוסבר איך להגדיר את סכימת ההערכה ואיך להתאים אישית את הרצות ההערכה.

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

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

הסוכן מבצע את הלולאה הזו של ניתוח ותיקון באופן אוטומטי:

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

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

  • "Run gap analysis on my last evaluation and propose fixes" (תבצע ניתוח פערים בהערכה האחרונה שלי ותציע תיקונים).
  • "Optimize this context set against golden.json"

כדי להתכונן לאיטרציה הבאה, מעלים את ההקשר המשופר לקבוצת ההקשרים הרלוונטית באמצעות Data Agents Studio, לפי ההוראות.

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

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

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

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

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

  • "צור תבנית לשאלה: 'אילו שדות תעופה נמצאים בקליפורניה?' באמצעות SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'".
  • "צור פן לסינון departure_time BETWEEN '00:00:00' AND '06:00:00' עם התווית 'עיניים אדומות'".
  • "צור חיפוש ערך עבור airports.iata".

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

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

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

  • "אני ממשיך לכתוב את המסנן departure_time BETWEEN '00:00:00' AND '06:00:00' בשאילתות רבות. מה הדרך הכי טובה לצלם את זה?"
  • "המשתמשים מתארים את סטטוס הטיסה בטקסט חופשי ואני רוצה להתאים אותם ל-flights.status. איזה סוג של חיפוש ערך כדאי להגדיר?"
  • "מה ההבדל בין תבנית לבין פן, ומתי כדאי להשתמש בכל אחת מהן?"

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

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

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

  • "Read golden.txt and turn all the pairs into templates."
  • "בעמודה context_set.json, החלף את airline = 'UA' ב-airline = 'United Airlines' בכל פריט שמופיעה בו המילה 'United'. אל תתעסקו עם פריטים שלא קשורים לבעיה".

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