با استفاده از فراداده‌های کاتالوگ دانش، یک پایگاه داده بسازید

۱. مقدمه

مدل‌های هوش مصنوعی مولد، استدلال‌کنندگان قدرتمندی هستند، اما فاقد زمینه نهادی هستند. اگر یک مدیر اجرایی از یک عامل هوش مصنوعی بپرسد: «درآمد سه‌ماهه اول ما چقدر است؟»، آن عامل ممکن است ده‌ها جدول با نام «درآمد» در سراسر دریاچه داده شما پیدا کند. برخی گزارش‌های مالی دقیق هستند، برخی دیگر تخمین‌های بازاریابی در زمان واقعی هستند و بسیاری احتمالاً سندباکس‌های منسوخ‌شده‌ای هستند.

بدون زمینه‌سازی صریح، یک عامل هوش مصنوعی جدولی را بر اساس شباهت نام ساده انتخاب می‌کند که منجر به پاسخ‌های « به‌طور متقاعدکننده‌ای اشتباه » حاصل از داده‌های تأییدنشده می‌شود.

این آزمایشگاه کد بخشی از یک مجموعه دو قسمتی است که به بررسی چگونگی ساخت یک عامل هوش مصنوعی آگاه از حاکمیت می‌پردازد.

در بخش اول، شما یک پایه داده ایجاد خواهید کرد. شما یک دریاچه داده واقع‌گرایانه و "نامرتب" را در BigQuery راه‌اندازی خواهید کرد، برچسب‌های متادیتای سفت و سخت (جنبه‌های کاتالوگ دانش) را برای تمایز داده‌های معتبر از نویز اعمال خواهید کرد و از رابط خط فرمان Antigravity (AGY) برای آزمایش محلی اینکه آیا عامل به طور دقیق از قوانین مدیریت داده‌های شما پیروی می‌کند یا خیر، استفاده خواهید کرد.

می‌توانید بخش دوم این مجموعه را بخوانید که نحوه‌ی استقرار نمونه‌ی اولیه‌ی عامل محلی در یک برنامه‌ی وب امن و در سطح سازمانی را با استفاده از پروتکل Model Context (MCP) و Cloud Run پوشش می‌دهد. 👉 بخش ۲ را بخوانید

آنچه یاد خواهید گرفت

• با استفاده از یک اسکریپت راه‌اندازی، یک دریاچه داده چندلایه واقع‌بینانه مستقر کنید.
• قالب‌های فراداده سفارشی ( انواع جنبه‌ها ) را در کاتالوگ دانش طراحی و ثبت کنید تا محصولات داده رسمی را از جداول خام جعبه شنی متمایز کنید.
• قبل از نوشتن هرگونه کد برنامه، قوانین مدیریت داده‌ها را به صورت محلی با استفاده از AGY CLI تأیید کنید.

آنچه نیاز دارید

• یک پروژه گوگل کلود با قابلیت پرداخت.
• دسترسی به Google Cloud Shell (خط فرمان AGY در Cloud Shell از قبل نصب شده است).
• آشنایی و درک اولیه با BigQuery و Knowledge Catalog .

مفاهیم کلیدی

• کاتالوگ دانش: سرویس مدیریت یکپارچه فراداده. ما از آن برای غنی‌سازی فراداده‌های فنی (طرحواره‌ها) با زمینه کسب‌وکار (مدیریت) استفاده می‌کنیم.
• نوع جنبه (Aspect Type ): یک الگوی فراداده ساختاریافته. برخلاف تگ‌های متن آزاد، جنبه‌ها تایپ قوی (enums، booleans) را اعمال می‌کنند و ارزیابی آنها را برای ماشین‌ها قابل اعتماد می‌کنند.

۲. تنظیمات و الزامات

شروع پوسته ابری

اگرچه می‌توان از راه دور و از طریق لپ‌تاپ، گوگل کلود را مدیریت کرد، اما در این آزمایشگاه کد، از گوگل کلود شل ، یک محیط خط فرمان که در فضای ابری اجرا می‌شود، استفاده خواهید کرد.

از کنسول گوگل کلود ، روی آیکون Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

آماده‌سازی و اتصال به محیط فقط چند لحظه طول می‌کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

این ماشین مجازی با تمام ابزارهای توسعه‌ای که نیاز دارید، مجهز شده است. این ماشین مجازی یک دایرکتوری خانگی پایدار ۵ گیگابایتی ارائه می‌دهد و روی فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود می‌بخشد. تمام کارهای شما در این آزمایشگاه کد را می‌توان در یک مرورگر انجام داد. نیازی به نصب چیزی ندارید.

مقداردهی اولیه محیط

Cloud Shell را باز کنید و متغیرهای پروژه خود را تنظیم کنید تا مطمئن شوید که همه دستورات زیرساخت صحیح را هدف قرار می‌دهند.

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

