יצירת סוכן להעשרת המטא-נתונים

Knowledge Catalog (לשעבר Dataplex Universal Catalog) מנהל מטא-נתונים של נכסי נתונים בארגון. המטא-נתונים האלה מספקים את ההקשר שבו הסוכנים משתמשים כדי לגלות, להבין ולשאול את הנתונים שנדרשים כדי לענות על שאלות של משתמשים.

‫Knowledge Catalog מנהל את המשאבים באופן אוטומטי, עוקב אחרי סכימות טכניות ויוצר תיאורים ופרופילי נתונים, אבל לעיתים קרובות הקשר עסקי חשוב נמצא במקומות אחרים, כמו:

  • מסמכים פנימיים ו-Wiki
  • מאגרי קודים
  • ערוצי תקשורת כמו Google Chat ו-Slack

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

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

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

כדי להריץ את סוכן ההעשרה של Knowledge Catalog, אתם צריכים לעמוד בדרישות הבאות:

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

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

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

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

ההרשאות הנדרשות

כדי להשתמש בסוכן ההעשרה, נדרשות ההרשאות הבאות:

  • bigquery.projects.get/createDatasets
  • dataplex.projects.search
  • dataplex.entryGroups.get/updateEntries
  • aiplatform.endpoints.predict
  • serviceusage.services.use

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

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

כדי להשתמש בסוכן ההעשרה של Knowledge Catalog, צריך להפעיל את ממשקי ה-API הבאים בפרויקט:

  • BigQuery API
  • Knowledge Catalog API
  • Vertex AI API
  • Service Usage API

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

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

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

התקנת יחסי תלות

כדי להריץ את הדוגמה, צריך את החבילות והכלים הבאים של Python:

  • ‫google-adk (ערכה לפיתוח סוכנים (ADK))
  • google-cloud-dataplex Knowledge Catalog Python Client
  • ‫google-auth ניהול Application Default Credentials
  • ‫mcp[cli] ליצירת שרת MCP לדוגמה
  • ‫gcloud לאימות ולהגדרה. הוראות להתקנת Google Cloud CLI מופיעות במסמכי התיעוד של Google Cloud SDK.

הגדרת הסביבה

  1. מגדירים את gcloud ונכנסים לחשבון:

    gcloud auth application-default login
gcloud config set core/project PROJECT_ID

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

    • ‫PROJECT_ID במזהה הפרויקט

  2. משכפלים את המאגר dataplex-labs ומנווטים לספריית קובצי המקור לדוגמה:

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/knowledge_catalog_enrichment_agent/src

  3. כדי להתקין את הרכיבים התלויים, משתמשים בסקריפט שמוגדר מראש, שמגדיר סביבה וירטואלית של Python ואת משתני הסביבה הנדרשים:

    source env.sh --install

  4. כדי ליצור מערך נתונים לדוגמה ב-BigQuery בשם kc_sample_analytics באזור us של פרויקט הענן, מריצים את הסקריפט create_data.py:

    python3 ../sample/data/create_data.py

    הדוגמה כוללת גם מספר מסמכים בספרייה sample/docs. המסמכים האלה יוצרים מאגר ידע מקומי. סוכן העשרה משתמש במאגר הידע הזה כדי לחלץ מידע וליצור תיעוד.

הורדת מטא-נתונים

מתחילים בהפעלת כלי ההורדה כדי לחלץ תמונת מצב של מטא-נתונים מ-Knowledge Catalog עבור מערך הנתונים של BigQuery והטבלאות שלו. כך נוצרים פריטי מטא-נתונים מקומיים.

הארגומנט --dir מציין את הספרייה שבה נכתבים קובצי המטא-נתונים.

python3 -m enrichment.download \
  --dir ../sample/metadata.initial \
  --dataset ${KC_ENRICH_SAMPLE_PROJECT}.kc_sample_analytics

הסקריפט יוצר קובץ Markdown אחד לכל טבלה בספרייה sample/metadata, לפי מוסכמת השמות הבאה: <project_id>.<dataset_id>.<table_id>.md.

העשרת המטא-נתונים

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

  • ‫--dir: מציין את הספרייה שמכילה את קובצי המטא-נתונים המקומיים.
  • ‫--output-dir: מציין את ספריית היעד של קובצי המטא-נתונים המעודכנים.
  • ‫--config-dir: מציין את הספרייה שמכילה את ההוראות לסוכן, את כלי ה-MCP ואת הכישורים.
python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

בדיקת המטא-נתונים

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

git diff --no-index ../sample/metadata.initial ../sample/metadata.new

פרסום המטא-נתונים

מריצים את כלי הפרסום כדי לפרוס את המטא-נתונים המועשרים ב-Knowledge Catalog.

python3 -m src.enrichment.publish --dir ../sample/metadata.new

התאמה אישית לנתונים שלכם

