‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

איך יוצרים קבוצות הקשר ומבצעים בהן אופטימיזציה באמצעות סוכן עם מנוע קבוצת הקשר

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

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

כשמספקים ל-QueryData הקשר שמותאם לאפליקציה העסקית, נותנים למערכת את הכללים העסקיים המדויקים שהיא צריכה כדי להבין את כוונת המשתמש (Intent) בצורה מדויקת ולספק שאילתות באיכות של כמעט 100%. כשאתם עובדים ב-CLI או ב-IDE, הסוכן להנדסת הקשר מעלה באופן אוטומטי את קבוצות ההקשרים אל Google Cloud , ושומר קבצים מקומיים בסביבת העבודה שלכם לצורך ניהול גרסאות.

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

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

אתם משוחחים עם הנציג בשפה טבעית כדי להפעיל את תהליך העבודה של האופטימיזציה. מתחילים עם הנחיה כמו "Optimize the context set against my application requirements".

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

לפני שמשתמשים בסוכן עם מנוע תלוי הקשר, צריך להשלים את הדרישות המוקדמות שמפורטות בקטעים הבאים. אתם יכולים ליצור ולאחסן קבוצות הקשר באזורים us-central1,‏ us-east1,‏ europe-west4 ו-asia-southeast1, גם אם המכונה של מסד הנתונים נמצאת באזור אחר.

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

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

הכנת מסד הנתונים

מכינים את המכונה ומסד הנתונים של Spanner:

יוצרים מכונה של Spanner או משתמשים במכונה קיימת.
יוצרים מסד נתונים במכונה של Spanner או משתמשים במסד נתונים קיים.

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

כדי לקבל את ההרשאות שנדרשות לשימוש בסוכן להנדסת הקשר ולניהול קבוצות הקשר, צריך להגדיר את התפקידים הבאים בניהול זהויות והרשאות גישה (IAM) ואת ההרשאות הבאות למסד הנתונים:

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

הכנת הסביבה

אתם יכולים ליצור ולשפר קבוצות הקשר מסביבת הפיתוח המקומית או מ-IDE.

התקנת uv

כדי לנהל את חבילות ה-Python הבסיסיות, הסוכן עם מנוע תלוי הקשר צריך את uv:

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

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

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

Antigravity CLI

מתקינים את Antigravity CLI. איך מתחילים לעבוד עם Antigravity CLI

מתקינים את הפלאגין של סוכן הנדסת ההקשר:

agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

מפעילים את Antigravity CLI:
```
agy
```

כדי לעדכן את הפלאגין מאוחר יותר, מריצים את agy plugin uninstall db-context-engineering ואז את agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

Claude Code

מוסיפים את מאגר הפלאגינים:

/plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git

מתקינים את הפלאגין:

/plugin install db-context-engineering@db-context-enrichment-marketplace

טוענים מחדש את הפלאגינים כדי להפעיל את השינויים:
```
/reload-plugins
```

כדי לעדכן את הפלאגין מאוחר יותר, מריצים את /plugin update db-context-engineering@db-context-enrichment-marketplace.

‫Gemini CLI (יצא משימוש)

מתקינים את Gemini CLI. איך מתחילים לעבוד עם Gemini CLI

מתקינים את התוסף:

gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

כדי לעדכן את התוסף מאוחר יותר, מריצים את gemini extensions update google-cloud-db-context-engineering.

אימות באמצעות Google Cloud

מגדירים את Application Default Credentials‏ (ADC) כדי לאמת את סביבת הפיתוח:
```
gcloud auth application-default login
```
כדי שהכלים של Model Context Protocol‏ (MCP) יוכלו להשתמש בפרויקט ב- Google Cloud , צריך להגדיר את הפרויקט לחיוב על מכסות בפרטי הכניסה:
```
gcloud auth application-default set-quota-project PROJECT_ID
```
מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

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

מפעילים את סביבת הסוכן ומבקשים מהסוכן ליצור את החיבור למסד הנתונים (לדוגמה, "Help me set up the database connection"). הסוכן ידריך אתכם בתהליך היצירה של קובץ התצורה של .context-engineering/tools.yaml, כדי שהוא יוכל לקרוא סכימות ולאמת SQL. (לפני שנוצר .context-engineering/tools.yaml, צפויה אזהרה ראשונית לגבי חיבור לשרת MCP של toolbox בזמן ההפעלה).
טוענים מחדש את החיבור לשרת ה-MCP כדי להחיל את ההגדרה של .context-engineering/tools.yaml:
- ‫Antigravity CLI: מריצים את /mcp ובוחרים באפשרות toolbox (או db-context-engineering_toolbox) כדי להפעיל מחדש.
- ‫Claude Code: מריצים את /mcp, בוחרים באפשרות toolbox ואז באפשרות Reconnect.
- ‫Gemini CLI: מריצים את הפקודה /mcp refresh (או /mcp reload).

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

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

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

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

אחרי שהנציג יוצר ומאמת את ההקשר הבסיסי, הוא מעלה אותו ישירות אל Google Cloud ומחזיר את שם המשאב של קבוצת ההקשרים.

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

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

במהלך יצירת מערך הנתונים, הנציג יוצר שתי קבוצות נפרדות:

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

אופטימיזציה של הדיוק באמצעות אלגוריתם טיפוס-הרים (hill-climbing)

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

הערכה: הסוכן בודק את קבוצת ההקשר הנוכחית מול נקודת ההשוואה לאימון באמצעות QueryData API ומדרג את הדיוק.
אבחון פערים: הנציג מנתח כשלים בשאילתות, מזהה את שורש הבעיה (למשל, חוסר בצירופי טבלאות, ישויות פרטיות לא מקושרות או תנאי סינון מורכבים) ומנסח תיקונים ממוקדים.
שיפור והעלאה: הסוכן מוסיף או משפר תבניות של שאילתות, מאפייני שאילתות וחיפושי ערכים כדי לפתור את הפערים, ומעלה באופן אוטומטי את קבוצת ההקשר המעודכנת אל Google Cloud מה-CLI שלכם.
חזרה: הסוכן חוזר על המחזור הזה בכמה סבבים עד שרמת הדיוק מתכנסת לציון האופטימלי.

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

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

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

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

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

יצירת תוכן וניתוח מעמיק לפי דרישה

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

יצירה ממוקדת: מתארים דרישה עסקית ספציפית בשפה טבעית, והסוכן יוצר את פריט ההקשר ומעלה אותו ישירות מה-CLI בלי עריכה ידנית:
- "צור תבנית ל: 'מצא לי בתים ליד בתי ספר טובים בהרצליה' עם SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7".
- "צור מאפיין למסנן properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 עם התווית 'למשפחה צעירה'."
- "צור חיפוש ערך עבור properties.city".
עדכון מספר פריטים בו-זמנית בקבוצת הקשרים: אם משנים את השמות של עמודות במסד הנתונים או את המבנים של הטבלאות, הנציג יכול לעדכן את כל פריטי ההקשר המושפעים בו-זמנית בלי לשנות רשומות לא קשורות:
- "בקבוצת ההקשר שלי, החלף את properties.property_type = 'SFR' ב-properties.property_type = 'Single Family Residential' בכל פריט שמתייחס לבתים חד-משפחתיים. אל תגעו בפריטים שלא קשורים."