بناء أسس البيانات باستخدام البيانات الوصفية في Knowledge Catalog

1. مقدمة

تتميّز نماذج الذكاء الاصطناعي التوليدي بقدرتها الفائقة على الاستنتاج، ولكنّها تفتقر إلى السياق المؤسسي. إذا سأل أحد المسؤولين التنفيذيين وكيل الذكاء الاصطناعي: "ما هي إيراداتنا في الربع الأول؟"، قد يعثر الوكيل على عشرات الجداول التي تحمل الاسم "الإيرادات" في مستودع البيانات المركزي. بعضها تقارير مالية دقيقة، وبعضها الآخر تقديرات تسويقية في الوقت الفعلي، والعديد منها عبارة عن بيئات اختبار قديمة.

بدون تحديد المصدر بشكل صريح، سيختار وكيل الذكاء الاصطناعي جدولاً استنادًا إلى تشابه بسيط في الأسماء، ما يؤدي إلى تقديم إجابات "مقنعة ولكنها خاطئة" مستمدة من بيانات لم يتم التحقّق منها.

هذا الدرس التطبيقي حول الترميز هو جزء من سلسلة مؤلّفة من جزأين تستكشف كيفية إنشاء وكيل مستند إلى الذكاء الاصطناعي ومدرك للحوكمة.

في هذا الجزء الأول، ستنشئ أساسًا للبيانات. ستعمل على إعداد مستودع بيانات واقعي "غير منظَّم" في BigQuery، وتطبيق علامات بيانات وصفية صارمة (جوانب Knowledge Catalog) للتمييز بين البيانات الصالحة والبيانات غير المرغوب فيها، واستخدام واجهة سطر الأوامر (CLI) الخاصة بأداة Antigravity (AGY) لاختبار ما إذا كان الوكيل يلتزم بدقة بقواعد إدارة البيانات.

يمكنك الاطّلاع على الجزء الثاني من هذه السلسلة الذي يوضّح كيفية نشر النموذج الأوّلي للوكيل المحلي في تطبيق ويب آمن ومناسب للمؤسسات باستخدام بروتوكول Model Context Protocol (MCP) وCloud Run. 👉 قراءة الجزء 2

أهداف الدورة التعليمية

  • يمكنك نشر بحيرة بيانات واقعية ومتعددة المستويات باستخدام نص التهيئة البرمجي.
  • صمِّم نماذج بيانات وصفية مخصّصة وسجِّلها (أنواع الجوانب) في Knowledge Catalog للتمييز بين منتجات البيانات الرسمية وجداول وضع الحماية الأولية.
  • تحقَّق من قواعد إدارة البيانات محليًا باستخدام AGY CLI قبل كتابة أي رمز برمجي للتطبيق.

المتطلبات

  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • الوصول إلى Google Cloud Shell (تكون واجهة سطر الأوامر AGY مثبَّتة مسبقًا في Cloud Shell)
  • فهم أساسي لخدمتَي BigQuery وKnowledge Catalog والإلمام بهما

المفاهيم الرئيسية

  • Knowledge Catalog: هي خدمة موحّدة لإدارة البيانات الوصفية. نستخدمها لإثراء البيانات الوصفية الفنية (المخططات) بسياق النشاط التجاري (الإدارة).
  • نوع الجانب: هو نموذج بيانات وصفية منظَّمة. على عكس علامات النص الحر، تفرض الجوانب الكتابة القوية (التعدادات، والقيم المنطقية)، ما يجعلها موثوقة بالنسبة إلى الآلات لتقييمها.

2. الإعداد والمتطلبات

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

تفعيل Cloud Shell

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

لقطة شاشة لواجهة سطر الأوامر في Google Cloud Shell توضّح أنّه تم ربط البيئة

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا دائمًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. لست بحاجة إلى تثبيت أي تطبيق.

إعداد البيئة

افتح Cloud Shell واضبط متغيرات مشروعك لضمان استهداف جميع الأوامر للبنية الأساسية الصحيحة.

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

تفعيل واجهات برمجة التطبيقات

فعِّل خدمات 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

إنشاء مستودع البيانات "غير المنظَّم"

