‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

מטרות

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

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

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

בוחרים Google Cloud פרויקט למדריך הזה.
מוודאים שהחיוב מופעל בפרויקט.

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

הכנת הסביבה

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

במסוף Google Cloud , לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) ב סרגל הכלים שבפינה הימנית העליונה. יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו.
ב-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"
```

מפעילים את השירותים הנדרשים. 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

משכפלים את 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.

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

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

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

הגדרת סוג היבט מותאם אישית ב-Knowledge Catalog

עכשיו מגדירים את הכללים של ניהול הנתונים. כדי לעשות זאת ב-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. כך מוודאים שהמטא-נתונים יישארו מובְנים וקריאים למכונה.

רישום סוג ההיבט ב-Knowledge Catalog

מריצים את הפקודה 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) של מטא-נתונים של היבטים

המפתחות של ההיבטים ב-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).

צירוף היבטים לטבלאות BigQuery

לפני שמריצים את הסקריפט, כדאי לבדוק את הנתונים שמצורפים לטבלאות. מריצים את הפקודה הבאה כדי לראות את המטא-נתונים של נתוני הכספים הפנימיים:
```
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 מקבל כללים ברורים ומובנים להערכה, במקום לנחש על סמך שמות הטבלאות.
מריצים את סקריפט האפליקציה. הסקריפט הזה מבצע איטרציה בטבלאות ב-BigQuery ומשתמש בפקודה gcloud dataplex entries update כדי לצרף את מטעני המטא-נתונים לכל טבלה:
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

אימות ההיבטים שהוחלו במסוף Google Cloud

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

פותחים את הדף Knowledge Catalog במסוף Google Cloud . אפשר להשתמש בסרגל החיפוש העליון כדי למצוא אותו.
חיפוש של fin_monthly_closing_internal. בוחרים את שם הטבלה ב-BigQuery בתוצאות כדי לפתוח את דף הפרטים שלה.
בקטע 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 ומגדירים את מיומנות הסוכן.

התקנת הפלאגין 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

אימות התקנת הפלאגין ב-CLI

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

/mcp

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

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

הרצת תרחישים לאימות הקשר של הנתונים

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

תרחיש 1: אחזור נתונים ברמת הזהב המאושרת

האם 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

הסרת המשאבים

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

אם אתם בסשן של Antigravity CLI, יוצאים מהסשן על ידי לחיצה על Ctrl+C פעמיים או הקלדה של /quit.
מריצים את סקריפט הניקוי כדי להרוס את הטבלאות, מערכי הנתונים וסוגי ההיבטים של Knowledge Catalog שנוצרו במדריך הזה:
```
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
```
מסירים את תוסף השירות ומסירים את קובצי ההדגמה המקומיים:
```
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

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

אפשר לנסות תרחישי שימוש אחרים ב-Knowledge Catalog.