כדי שהשאילתות של 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, גם אם המכונה של מסד הנתונים נמצאת באזור אחר.
הפעלת השירותים הנדרשים
מפעילים את השירותים הבאים בפרויקט:
הכנת מסד הנתונים
מכינים את מכונת AlloyDB ל-PostgreSQL ומגדירים את הגישה של הסוכן:
- יוצרים אשכול ומכונה של AlloyDB ויוצרים מסד נתונים, או משתמשים במכונה ובמסד נתונים קיימים.
- מפעילים את הגישה ל-Data API במכונה של AlloyDB. אם אתם משתמשים בכתובת IP פרטית, הגדירו את השדה Data API access (
dataApiAccess) לערךENABLEDבמכונה הראשית כדי שהסוכן יוכל לבדוק סכימות ולאמת שאילתות. במכונות שנוצרו בלי גישה ל-Data API, צריך להפעיל את הגישה ל-Data API או להגדיר אותה במסוף Google Cloud .
תפקידים והרשאות נדרשים
כדי לקבל את ההרשאות שנדרשות לשימוש בסוכן הנדסת ההקשר ולניהול קבוצות ההקשר, צריך להגדיר את התפקידים הבאים בניהול זהויות והרשאות גישה (IAM) ואת הרשאות הגישה הבאות למסד הנתונים:
- מוסיפים לאשכול משתמש או חשבון שירות ב-IAM. מידע נוסף זמין במאמר ניהול אימות IAM.
- מקצים את התפקידים
roles/alloydb.databaseUser,roles/serviceusage.serviceUsageConsumer,roles/geminidataanalytics.queryDataUserו-roles/mcp.toolUserלמשתמש או לחשבון השירות ב-IAM ברמת הפרויקט. מידע נוסף זמין במאמר הוספת קישור למדיניות IAM בפרויקט. - כדי ליצור, להעלות ולנהל קבוצות של הקשרים, צריך להקצות למשתמש או לחשבון השירות ב-IAM את התפקיד "עריכה ב-Dataplex Catalog" (
roles/dataplex.catalogEditor) או "אדמין ב-Dataplex Catalog" (roles/dataplex.catalogAdmin) ברמת הפרויקט. מידע נוסף זמין במאמר הרשאות לקבוצות הקשר. - אם אתם משתמשים בחיפושים של ערכים סמנטיים (
google_ml.embedding), צריך להפעיל את Vertex AI API ולהקצות את התפקידroles/aiplatform.userלחשבון השירות של אשכול AlloyDB. כדי לתת הרשאות לקריאה בלבד למסד הנתונים למשתמש או לחשבון השירות ב-IAM, נכנסים כמשתמש עם הרשאות של משתמש-על, כמו המשתמש
postgres:GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";מחליפים את
USER_NAMEבכתובת האימייל של המשתמש (בחשבון שירות, משמיטים את הסיומת.). אם הטבלאות נמצאות בסכימה מותאמת אישית שאינהpublic, צריך להריץ גם אתGRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME";ו-GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";. מידע נוסף זמין במאמר הענקת הרשאות למסד נתונים למשתמשי IAM.
הכנת מסד הנתונים לחיפושי ערכים
כדי להשתמש בחיפושים של טריגרמות וערכים סמנטיים עם זמן אחזור קצר של שאילתות, צריך להגדיר את מסד הנתונים של AlloyDB עם התוספים הנדרשים, עמודות הטמעה שחושבו מראש ואינדקסים בטבלאות חיפוש או בטבלאות מאפיינים (פחות מ-100,000 שורות, או SELECT DISTINCT תצוגה מהותית שרועננה):
כדי לאפשר למכונה של AlloyDB לבצע חיפושים של ערכים לא מדויקים של טריגרמות (
%ו-<->), מפעילים את התוסףpg_trgmויוצרים אינדקס טריגרמות שלGiSTבעמודת החיפוש של היעד:CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE INDEX IF NOT EXISTS idx_properties_address_trgm ON properties USING GiST (address gist_trgm_ops);האינדקס מאפשר ל-
ORDER BY column <-> $value::text LIMIT 25להשתמש בסריקת אינדקס של K-nearest-neighbor (KNN) במקום לסרוק את כל הטבלה.כדי לאפשר למכונה של AlloyDB לבצע חיפושים של ערכים סמנטיים (
<=>ו-google_ml.embedding):מפעילים את Vertex AI API ונותנים את התפקיד
roles/aiplatform.userלחשבון השירות של AlloyDB. מידע נוסף זמין במאמר שילוב עם Vertex AI.מפעילים את התוספים
vectorו-google_ml_integrationבמסד הנתונים:CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS google_ml_integration;מוסיפים עמודה מסוג
vector(768)לטבלת החיפוש, מחשבים מראש הטמעות לשורות קיימות ויוצרים אינדקס קוסינוס מסוגHNSW(vector_cosine_ops) במקום לקרוא ל-google_ml.embeddingלכל שורה בזמן השאילתה:ALTER TABLE properties ADD COLUMN IF NOT EXISTS city_embedding vector(768); UPDATE properties SET city_embedding = l2_normalize(subvector(google_ml.embedding('gemini-embedding-001', city)::vector, 1, 768))::vector(768) WHERE city IS NOT NULL AND city_embedding IS NULL; CREATE INDEX IF NOT EXISTS idx_properties_city_embedding_hnsw ON properties USING hnsw (city_embedding vector_cosine_ops);
הכנת הסביבה
אתם יכולים ליצור קבוצות הקשר ולבצע להן אופטימיזציה מסביבת הפיתוח המקומית או מ-IDE.
התקנת uv
סוכן ה-context engineering דורש את uv כדי לנהל את חבילות ה-Python הבסיסיות:
מתקינים את
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).
- Antigravity CLI: מריצים את
יצירה ואופטימיזציה של הקשר
סוכן הנדסת ההקשר מנחה את קבוצת ההקשרים לאורך מחזור חיים מקצה לקצה, החל מההפעלה הראשונית ועד ליכולת הכללה מאומתת.
יצירת קבוצת הקשרים בסיסית
כדי להימנע מיצירת הקשר מדף ריק, הנציג בודק את הסכימה של מסד הנתונים יחד עם כל פריטי המידע הזמינים של האפליקציה, כמו דרישות עסקיות, מסמכים או שאילתות SQL לדוגמה. הסוכן מפיק קבוצת הקשר בסיסית ראשונית שמכילה תבניות שאילתה בסיסיות והיבטים של שאילתות שמבוססים על מודל מסד הנתונים שלכם.
אחרי שהנציג יוצר ומאמת את ההקשר הבסיסי, הוא מעלה אותו ישירות אל Google Cloud ומחזיר את שם המשאב של קבוצת ההקשרים.
יצירת מערכי נתונים להערכה ולבדיקה מפריטי מידע שנוצרו באפליקציה
כדי לשפר את הדיוק באופן שיטתי, צריך שאלות של אמת קרקע (ground truth) בשילוב עם שאילתות SQL מאומתות. אם עדיין אין לכם נקודת השוואה להערכה, הנציג יכול ליצור אחת כזו על ידי חילוץ תרחישים עסקיים מקוד האפליקציה, משאילתות היסטוריות ומהסכימה של מסד הנתונים.
במהלך יצירת מערך הנתונים, הנציג יוצר שתי קבוצות נפרדות:
- נקודת השוואה לאימון: אוסף של זוגות מייצגים של שאלה ו-SQL שמשמשים במהלך אופטימיזציה איטרטיבית.
- קבוצת נתונים שהוחזקה: קבוצה נפרדת של שאלות שדומות בתחום שלהן למדד ההשוואה לאימון, ששמורה לבדיקת יכולת ההכללה.
אופטימיזציה של הדיוק באמצעות טיפוס בהר (hill-climbing)
באופטימיזציה של טיפוס על גבעה, הנציג משפר באופן איטרטיבי את קבוצת ההקשרים כדי להגיע לדיוק של כמעט 100% ב-QueryData:
- הערכה: הסוכן בודק את קבוצת ההקשר הנוכחית מול נקודת ההשוואה לאימון באמצעות 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".
- "צור תבנית ל: 'מצא לי בתים ליד בתי ספר טובים בהרצליה' עם SQL:
עדכון מספר פריטים בו-זמנית בקבוצת הקשרים: אם משנים את השמות של עמודות במסד הנתונים או את המבנה של טבלאות, הנציג יכול לעדכן את כל פריטי ההקשר המושפעים בו-זמנית בלי לשנות רשומות לא קשורות:
- "בקבוצת ההקשרים שלי, החלף את
properties.property_type = 'SFR'ב-properties.property_type = 'Single Family Residential'בכל פריט שמתייחס לבתים חד-משפחתיים. אל תגעו בפריטים שלא קשורים."
- "בקבוצת ההקשרים שלי, החלף את