فعال کردن APIها

برای اجرای دستورالعمل زیر، سرویس‌های ابری گوگل مورد نیاز را فعال کنید.

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

مخزن را کلون کنید

کد زیرساخت و اسکریپت‌های اتوماسیون را از مخزن گیت‌هاب دریافت کنید. برای صرفه‌جویی در فضای دیسک در 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

دریاچه داده «نامرتب» را بسازید

محیط‌های داده دنیای واقعی به ندرت تمیز هستند. برای شبیه‌سازی واقعیت، به ترکیبی از پایگاه‌های داده «رسمی» و جداول «جعبه شنی» غیرقابل اعتماد نیاز داریم.

ما از یک اسکریپت راه‌اندازی برای استقرار مجموعه داده‌ها و جداول BigQuery استفاده خواهیم کرد.

1. اسکریپت راه‌اندازی را قابل اجرا کنید و آن را اجرا کنید. این کار سه مجموعه داده BigQuery ( finance_mart ، marketing_prod ، analyst_sandbox ) ایجاد می‌کند و جداول آنها را با داده‌های نمونه پر می‌کند.

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

نقطه بازرسی : اکنون شما یک دریاچه داده کاملاً پرجمعیت اما کاملاً بدون مدیریت دارید. برای یک هوش مصنوعی، هر جدول دقیقاً یکسان به نظر می‌رسد.

۳. ایجاد الگوی مدیریت داده (نوع جنبه)

اکنون، برخی از قوانین مدیریت داده‌ها را تعریف خواهیم کرد. در کاتالوگ دانش، این کار با ایجاد یک نوع جنبه انجام می‌شود که یک الگوی فراداده با نوع‌بندی قوی و قابل استفاده مجدد است.

ما این الگو را با استفاده از 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 زیر را برای ثبت این الگو در رجیستری کاتالوگ دانش خود اجرا کنید.

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"

۴. اعمال حاکمیت

این مرحله مهندسی حیاتی است. در حال حاضر، جدول finance_mart.fin_monthly_closing_internal و analyst_sandbox.tmp_data_dump_v2_final_real کاملاً مشابه یک LLM به نظر می‌رسند. آنها فقط اشیاء با ستون هستند.

به عنوان یک مهندس مدیریت، شما باید یک جنبه (یک برچسب ابرداده گواهی‌شده) را به این جداول اضافه کنید تا آنها را از هم متمایز کنید. در یک سازمان واقعی، شما این کار را از طریق خطوط لوله CI/CD خودکار می‌کنید. ما این خودکارسازی را با اسکریپت‌ها شبیه‌سازی خواهیم کرد.

ایجاد پیلودهای مدیریتی

کلیدهای جنبه‌های کاتالوگ دانش باید به صورت جهانی منحصر به فرد باشند (با پیشوند شناسه پروژه شما). اسکریپت ./generate_payloads.sh به صورت پویا فایل‌های فراداده YAML را تولید می‌کند.

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

خروجی:

این یک پوشه "./aspect_payloads" ایجاد می‌کند که شامل ۴ فایل YAML است و سناریوهای مدیریتی (طلایی/داخلی، طلایی/عمومی، نقره‌ای/بلادرنگ، برنزی/سندباکس) را تعریف می‌کند.

اعمال جنبه‌ها با CLI

قبل از اجرای اسکریپت، بیایید نگاهی به آنچه که در واقع برای رفع ابهام از فرآیند اعمال می‌کنیم، بیندازیم. دستور زیر را اجرا کنید تا ساختار بار داده داخلی امور مالی را مشاهده کنید:

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. صفحه « کاتالوگ دانش » را در کنسول گوگل کلود باز کنید. اگر «کاتالوگ دانش» را در منوی ناوبری سمت چپ نمی‌بینید، از نوار جستجو در بالای پنجره کنسول گوگل کلود استفاده کنید، «کاتالوگ دانش» را تایپ کنید و نتیجه را در قسمت «نتایج برتر» یا «محصولات و صفحات» انتخاب کنید.
2. عبارت fin_monthly_closing_internal را جستجو کنید. باید جدول BigQuery را در نتایج مشاهده کنید. برای ورود به صفحه جزئیات آن، روی نام جدول کلیک کنید.

3. در صفحه جزئیات جدول، به دنبال بخش « برچسب‌ها و جنبه‌های اختیاری » که در پایین قرار دارد، بگردید.
4. شما جنبه official-data-product-spec را خواهید یافت. تأیید کنید که مقادیر با سناریوی « طلایی داخلی » که اعمال کرده‌ایم، مطابقت دارند.

اکنون تأیید کرده‌اید که جداول BigQuery که از نظر فنی یکسان هستند ( fin_monthly_closing_internal و tmp_data_dump_v2_final_real ) منطقاً توسط فراداده‌های قابل خواندن توسط ماشین از هم متمایز می‌شوند.