من النادر أن تكون بيئات البيانات في العالم الحقيقي نظيفة. لمحاكاة الواقع، نحتاج إلى مزيج من مستودعات البيانات "الرسمية" وجداول "وضع التجربة" غير الموثوق بها.

سنستخدم نص التهيئة البرمجي لنشر مجموعات بيانات وجداول BigQuery.

  1. اجعل نص التهيئة البرمجي قابلاً للتنفيذ وشغِّله. سيؤدي ذلك إلى إنشاء ثلاث مجموعات بيانات في BigQuery (finance_mart وmarketing_prod وanalyst_sandbox) وتعبئة جداولها ببيانات نموذجية.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

نقطة التحقّق: لديك الآن مستودع بيانات مركزي مملوء بالكامل، ولكنّه غير خاضع لأي إدارة. بالنسبة إلى الذكاء الاصطناعي، تبدو جميع الجداول متطابقة تمامًا.

3- إنشاء نموذج إدارة البيانات (نوع العنصر)

الآن، سنحدّد بعض قواعد إدارة البيانات. في "كتالوج المعرفة"، يتم ذلك من خلال إنشاء نوع عنصر، وهو نموذج بيانات تعريف قابل لإعادة الاستخدام ومحدّد النوع بدقة.

سنُسجّل هذا النموذج باستخدام واجهة سطر الأوامر gcloud حتى تتمكّن من الاطّلاع على طريقة تعريفه.

فحص مخطط الجوانب

أدخِل محتوى 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"

4. تطبيق الحوكمة

هذه هي الخطوة الهندسية المهمة. في الوقت الحالي، يبدو الجدولان finance_mart.fin_monthly_closing_internal وanalyst_sandbox.tmp_data_dump_v2_final_real متطابقَين بالنسبة إلى نموذج لغوي كبير. وهي مجرد كائنات تحتوي على أعمدة.

بصفتك مهندس حوكمة، عليك إرفاق سمة (تصنيف بيانات وصفية معتمَد) بهذه الجداول للتمييز بينها. في مؤسسة حقيقية، يمكنك تنفيذ ذلك تلقائيًا من خلال عمليات CI/CD. سنحاكي عملية التشغيل الآلي هذه باستخدام النصوص البرمجية.

إنشاء حمولات إدارة

يجب أن تكون مفاتيح جوانب "كتالوج المعرفة" فريدة على مستوى العالم (يجب أن تبدأ برقم تعريف مشروعك). سينشئ النص البرمجي ./generate_payloads.sh ملفات البيانات الوصفية بتنسيق YAML بشكل ديناميكي.

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

الناتج:

يؤدي هذا الأمر إلى إنشاء مجلد "./aspect_payloads" يحتوي على 4 ملفات YAML تحدّد سيناريوهات الحوكمة (Gold/Internal وGold/Public وSilver/Realtime وBronze/Sandbox).

تطبيق الجوانب باستخدام واجهة سطر الأوامر

قبل تشغيل النص البرمجي، لنلقِ نظرة على ما نطبّقه فعليًا لإزالة الغموض عن العملية. نفِّذ الأمر التالي للاطّلاع على بنية حمولة البيانات المالية الداخلية:

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. تزويد النموذج اللغوي الكبير بقواعد واضحة ومنظَّمة لتقييمها بدلاً من التخمين استنادًا إلى أسماء الجداول فقط

الآن، شغِّل نص تطبيق البرنامج. يتم تكرار ذلك في جداول BigQuery وتنفيذ الأمر gcloud dataplex entries update لإرفاق هذه البيانات الوصفية الثابتة.

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

إثبات الملكية (اختياري)

قبل المتابعة، تأكَّد من تطبيق البيانات الوصفية بشكل صحيح في وحدة التحكّم.

  1. افتح صفحة Knowledge Catalog في Google Cloud Console. إذا لم يظهر "كتالوج المعرفة" في قائمة التنقّل على يمين الصفحة، استخدِم شريط البحث في أعلى نافذة Google Cloud Console، واكتب "كتالوج المعرفة"، ثم اختَر النتيجة ضمن "أهم النتائج" أو "المنتجات والصفحات".
  2. ابحث عن "fin_monthly_closing_internal". يجب أن يظهر جدول BigQuery في النتائج. انقر على اسم الجدول للانتقال إلى صفحة التفاصيل.

