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

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

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

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

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

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

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

  • הנחיה לדוגמה לניתוח כשלים: "עדכן את ההקשר כדי שנוכל לזהות נכון את שדה התעופה בשאילתות כמו 'טיסות לדיסני וורלד'". הסוכן מנתח את הכישלון, מסיק מסקנות לגבי הפער וממליץ להוסיף פריט הקשר מתאים, כמו שאילתת חיפוש ערכים.
  • פרומפט לדוגמה להצעות תלויות הקשר: "Read my app code and suggest some context to add." הסוכן מנתח את הקוד, מסיק מסקנות לגבי הדומיין של האפליקציה ומציע אילו פריטי הקשר יהיו רלוונטיים.
  • הנחיה לדוגמה לעיבוד בכמות גדולה: "הנה 10 דוגמאות לשאלות ולשאילתות SQL. הופכים אותם לתבניות". הסוכן מעבד את הקלט בכמות גדולה ומעדכן את קבוצת ההקשר.

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

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

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

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

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

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

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

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

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

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

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

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

הכנת מכונה של Cloud SQL

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

מתן הרשאה ל-executesql במכונה של Cloud SQL

כדי להעניק את ההרשאה executesql למכונת Cloud SQL ולהפעיל את Cloud SQL Data API, מריצים את הפקודה הבאה: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
מחליפים את מה שכתוב בשדות הבאים:
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫INSTANCE_ID: המזהה של מכונת Cloud SQL.
כדי לבצע את השלבים במדריך הזה, נכנסים אל Google Cloud ומאמתים את מסד הנתונים באמצעות אימות IAM.

הכנת מסד הנתונים לחיפושים של ערכים

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

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

    1. מפעילים את הדגל cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. מפעילים את הדגל enable-google-ml-integration כדי לאפשר למכונה של Cloud SQL ל-MySQL להשתלב עם Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. יצירת עמודה וקטורית לאחסון הטמעות של ערים

      ALTER TABLE `airports`
ADD COLUMN `city_embedding` VECTOR(768);

    4. יצירה ואחסון של הטמעות וקטוריות לשמות של ערים

      UPDATE `airports`
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`)
WHERE `city` IS NOT NULL;

  2. כדי לאפשר למכונת Cloud SQL ל-MySQL לבצע חיפושים של ערכי טריגרמה, צריך לבצע את השלבים הבאים:

    1. מפעילים את הדגל ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. יוצרים אינדקס FULLTEXT להתאמת טריגרמות בשם שדה התעופה:

      CREATE FULLTEXT INDEX `idx_ngram_airports_name`
ON `airports`(`name`) 
WITH PARSER ngram;

הכנת הסביבה

אתם יכולים ליצור קובצי קבוצות הקשר מכל סביבת פיתוח מקומית או סביבת פיתוח משולבת (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 של ערכת הכלים: משתמש בפרטי הכניסה כדי להתחבר למסד הנתונים, לאחזר סכימות ולהריץ SQL לצורך אימות.
  • ‫Evalbench: משתמש בפרטי כניסה כדי להפעיל את QueryData לצורך הערכה.

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

gcloud auth application-default login

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

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

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

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

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

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

    • ב-CLI של Antigravity, מריצים את הפקודה /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".

הנציג יבקש מכם לתת שם לניסוי, כדי לארגן את פריטי המידע שנוצרו, ויכול להיות שהוא יבקש מכם לצמצם את ההיקף אם הסכימה של מסד הנתונים גדולה. כדי להעלות את ההקשר באמצעות Cloud SQL 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'. אל תגעו בפריטים שלא קשורים."

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