יצירת תשתית נתונים באמצעות מטא-נתונים של Knowledge Catalog

1. מבוא

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

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

ה-Codelab הזה הוא חלק מסדרה בת שני חלקים שבה נסביר איך ליצור סוכן AI שמודע לניהול.

בחלק הראשון הזה, תבנו בסיס נתונים. תגדירו אגם נתונים ריאליסטי ו'מבולגן' ב-BigQuery, תחיל תגי מטא-נתונים קשיחים (היבטים של Knowledge Catalog) כדי להבחין בין נתונים תקפים לבין רעשי רקע, ותשתמשו בממשק שורת הפקודה (CLI) של Antigravity (AGY) כדי לבדוק באופן מקומי אם הסוכן פועל בהתאם לכללי משילות המידע (data governance) שהגדרתם.

מומלץ לקרוא את החלק השני בסדרה הזו, שבו מוסבר איך לפרוס את אב הטיפוס של הסוכן המקומי באפליקציית אינטרנט מאובטחת ברמה ארגונית באמצעות Model Context Protocol‏ (MCP) ו-Cloud Run. ‫👉 Part 2

מה תלמדו

• פריסת אגם נתונים (data lake) ריאליסטי עם כמה רמות באמצעות סקריפט הגדרה.
• עיצוב ורישום של תבניות מטא-נתונים מותאמות אישית (סוגי היבטים) ב-Knowledge Catalog כדי להבחין בין מוצרי נתונים רשמיים לבין טבלאות גולמיות בארגז החול.
• לפני שכותבים קוד אפליקציה, כדאי לאמת את כללי משילות המידע באופן מקומי באמצעות AGY CLI.

הדרישות

• פרויקט ב-Google Cloud שהחיוב בו מופעל.
• גישה ל-Google Cloud Shell (ה-CLI של AGY מותקן מראש ב-Cloud Shell).
• הבנה בסיסית של BigQuery ושל Knowledge Catalog.

מושגים מרכזיים

• Knowledge Catalog: שירות מאוחד לניהול מטא-נתונים. אנחנו משתמשים בו כדי להוסיף הקשר עסקי (ניהול) למטא-נתונים טכניים (סכימות).
• ‫Aspect Type: תבנית של מטא-נתונים מובְנים. בניגוד לתגי טקסט חופשי, תגי היבטים מחייבים הקלדה חזקה (מספור, ערכים בוליאניים), ולכן המכונות יכולות להסתמך עליהם לצורך הערכה.

2. הגדרה ודרישות

הפעלת Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-Codelab הזה נשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-מסוף Google Cloud, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הקצאת המשאבים והחיבור לסביבה יימשכו רק כמה רגעים. בסיום התהליך, אמור להופיע משהו כזה:

המכונה הווירטואלית הזו כוללת את כל הכלים שדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.

הפעלת הסביבה

פותחים את Cloud Shell ומגדירים את משתני הפרויקט כדי לוודא שכל הפקודות מכוונות לתשתית הנכונה.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

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

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

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

שכפול המאגר

מקבלים את קוד התשתית ואת סקריפטים האוטומציה ממאגר GitHub. כדי לחסוך במקום בדיסק ב-Cloud Shell, נוריד רק את התיקייה הספציפית שדרושה למעבדה הזו.

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

בניית אגם נתונים (data lake) עם נתונים לא מסודרים

בדרך כלל סביבות נתונים בעולם האמיתי לא נקיות. כדי לדמות את המציאות, אנחנו צריכים שילוב של מרכזי נתונים 'רשמיים' וטבלאות 'ארגז חול' לא מהימנות.

נשתמש בסקריפט הגדרה כדי לפרוס את מערכי הנתונים והטבלאות ב-BigQuery.

1. הופכים את סקריפט ההגדרה לסקריפט שאפשר להפעיל ומריצים אותו. פעולה זו תיצור שלושה מערכי נתונים של BigQuery‏ (finance_mart, ‏ marketing_prod, ‏ analyst_sandbox) ותאכלס את הטבלאות שלהם בנתונים לדוגמה.

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

נקודת עצירה: עכשיו יש לכם אגם נתונים מלא, אבל לא מנוהל. ל-AI, כל הטבלאות נראות בדיוק אותו דבר.

3. יצירת תבנית למשילות מידע (סוג היבט)

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

נרשום את התבנית הזו באמצעות gcloud CLI כדי שתוכלו לראות איך היא מוגדרת.

בדיקת סכימת ההיבטים

כדי לראות את הגדרת הסכימה, מריצים את הפקודה הבאה כדי להציג את התוכן של aspect_template.json:

cat aspect_template.json

יוצג לכם מבנה ה-JSON הבא:

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      ...
    }
  ]
}