בשלב הקודם השתמשתם בארגומנט --config-dir כדי להפנות את הסוכן לספרייה ../sample/config לצורך ההגדרה שלו. כך הסוכן יודע איפה למצוא מידע ואיך ליצור אינטראקציה עם מקורות שונים.

הדוגמה מגיעה עם הגדרת ברירת מחדל שמורה לסוכן להשתמש בשרת MCP מקומי כדי לגשת לקבצים במאגר הידע המקומי (sample/docs). כדי להחיל את תהליך העבודה הזה בסביבה שלכם, אתם יכולים להתאים אישית את קובצי ההגדרה האלה כדי לחבר את הסוכן לוויקי הפנימי, למאגרי קוד, ל-Google Drive או למערכות אחרות.

הספרייה sample/config/ מכילה את הקבצים הבאים:

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md
  • ‫instructions.md: משפר את הוראות הבסיס של הסוכן באמצעות פרטים שרלוונטיים לארגון, כמו הוראה לחפש במאגר ידע ספציפי.
  • ‫mcp.json: הגדרה של שרתי MCP שהסוכן יכול להשתמש בהם כדי לגשת לכלים של מקורות המידע, כמו כלי לקריאת קבצים מספרייה מקומית.
  • ‫SKILL.md: מתאר איך הסוכן צריך להשתמש בכלים ספציפיים כדי לקיים אינטראקציה עם מקור מידע, למשל שימוש ב-list_contents,‏ read_file ו-search_content כדי למצוא מידע במסמכים מקומיים.

עיון בקוד לדוגמה של Knowledge Catalog

הכלים download ו-publish בקטע של תהליך ההעשרה משתמשים בממשקי Knowledge Catalog API כדי לקרוא ולכתוב מטא-נתונים.

בקטע הזה מוסבר איך ממשקי ה-API האלה פועלים, כדי שתוכלו להתאים את הדוגמה לשילובים שלכם.

חיפוש ואחזור של מטא-נתונים

בדוגמה נעשה שימוש בממשקי ה-API הבאים כדי לחפש ולאחזר מטא-נתונים:

  • ‫SearchEntries כדי לאחזר את המטא-נתונים של הרשומה ומטא נתונים של מיקום עבור מערך הנתונים.
  • ‫ListEntries כדי למנות טבלאות BigQuery בתוך Catalog EntryGroup.
  • GetEntry כדי לאחזר את המטא-נתונים הספציפיים של כל טבלה ב-BigQuery.

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

import google.cloud.dataplex_v1 as dataplex

BIGQUERY_TABLE_TYPE = "projects/dataplex-types/locations/global/entryTypes/bigquery-table"
OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"

catalog = dataplex.CatalogServiceClient()

dataset_reference = '...'   # project_id.dataset_id
project_id, dataset_id = dataset_reference.split('.')

# 1. Search for dataset to determine its location
search_response = catalog.search_entries(
    request=dataplex.SearchEntriesRequest(
        name=f"projects/{project_id}/locations/global",
        query=f"type=dataset name={dataset_id}",
        page_size=1
    )
)
dataset_entry = search_response.results[0].dataplex_entry
location_id = dataset_entry.entry_source.location

# 2. List resources in the underlying group
entry_group_name = f"projects/{project_id}/locations/{location_id}/entryGroups/@bigquery"
entry_filter = f'parent_entry="{dataset_entry.name}"'
list_response = catalog.list_entries(
    request=dataplex.ListEntriesRequest(
        parent=entry_group_name,
        entry_filter=entry_filter,
    )
)

# 3. Retrieve metadata for each table in the list
for table_entry in list_response.entries:
    entry = catalog.get_entry(
        request=dataplex.GetEntryRequest(
            name=table_entry.name,
            view="CUSTOM",
            aspect_types=[OVERVIEW_ASPECT_TYPE]
        )
    )

עדכון המטא-נתונים של הטבלה

בדוגמת הקוד הבאה מוצג איך לפרסם את התיעוד שנוצר בהיבט Overview של טבלה ולעדכן את המטא-נתונים שלה:

import google.cloud.dataplex_v1 as dataplex
import google.protobuf.field_mask_pb2 as field_mask_pb2
import google.protobuf.json_format as jsonpb

OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"
OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview"

catalog = dataplex.CatalogServiceClient()

table_reference = "..."    # project_id.dataset_id.table_id
project_id, dataset_id, table_id = table_reference.split('.')

entry_data = {
    "name": f"bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}",
    "aspects": {
        OVERVIEW_ASPECT_KEY: {
            "aspectType": OVERVIEW_ASPECT_TYPE,
            "data": {
                "content": "...", # content parsed from local markdown file
                "contentType": "MARKDOWN"
            }
        }
    }
}

entry = dataplex.Entry()
jsonpb.ParseDict(entry_data, entry._pb)

catalog.update_entry(
    request=dataplex.UpdateEntryRequest(
        entry=entry,
        update_mask=field_mask_pb2.FieldMask(paths=["aspects"]),
        aspect_keys=[OVERVIEW_ASPECT_KEY],
    )
)

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