אחזור הקשר של נכסי נתונים

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

ה-method‏ lookupContext מגשרת על הפער בהקשר באמצעות בקשת API אחת כדי לאחזר חבילה בפורמט מוגדר מראש של מטא-נתונים של נכסי נתונים, שעברה אופטימיזציה לתהליכי עבודה Agentic Workflows. אתם יכולים להשתמש בהקשר הקומפקטי הזה, שמוכן ל-LLM, כדי לבסס את הנציגים שלכם בהערכה של נכסי נתונים ובשימוש בהם.

אתם יכולים להשתמש ב-lookupContext לכל נכסי הנתונים שמאוחסנים ב-Knowledge Catalog, למשל טבלאות ב-BigQuery, מערכי נתונים ושגרות, וגם דומיינים של נתונים וכל רשומה אחרת.

איך הסוכנים יכולים לקבל הקשר של נתונים?

1. הנציג מאחזר נכסי נתונים שעשויים להיות רלוונטיים לאחזור הקשר, למשל באמצעות חיפוש סמנטי ב-Knowledge Catalog.
2. הנציג משתמש ב-method‏ lookupContext כדי לבצע קריאה אחת ל-API או בקשה לכלי MCP שמאחזרת את ההקשר של נכס ספציפי.

3. ה-method מחזירה תשובה שמכילה בלוק טקסט בפורמט מוגדר מראש. בהתאם לפרמטר format שמציינים בבקשה, המסמך יכול להיות בפורמט YAML,‏ XML או JSON.

   התשובה מכילה את רכיבי ההקשר הבאים:

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

4. הסוכן משתמש בתגובה הזו כדי להנחות את הבחירה של נכסים רלוונטיים או את השימוש בהם.

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

לפני שמשתמשים ב-method‏ lookupContext, צריך לוודא שיש לכם את התפקידים הנדרשים ולהפעיל את ממשקי ה-API הנדרשים.

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

כדי לקבל את ההרשאות שדרושות להפעלת השיטה lookupContext, בקשו מהאדמין לתת לכם את התפקידים הבאים ב-IAM בפרויקט Google Cloud iam.gserviceaccount.com:

• גישת קריאה למשאבי קטלוג, כולל רשומות, קבוצות רשומות ומילוני מונחים: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

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

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

הפעלת ממשקי ה-API

כדי להשתמש ב-method ‏lookupContext, צריך להפעיל את ממשקי ה-API הבאים בפרויקט:

• Knowledge Catalog API

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

להפעלת ה-API

אחזור הקשר של נכס נתונים

כדי לאחזר את ההקשר של נכס נתונים, אפשר לגשת ל-method‏ lookupContext ישירות באמצעות Dataplex API או להשתמש בשרת Model Context Protocol‏ (MCP) מרוחק של Knowledge Catalog או ב-MCP Toolbox For Databases.

השיטה lookupContext מסננת את המשאבים על סמך ההרשאות שלכם. התשובה מכילה נתונים רק לגבי נכסים שלזהות שלכם יש את ההרשאות הנדרשות ב-IAM (המערכת לניהול הזהויות והרשאות הגישה) כדי לגשת אליהם. אם אין לכם הרשאות במשאבים המבוקשים, ה-method מחזירה תשובה ריקה.

REST

כדי לאחזר הקשר של נכס נתונים, שולחים את הבקשה הבאה:

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
• ‫LOCATION: האזור שבו הנכס נמצא (לדוגמה, us-central1)
• ‫RESOURCES: עד עשרה שמות של רשומות לאחזור ההקשר, בפורמט projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. במקרה של כמה מקורות, ה-API יוצר קשרים בין המקורות המבוקשים, כמו הצטרפות סכמה תכופה, ומחזיר את פרטי הקשר בהקשר.
• ‫OPTIONS: האפשרויות שמאפשרות להגדיר את ההקשר:
  • ‫format הוא הפורמט של קובץ ההקשר. לדוגמה, yaml.
  • ‫context_budget הוא מספר התווים שהתשובה מוגבלת אליו. אם מגדירים את הפרמטר all_schema_fields לערך true, ה-API מחזיר את כל השדות של הסכימה, ללא קשר לערך של context_budget.

דוגמה לבקשה שמאחזרת הקשר לטבלה ב-BigQuery:

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

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

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

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

כדי לבצע אימות ב-Knowledge Catalog, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

בדוגמה הבאה מוצג איך לאחזר את ההקשר של טבלה ב-BigQuery:

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

אחזור הקשר לתרחישים

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

• סוג השגרה, למשל פונקציה סקלרית, פונקציית טבלה או פרוצדורה.
• השפה של השגרה.
• הארגומנטים וסוג ההחזרה של השגרה.
• קוד המקור של השגרה (גוף ההגדרה).
• תיאורים ומטא-נתונים אחרים מ-Knowledge Catalog.

כדי לאחזר הקשר של תרחיש, צריך לכלול את שם הרשומה של התרחיש ברשימה resources של הבקשה. שם הרשומה הוא בפורמט הבא:

projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט שמכיל את השגרה.
• ‫LOCATION: המיקום של מערך הנתונים שמכיל את השגרה (לדוגמה, us).
• ‫DATASET_ID: מזהה קבוצת הנתונים שמכילה את השגרה.
• ‫ROUTINE_ID: מזהה התרחיש.

מהן השיטות המומלצות לחיפושי הקשר?

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

• מבקשים את האורך שנבחר להקשר הפלט באמצעות הפרמטר context_budget. השיטה lookupContext תנסה להתאים את ההקשר הרלוונטי ביותר לפלט, כמה שיותר קרוב למגבלות שנקבעו על ידי הפרמטר.
• אפשר לכלול עד עשרה נכסי נתונים ברשימה resources. לדוגמה, אם כוללים כמה טבלאות ברשימה resources, ה-API מספק את ההקשר לא רק לטבלאות האלה, אלא גם לנתיבי הצטרפות אפשריים ביניהן, וכך מספק הנחיות לגבי אופן השימוש בטבלאות האלה יחד.
• כדי להימנע משינויים יקרים, כדאי להשתמש באפשרות format, כמו yaml או json, שהכי מתאימה ללוגיקת הניתוח של ה-LLM או הסוכן.

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

• איך יוצרים נציג שיאתר את הנתונים שלכם
• איך יוצרים סוכן להעשרת המטא-נתונים
• הסבר על תחביר החיפוש ב-Knowledge Catalog
• מידע נוסף על הצגת קשרי נתונים