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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Knowledge Catalog API

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

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

להפעלת ה-API

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

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

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

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.

כדי לבצע אימות לקטלוג הידע, צריך להגדיר את 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

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

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

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