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

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

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

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

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

  • חילוץ הקשר: חילוץ הקשר עסקי ממאגרי ידע, ממסמכים, מקוד או מצ'אט כדי להעשיר את המטא-נתונים הטכניים.
  • יצירת מסמכי תיעוד: יצירת מסמכי תיעוד לטבלאות ב-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
  • Dataplex API
  • Vertex AI API
  • Service Usage API

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

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

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

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

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

  • ‫google-adk (ערכה לפיתוח סוכנים (ADK))
  • לקוח Python של google-cloud-dataplex Knowledge Catalog
  • ‫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. משכפלים את המאגר knowledge-catalog ועוברים לספריית קובצי המקור לדוגמה:

    git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/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 בקטע של תהליך ההעשרה משתמשים בממשקי ה-API של Knowledge Catalog כדי לקרוא ולכתוב מטא-נתונים.

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

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

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

  • ‫SearchEntries כדי לאחזר את המטא-נתונים של הרשומה והמיקום של מערך הנתונים.
  • ‫ListEntries כדי למנות טבלאות ב-BigQuery בתוך 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],
    )
)

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