שימוש ב-Antigravity CLI כדי לבדוק את הקשר הנתונים

סוכני AI יכולים להסיק מסקנות, אבל הם מתחילים ללא ידע על החברה הספציפית שלכם. תארו לעצמכם שאתם שואלים נציג, "What is our Q1 revenue?‎" ללא הנחיה, יכול להיות שהסוכן יבחר מתוך עשרות טבלאות בשם 'הכנסה' במסדי הנתונים שלכם, החל מדוחות רשמיים ועד נתוני בדיקה לא מסודרים. אם הסוכן יבחר את הטבלה עם השם הכי דומה, הוא עלול להחזיר תשובות שגויות באופן משכנע על סמך מקורות לא מאומתים.

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

מטרות

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

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

לפני שמתחילים, חשוב לוודא שביצעתם את הפעולות הבאות:

כדי להשלים את המדריך הזה, אתם צריכים גם ידע בסיסי ב-BigQuery וב-Knowledge Catalog.

הכנת הסביבה

במדריך הזה משתמשים ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן. ‫Antigravity CLI‏ (agy) מותקן מראש ב-Google Cloud Shell.

  1. במסוף, לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) בסרגל הכלים שבפינה הימנית העליונה. Google Cloud יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו.

  2. ב-Cloud Shell, מגדירים את המשתנים PROJECT_ID ו-REGION כך שכל הפקודות העתידיות יופנו לפרויקט הספציפי Google Cloud שלכם.

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

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

    gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

  4. משכפלים את Google Cloud מאגר ההדגמות של DevRel.

    מורידים את קוד התשתית ואת הסקריפטים מ-GitHub. כדי למשוך רק את התיקייה הספציפית שדרושה לכם במדריך הזה, אתם יכולים להשתמש ב-sparse checkout.

    # 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 you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

פיתוח אגם נתונים לדוגמה

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

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

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

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

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

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

עכשיו מגדירים את הכללים של ניהול הנתונים. כדי לעשות זאת ב-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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

החלת משילות מידע

זהו שלב הנדסי קריטי. בשלב הזה, טבלאות finance_mart.fin_monthly_closing_internal ו-analyst_sandbox.tmp_data_dump_v2_final_real נראות זהות לסוכן AI. הן רק אובייקטים עם עמודות.

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

יצירת מטען ייעודי (payload) של משילות מידע (data governance)

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

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

תיקייה בשם aspect_payloads/ נוצרת ומכילה 4 קובצי YAML שמגדירים תרחישים שונים של משילות מידע (data governance) (fin_internal.yaml, ‏ fin_public.yaml, ‏ mkt_realtime.yaml, ‏ sandbox.yaml).

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

  1. לפני שמריצים את הסקריפט, כדאי לבדוק את הנתונים שמצורפים לטבלאות. מריצים את הפקודה הבאה כדי לראות את המטא-נתונים של נתוני הכספים הפנימיים:

    cat aspect_payloads/fin_internal.yaml

    קובץ ה-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

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

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

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

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

לפני שממשיכים, בודקים שהסקריפט החיל את ההיבטים בצורה נכונה ב Google Cloud מסוף:

  1. פותחים את הדף Knowledge Catalog במסוף Google Cloud . אפשר להשתמש בסרגל החיפוש העליון כדי למצוא אותו.
  2. חיפוש של fin_monthly_closing_internal. בוחרים את שם הטבלה ב-BigQuery בתוצאות כדי לפתוח את דף הפרטים שלה.
  3. בקטע Optional tags and aspects (תגים והיבטים אופציונליים) בתחתית, מחפשים את ההיבט official-data-product-spec. מוודאים שהערכים תואמים לתרחיש 'Gold Internal' שהגדרתם.

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

בדיקת הקשר של הנתונים באמצעות Antigravity CLI

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

התקנת פלאגין של שירות

ב-Cloud Shell, מתקינים את הפלאגין של השירות:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

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

מיומנות הנציג היא קובץ הגדרה סטטי לשימוש חוזר שנמצא במיקום .agents/skills/knowledge-catalog-governance/SKILL.md. הוא מכיל את הלוגיקה שמתרגמת כללים אנושיים מופשטים כמו "אני צריך נתונים בטוחים" לחיפושים טכניים מובנים.

כדי לבדוק את הגדרת המיומנות ולהבין איך עובד הקשר של הנתונים, בודקים את הקובץ SKILL.md:

cat .agents/skills/knowledge-catalog-governance/SKILL.md

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

הפעלה של Antigravity CLI ותרחישי בדיקה

מפעילים את הסשן של Antigravity CLI. מכיוון שאתם נמצאים בתיקיית הפרויקט, ה-CLI מזהה ומטעין את המיומנות באופן אוטומטי מהספרייה .agents/skills:

agy

אימות ההתקנה

בשורת הפקודה של Antigravity CLI, מאשרים שהפלאגין פעיל. מקלידים /mcp כדי להציג רשימה של כלים ופלאגינים שהוגדרו:

/mcp

הפלט צריך להציג את knowledge-catalog כפלאגין פעיל עם הכלים הזמינים שלו:

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

רוצה לנסות?

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

תרחיש 1: איתור נתונים סטנדרטיים מסוג Gold

האם Antigravity CLI יכול למצוא את הנתונים הכי מהימנים לפגישת דירקטוריון חשובה:

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?

ממשק ה-CLI אמור לדלג על הנתונים הגולמיים ולמצוא את fin_monthly_closing_internal. היא עושה זאת על ידי התאמת הבקשה שלך לנתונים מסוג 'סופיים' ו'חסויים' לתגי GOLD_CRITICAL ו-INTERNAL_ONLY שהוספת קודם.

תרחיש 2: גילוי נאות לציבור

נניח שאתם רוצים לשתף נתונים עם גורמים חיצוניים. אתם רוצים לוודא ש-CLI לא מאפשר לדליפת סודות פנימיים:

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?

למרות שהטבלה הפנימית מכילה את הפרטים הכי מפורטים, ממשק ה-CLI צריך לעקוף אותה. היא אמורה להפנות אתכם אל fin_quarterly_public_report כי זו הטבלה היחידה שתויגה כ-EXTERNAL_READY.

תרחיש 3: צרכים תפעוליים בזמן אמת

למדעני נתונים יש לעיתים קרובות צורך במידע העדכני ביותר. כדאי לבדוק אם Antigravity CLI מבין את ההבדל בין העלאה מרוכזת יומית לבין שידור חי:

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?

ה-CLI אמור למצוא את mkt_realtime_campaign_performance. הוא מזהה את תדירות העדכון של REALTIME_STREAMING במטא-נתונים.

תרחיש 4: חקר ארגז החול

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

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.

ה-CLI אמור למצוא את tmp_data_dump_v2_final_real. הוא יודע שזו הבחירה הנכונה כי היא תואמת לרמת BRONZE_ADHOC ומסומנת במפורש בסימן is_certified: false.

אחרי שמסיימים את הבדיקה, אפשר לצאת מהסשן של CLI:

/quit

הסרת המשאבים

כדי להימנע מחיובים חוזרים, צריך לבצע את הפעולות הבאות:

  1. אם אתם בסשן של Antigravity CLI, יוצאים מהסשן על ידי לחיצה על Ctrl+C פעמיים או הקלדה של /quit.

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

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

  3. מסירים את תוסף השירות ומסירים את קובצי ההדגמה המקומיים:

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

סיכום

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

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