שימו לב איך הסכימה הזו אוכפת סוגי נתונים מחמירים, כמו enum לרמת הקריטיות (GOLD_CRITICAL, ‏ SILVER_STANDARD, ‏ BRONZE_ADHOC) ו-bool ל-is_certified. כך מובטח שהמטא-נתונים יישארו מובְנים וקריאים למכונה.

רישום סוג ההיבט

מריצים את הפקודה gcloud הבאה כדי לרשום את התבנית הזו במאגר של Knowledge Catalog.

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

4. החלת אמצעי בקרה

זהו שלב הנדסי קריטי. בשלב הזה, הטבלאות finance_mart.fin_monthly_closing_internal ו-analyst_sandbox.tmp_data_dump_v2_final_real נראות זהות למודל שפה גדול (LLM). הן רק אובייקטים עם עמודות.

כמהנדסי ניהול, אתם צריכים לצרף היבט (תווית מטא-נתונים מאומתת) לטבלאות האלה כדי להבדיל ביניהן. בארגון אמיתי, הייתם מבצעים אוטומציה של התהליך הזה באמצעות צינורות עיבוד נתונים של CI/CD. אנחנו נדמה את האוטומציה הזו באמצעות סקריפטים.

יצירת מטען ייעודי (payload) של ניהול

המפתחות של ההיבטים ב-Knowledge Catalog חייבים להיות ייחודיים באופן גלובלי (עם קידומת של מזהה הפרויקט). הסקריפט ./generate_payloads.sh ייצור באופן דינמי את קובצי המטא-נתונים ב-YAML.

chmod +x ./generate_payloads.sh
./generate_payloads.sh

פלט:

הפעולה הזו יוצרת תיקייה בשם './aspect_payloads' שמכילה 4 קובצי YAML, שמגדירים את תרחישי השליטה (Gold/Internal, ‏ Gold/Public, ‏ Silver/Realtime, ‏ Bronze/Sandbox).

החלת היבטים באמצעות ה-CLI

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

cat aspect_payloads/fin_internal.yaml

יוצג לכם התוכן הבא.

your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

שימו לב איך קובץ ה-YAML הזה מגדיר באופן מפורש את ההקשר העסקי, למשל הגדרת הדגל is_certified: true והקצאת הרמה GOLD_CRITICAL. לתת ל-LLM כללים ברורים ומובנים להערכה במקום לנחש על סמך שמות הטבלאות.

עכשיו מריצים את סקריפט האפליקציה. הסקריפט מבצע איטרציה בטבלאות BigQuery ומריץ את הפקודה gcloud dataplex entries update כדי לצרף את המטא-נתונים הקשיחים האלה.

chmod +x ./apply_governance.sh
./apply_governance.sh

אימות (אופציונלי)

לפני שממשיכים, צריך לוודא שהמטא-נתונים הוחלו בצורה נכונה במסוף.

1. פותחים את הדף Knowledge Catalog במסוף Google Cloud. אם האפשרות Knowledge Catalog לא מופיעה בתפריט הניווט הימני, משתמשים בסרגל החיפוש בחלק העליון של חלון מסוף Google Cloud, מקלידים Knowledge Catalog ובוחרים את התוצאה בקטע Top results (התוצאות המובילות) או Products & Pages (מוצרים ודפים).
2. חיפוש של fin_monthly_closing_internal. הטבלה ב-BigQuery אמורה להופיע בתוצאות. לוחצים על שם הטבלה כדי להיכנס לדף הפרטים שלה.

3. בדף הפרטים של הטבלה, מחפשים את הקטע תגים והיבטים אופציונליים בתחתית הדף.
4. ההיבט official-data-product-spec יוצג. מוודאים שהערכים תואמים לתרחיש Gold Internal שהגדרנו.

עכשיו אישרתם שטבלאות BigQuery זהות מבחינה טכנית (fin_monthly_closing_internal ו-tmp_data_dump_v2_final_real), אבל הן שונות מבחינה לוגית בגלל מטא-נתונים שניתנים לקריאה על ידי מכונה.

5. הגדרה ויצירת אב-טיפוס של הסוכן

לפני שנבנה אפליקציה (בשלב 2), נאמת את הלוגיקה של משילות מידע (data governance) באופן מקומי. צריך להתקין את הפלאגין Knowledge Catalog ולהגדיר את מיומנות הסוכן.

התקנת התוסף

ב-Cloud Shell, מתקינים את הפלאגין Knowledge Catalog. תתבקשו לאשר את הפעולה ולספק את פרטי ההגדרה.

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

בדיקת מיומנות הנציג

מיומנות הנציג היא קובץ הגדרה סטטי לשימוש חוזר שנמצא במיקום .agents/skills/knowledge_catalog_governance/SKILL.md. הוא מכיל את הלוגיקה שמתרגמת כללים אנושיים מופשטים (לדוגמה, 'אני צריך נתונים בטוחים') לחיפושים טכניים מדויקים.

