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

ההקשר של הנתונים מאפשר לאפליקציות ה-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 (roles/dataplex.catalogViewer)

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

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

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

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

• Dataplex 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 תנסה להתאים את ההקשר הכי רלוונטי לפלט, כמה שיותר קרוב למגבלות שנקבעו בפרמטר.
• אפשר להוסיף עד 10 נכסי נתונים לרשימה resources. לדוגמה, אם כוללים כמה טבלאות ברשימה resources, ה-API מספק את ההקשר לא רק לטבלאות האלה, אלא גם לנתיבי הצטרפות אפשריים ביניהן, וכך מספק את ההנחיות הנדרשות לגבי אופן השימוש בטבלאות האלה יחד.
• כדי להימנע מטרנספורמציות יקרות, השתמשו באפשרות format, כמו yaml או json, שהכי מתאימה ללוגיקת הניתוח של ה-LLM או הנציג.

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

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