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

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

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

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

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

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

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

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

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

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

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

תהליך שיטתי של טיפוס הרים

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

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

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

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

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

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

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

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

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

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

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

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

הכנת הסביבה

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

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

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

הסוכן עם מנוע תלוי הקשר מפעיל שרת 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. מתקינים את הפלאגין של סוכן הנדסת ההקשר, שכולל תהליכי עבודה ליצירת הקשר. מחליפים את VERSION בגרסת ההפצה הנדרשת: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. מפעילים את Antigravity CLI: 
    agy

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

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION

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 google-cloud-db-context-engineering

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

הנציג צריך חיבור למסד נתונים כדי לאחזר סכימות, וגם יכולת לאמת את התחביר של ההקשר של ה-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. מבקשים מהנציג לעזור בהגדרת החיבור למסד הנתונים. לדוגמה, מזינים את ההנחיה "help me set up the database connection". פועלים לפי ההוראות של הנציג כדי ליצור את קובץ התצורה בספריית העבודה הנוכחית בתור autoctx/tools.yaml.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[
  {
    "id": "eval_001",
    "database": "<database_name>",
    "nlq": "How many hotels are in London?",
    "golden_sql": "SELECT COUNT(*) FROM `hotels` WHERE CAST(cf['location'] AS STRING) = 'London'",
    "tags": ["complexity: low", "topic: location_lookup", "source: generated:schema"]
  }
]

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

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

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

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

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

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

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

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

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

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

כשמריצים הערכה, מקבלים את הפרטים הבאים:

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

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

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

  • "Evaluate my context against golden.json"
  • "Re-run the evaluation using the config from my last experiment."

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

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

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

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

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

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

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

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

  • "Run gap analysis on my last evaluation and propose fixes."
  • "בצע אופטימיזציה של קבוצת ההקשרים הזו בהשוואה ל-golden.json".

כדי להתכונן לאיטרציה הבאה, מעלים את ההקשר המשופר לקבוצת ההקשרים המטורגטים באמצעות Bigtable 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. איזה סוג של חיפוש ערך כדאי להגדיר?"
  • "מה ההבדל בין תבנית לבין פאסט, ומתי כדאי להשתמש בכל אחד מהם?"

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

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

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

  • "תקרא את golden.txt ותהפוך את כל הצמדים לתבניות".
  • "בעמודה context_set.json, החלף את airline = 'UA' ב-airline = 'United Airlines' בכל פריט שמתייחס ל-'United'. אל תגעו בפריטים שלא קשורים."

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