۵. پیکربندی و نمونه‌سازی اولیه عامل

قبل از ساخت برنامه (که در بخش ۲ انجام خواهیم داد)، منطق مدیریت داده‌های خود را به صورت محلی تأیید خواهیم کرد. باید افزونه Knowledge Catalog را نصب کرده و Agent Skill را پیکربندی کنیم.

افزونه را نصب کنید

در 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 قرار دارد. این فایل شامل منطقی است که قوانین انتزاعی انسانی (مثلاً "من به داده‌های ایمن نیاز دارم") را به جستجوهای فنی دقیق ترجمه می‌کند.

برای درک الگوریتمی که به هوش مصنوعی آموزش می‌دهیم، فایل را بررسی کنید:

cat .agents/skills/knowledge_catalog_governance/SKILL.md

توجه داشته باشید که این به صراحت به مدل دستور می‌دهد که از یک حلقه‌ی فاز ۱ (تأیید فراداده) و فاز ۲ (اجرای پرس‌وجو) پیروی کند. مدل باید قبل از ساخت هرگونه SQL، فراداده را کشف و تأیید کند.

شروع به کار عامل و آزمایش سناریوها

جلسه AGY CLI را شروع کنید. این برنامه به طور خودکار مهارت را از دایرکتوری .agents/skills کشف و بارگذاری می‌کند.

agy

توجه: ممکن است چندین فایل متنی در حال بارگذاری باشند. این طبیعی است. رابط خط فرمان، مهارت محلی مربوط به قوانین خاص این پروژه، به علاوه دستورالعمل‌های پیش‌فرض برای خود افزونه Knowledge Catalog را بارگذاری می‌کند.

تأیید نصب

برای تأیید فعال بودن افزونه Knowledge Catalog، عبارت /mcp را تایپ کنید. باید knowledge-catalog به عنوان یک افزونه فعال به همراه ابزارهای موجود آن مشاهده کنید.

/mcp

خروجی مورد انتظار:

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

سناریوهای آزمایشی (نمونه‌سازی اولیه)

دستورات زیر را یکی یکی در جلسه عامل در حال اجرا قرار دهید تا تأیید کنید که از قوانین شما پیروی می‌کند.

💡 نکته: در صورت درخواست، گزینه «۲. بله، و همیشه به «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 داده‌های مالی اولویت می‌دهد.

• سناریوی D (آزمایش در محیط سندباکس):

"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 (داده‌های خام) مطابقت دارد و در جنبه (Aspect) خود is_certified: false (محیط sandbox) مطابقت دارد.

(برای خروج از جلسه AGY، عبارت /exit یا /quit را تایپ کنید)

۶. تبریک می‌گویم! قدم بعدی چیست؟

شما با موفقیت یک پایه داده‌ی تحت کنترل ایجاد کرده‌اید و ثابت کرده‌اید که یک هوش مصنوعی می‌تواند با استفاده از یک نمونه‌ی اولیه‌ی رابط خط فرمان محلی، قوانین فراداده‌ی شما را به طور دقیق دنبال کند!

حالا به یک نقطه‌ی بازرسی رسیده‌اید. لطفاً مرحله‌ی بعدی خود را انتخاب کنید:

گزینه الف: می‌خواهم همین الان به بخش دوم بروم!

اگر آماده‌اید که این نمونه اولیه محلی را با استفاده از پروتکل Model Context (MCP) و Cloud Run به یک برنامه وب امن و در سطح تولید تبدیل کنید:

👉 لینک به بخش دوم Codelab

⚠️ توقف: مراحل پاکسازی زیر را اجرا نکنید. برای بخش دوم به تنظیمات فعلی داده‌ها و کاتالوگ دانش خود نیاز دارید!

گزینه ب: بخش دوم را بعداً انجام می‌دهم یا فقط می‌خواستم بخش اول را تمام کنم.

اگر می‌خواهید همین امروز دست از کار بکشید و از هزینه‌های ابری جلوگیری کنید، باید منابع خود را پاکسازی کنید.

نگران نباشید! در بخش دوم، ما یک «اسکریپت سریع» ارائه خواهیم داد که محیط بخش اول را تنها در عرض ۲ دقیقه به طور کامل برای شما بازسازی می‌کند تا بتوانید دقیقاً از همان جایی که متوقف شده بودید، ادامه دهید.

👉 به بخش پاکسازی بروید.

۷. تمیزکاری (فقط برای گزینه ب)

اگر اینجا توقف می‌کنید، منابع را از بین ببرید تا از پرداخت هزینه‌ها جلوگیری کنید.

دریاچه داده را نابود کنید

اگر در حال حاضر در جلسه 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