13d068a8cd0bfda9.png

  1. في صفحة تفاصيل الجدول، ابحث عن قسم العلامات والجوانب الاختيارية في أسفل الصفحة.
  2. ستظهر لك السمة official-data-product-spec. تأكَّد من أنّ القيم تتطابق مع سيناريو Gold Internal الذي طبّقناه.

56726f62e1ac311a.png

لقد أكّدت الآن أنّ جداول BigQuery المتطابقة فنيًا (fin_monthly_closing_internal وtmp_data_dump_v2_final_real) يتم تمييزها منطقيًا من خلال البيانات الوصفية القابلة للقراءة آليًا.

5- إعداد الوكيل وإنشاء نموذج أولي له

قبل إنشاء تطبيق (وهو ما سنفعله في الجزء 2)، سنتأكّد من صحة منطق إدارة البيانات محليًا. علينا تثبيت المكوّن الإضافي "كتالوج المعرفة" وإعداد "مهارة الوكيل".

تثبيت الإضافة

في 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

يُرجى العِلم أنّها توجّه النموذج صراحةً إلى اتّباع حلقة صارمة من المرحلة 1 (التحقّق من البيانات الوصفية) والمرحلة 2 (تنفيذ طلب البحث). يجب أن يكتشف النموذج البيانات الوصفية ويتأكّد منها قبل إنشاء أي SQL.

بدء تشغيل الوكيل واختبار السيناريوهات

ابدأ جلسة AGY CLI. سيكتشف المساعد المهارة ويحمّلها تلقائيًا من دليل .agents/skills.

agy

ملاحظة: قد تلاحظ تحميل ملفات سياق متعددة. هذا أمر طبيعي. تحمّل واجهة سطر الأوامر المهارة المحلية لقواعد هذا المشروع المحددة، بالإضافة إلى التعليمات التلقائية الخاصة بمكوّن Knowledge Catalog الإضافي نفسه.

التحقق من التثبيت

اكتب /mcp للتأكيد على أنّ المكوّن الإضافي "كتالوج المعرفة" نشط. من المفترض أن يظهر knowledge-catalog كإضافة نشطة مع الأدوات المتاحة.

/mcp

الناتج المتوقّع:

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

سيناريوهات الاختبار (وضع النماذج الأولية)

الصِق الطلبات التالية في جلسة الوكيل النشطة واحدةً تلو الأخرى للتأكّد من أنّها تلتزم بقواعدك.

  • السيناريو (أ) (إثبات صحة بيانات المدير المالي):
"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 (اجتماع مجلس الإدارة) في Aspect، ويقترحه.

  • السيناريو (ب) (الإفصاح العلني):
"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 (بيئة وضع الحماية) في Aspect.

(للخروج من جلسة AGY، اكتب /exit أو /quit)

6. تهانينا! ما هي الخطوات التالية؟

لقد أنشأت بنجاح أساسًا محكومًا للبيانات وأثبتّ أنّ الذكاء الاصطناعي يمكنه اتّباع قواعد البيانات الوصفية بدقة باستخدام نموذج أولي لواجهة سطر الأوامر المحلية.

لقد بلغت الآن نقطة إنجاز. يُرجى اختيار الخطوة التالية:

الخيار "أ": أريد الانتقال إلى الجزء 2 الآن.

إذا كنت مستعدًا لتحويل هذا النموذج الأوّلي المحلي إلى تطبيق ويب آمن ومناسب للإنتاج باستخدام "بروتوكول سياق النموذج" (MCP) وCloud Run، اتّبِع الخطوات التالية:

👉 رابط إلى الجزء 2 من الدرس التطبيقي حول الترميز

الخيار "ب": سأكمل الجزء 2 لاحقًا أو أردتُ إكمال الجزء 1 فقط.

إذا أردت التوقف اليوم وتجنُّب تكاليف السحابة الإلكترونية، عليك تنظيف مواردك.

لا داعي للقلق. في الجزء 2، سنقدّم "نصًا برمجيًا سريعًا" يعيد إنشاء بيئة الجزء 1 بالكامل في غضون دقيقتَين فقط، ما يتيح لك المتابعة من حيث توقّفت تمامًا.

👉 انتقِل إلى قسم "التنظيف".

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