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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הכנת אשכול, מכונה ומסד נתונים של AlloyDB ל-PostgreSQL

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

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

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

מתן הרשאה ל-executesql למכונת AlloyDB ל-PostgreSQL

כדי להעניק את ההרשאה executesql למכונת AlloyDB ל-PostgreSQL ולהגדיר את הגדרת המכונה data_api_access לערך ALLOW_DATA_API, משתמשים בפקודה curl הבאה: 
   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'
מחליפים את מה שכתוב בשדות הבאים:
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור שבו נמצא אשכול AlloyDB.
  • ‫CLUSTER_ID: המזהה של אשכול AlloyDB.
  • ‫INSTANCE_ID: המזהה של מופע AlloyDB.
כדי לבצע את השלבים במדריך הזה, צריך להיכנס אל Google Cloud ולאחר מכן לבצע אימות למסד הנתונים באמצעות אימות IAM.

הכנת הסביבה

אפשר ליצור קבצים של הגדרות הקשר מכל סביבת פיתוח מקומית או 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. מתקינים את הפלאגין של סוכן הנדסת ההקשר, שכולל תהליכי עבודה ליצירת הקשר: 
    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 בסביבת העבודה, שבו הם מוכנים להערכה. אתם יכולים לספק קובץ קיים או לכתוב כמה דוגמאות להערכה בשורה כדי שהסוכן ירחיב אותן.

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

  • "צור מערך נתונים להערכה מהסכימה שלי"
  • "Here's a seed question and SQL. הרחיבו אותו למערך נתונים רחב יותר וודאו שהשאילתות פועלות".

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

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

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

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

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

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

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

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

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

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

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

  • "Evaluate my context against golden.json."
  • "הפעל מחדש את ההערכה באמצעות ההגדרות מהניסוי האחרון שלי".

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

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

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

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

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

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