יצירת קבוצות הקשר ל-Firestore עם תאימות ל-MongoDB באמצעות סוכן עם מנוע קבוצת הקשר

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הכנת מסד נתונים ב-Firestore

מוודאים שיש לכם מסד נתונים של Firestore Enterprise Edition עם תאימות ל-MongoDB.

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

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

הכנת הסביבה

אתם יכולים ליצור קובצי קבוצות הקשר מכל סביבת פיתוח מקומית או 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

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

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

הגדרת Application Default Credentials

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

  • שרת MCP של Toolbox: משתמש בפרטי הכניסה כדי להתחבר למסד הנתונים, לאחזר סכימות ולהריץ MQL לאימות.
  • ‫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.

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

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

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

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

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

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

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

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

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

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

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

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for each of the top 5 products?",
    "golden_sql": "db.sales.aggregate([ { $group: { _id: '$product_id', total_net_revenue: { $sum: '$net_revenue' } } }, { $sort: { total_net_revenue: -1 } }, { $limit: 5 } ]);"
  }
]

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

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

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

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

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

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

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

הנציג יבקש מכם לתת שם לניסוי, כדי לארגן את פריטי המידע שנוצרו, ויכול להיות שהוא יבקש מכם לצמצם את ההיקף אם הסכימה של מסד הנתונים גדולה. כדי להעלות את ההקשר באמצעות Firestore 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 --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

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

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

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

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

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

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

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

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

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

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

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

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

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

  • "צור תבנית לשאלה: 'אילו שדות תעופה יש בקליפורניה?' עם השאילתה: db.airports.find({ country: "United States", state: "CA" }, { name: 1, _id: 0 })."
  • "צור פאסט למסנן { departure_time: { $gte: "00:00:00", $lte: "06:00:00" } } עם התווית 'עין אדומה'."
  • "צור חיפוש ערכים עבור airports.iata".

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

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

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

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

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

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

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

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

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