בודקים את הקובץ כדי להבין את האלגוריתם שאנחנו מלמדים את ה-AI:

cat .agents/skills/knowledge_catalog_governance/SKILL.md

שימו לב שההנחיה מורה למודל לבצע לולאה קפדנית של שלב 1 (אימות מטא-נתונים) ושלב 2 (ביצוע שאילתה). המודל צריך לגלות ולאמת את המטא-נתונים לפני שהוא יוצר SQL.

הפעלת הסוכן ובדיקת תרחישים

מתחילים את הסשן ב-AGY CLI. הוא יאתר ויטען את המיומנות באופן אוטומטי מהספרייה של .agents/skills.

agy

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

אימות התקנה

מקלידים /mcp כדי לוודא שהפלאגין Knowledge Catalog פעיל. knowledge-catalog אמור להופיע כתוסף פעיל עם הכלים הזמינים שלו.

/mcp

הפלט הצפוי:

MCP Servers
...
>  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

תרחישי בדיקה (יצירת אב טיפוס)

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

💡 כדאי לדעת: אם מוצגת בקשה, בוחרים באפשרות '2. כן, ותמיד לאפשר 'knowledge-catalog/search_entries' בשיחה הזו' כדי לאפשר בדיקה חלקה.

• תרחיש א' (אישור הנתונים של סמנכ"ל הכספים):

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

מה צפוי: הסוכן יזהה אוטומטית את הפרויקט הפעיל והאזור שלכם מהכלים שלו, ישלח שאילתה ל-fin_monthly_closing_internal כי יש התאמה סמנטית בין GOLD_CRITICAL (מדויק) לבין INTERNAL_ONLY (ישיבת דירקטוריון) בהיבט שלו, וימליץ על הפרויקט.

• תרחיש ב' (גילוי נאות לציבור):

"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"

מה שצריך לקרות: הסוכן צריך לדלג על הטבלה הפנימית החודשית ולבחור רק את fin_quarterly_public_report כי הוא הנכס היחיד שתויג EXTERNAL_READY.

• תרחיש ג' (צרכים תפעוליים):

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

התשובה הצפויה: הסוכן בוחר באפשרות mkt_realtime_campaign_performance כי הוא מזהה את תדירות העדכון REALTIME_STREAMING, ונותן לה עדיפות על פני רמת המידע GOLD_CRITICAL של נתוני הכספים.

• תרחיש ד' (ניסויים בארגז חול):

"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."

מה שקורה בפועל: הסוכן בוחר ב-tmp_data_dump_v2_final_real כי הוא תואם מבחינה סמנטית ל-BRONZE_ADHOC (נתונים גולמיים) ול-is_certified: false (סביבת ארגז חול) בהיבט שלו.

(כדי לצאת מהסשן של AGY, מקלידים ‎ /exit או ‎ /quit)

6. מעולה! מה השלב הבא?

יצרתם בהצלחה בסיס נתונים מנוהל והוכחתם שאפשר להשתמש ב-AI כדי לפעול בהתאם לכללי המטא-נתונים באמצעות אב טיפוס מקומי של CLI.

הגעתם לנקודת ביקורת. בחירת השלב הבא

אפשרות א': אני רוצה להמשיך לחלק 2 עכשיו!

אם אתם רוצים להפוך את אב הטיפוס המקומי הזה לאפליקציית אינטרנט מאובטחת ברמת ייצור באמצעות Model Context Protocol‏ (MCP) ו-Cloud Run:

‫👈 קישור ל-Codelab חלק 2

⚠️ עצירה: אל תבצעו את שלבי הניקוי שבהמשך. כדי לבצע את חלק 2, תצטרכו את הנתונים הנוכחיים ואת ההגדרות של קטלוג הידע.

אפשרות ב': אשלים את חלק 2 מאוחר יותר או שרציתי להשלים רק את חלק 1.

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

אל דאגה! בחלק 2, נספק 'סקריפט להפעלה מהירה' שיבנה מחדש את סביבת חלק 1 תוך 2 דקות בלבד, כדי שתוכלו להמשיך בדיוק מהמקום שבו הפסקתם.

‫👈 עוברים לקטע בנושא ניקוי.

7. ניקוי (רק באפשרות ב')

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

השמדת אגם הנתונים

אם אתם נמצאים כרגע בסשן של AGY CLI, יוצאים מהסשן על ידי הקשה על Ctrl+C פעמיים או הקלדה של /quit. לאחר מכן, מריצים את הפקודות הבאות:

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

הסרת התוסף AGY CLI ומחיקת קבצים מקומיים

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos