1. نظرة عامة
في الجزء 1، نجحنا في تحويل ملفات PDF غير المنظَّمة والفوضوية إلى جداول نظيفة وذكية ومنظَّمة في BigQuery باستخدام Knowledge Catalog وDataScan. لدينا الآن مستودع بيانات قوي. في الجزء 2، أعددنا AlloyDB كعمود فقري للمعاملات ودمجنا جداول BigQuery فيه، ما أدّى إلى إنشاء طبقة بيانات موحّدة بدون تكرار أي بايت واحد.
اليوم، سننشئ العقل. سننشئ تطبيقًا متعدد الوكلاء، وهو "مدير متجر FroyoOS"، الذي يستند إلى طبقة البيانات هذه للإجابة عن الأسئلة والتحقّق من المواد المسبّبة للحساسية ومعالجة الطلبات المباشرة.
التحدي: فصل الذكاء الاصطناعي عن الوكيل
عند إنشاء وكيل ذكاء اصطناعي يحتاج إلى التحدّث إلى قواعد البيانات، يكون النمط غير المرغوب فيه الأكثر شيوعًا هو فرض البيانات ومنطق الذكاء الاصطناعي مباشرةً في تطبيق Python. يؤدي ذلك إلى جعل تطبيقك هشًا وغير آمن ويصعب جدًا صيانته مع نمو بنية بياناتك.
لحلّ هذه المشكلة، سنستخدم خادم MCP Toolbox. يعمل خادم MCP Toolbox كطبقة تجريد بيانات موحّدة. نحدّد عمليات قاعدة البيانات بشكل إعلاني في ملف tools.yaml بسيط. ننشر خادم MCP Toolbox هذا كنقطة نهاية آمنة بدون خادم على Google Cloud Run. يتصل وكيل الذكاء الاصطناعي ببساطة بنقطة النهاية هذه ويقول: "نفِّذ أداة "place_order"".
قوة HTAP
قبل أن نبدأ في إنشاء الوكيل، لنتحدّث عن سبب استخدام عنوان هذه المشاركة عبارة HTAP (المعالجة المختلطة للمعاملات والتحليل) تحديدًا.
في بنية تقليدية، إذا احتاج وكيل الذكاء الاصطناعي إلى معالجة طلب مباشر من المستخدم (حِمل عمل OLTP للمعاملات) والمقارنة بين مصادر بيانات متعددة لآلاف عمليات الربط المعقّدة للمكوّنات (حِمل عمل OLAP التحليلي)، سيتعين على تطبيق Python إدارة عمليات الاتصال بقاعدتَي بيانات مختلفتَين تمامًا. يؤدي ذلك إلى حدوث تأخير شديد وزيادة في تكاليف الأمان وإدارة غير مستقرة للحالة.
لقد حوّلنا AlloyDB إلى مصدر قوة HTAP من خلال دمج مستودع بيانات BigQuery مباشرةً في PostgreSQL. بسبب بنية HTAP هذه، يحتاج وكيل الذكاء الاصطناعي اليوم إلى التحدّث إلى نقطة نهاية واحدة لقاعدة البيانات فقط. يمكنه إدراج معاملات مباشرة في جدول live_orders وإجراء عمليات فحص تحليلية مكثفة على مجموعة بيانات BigQuery المدمجة froyo_data في الوقت نفسه تمامًا، بدون تكرار أي بايت واحد من البيانات. لنطّلع على كيفية عرض هذا المحرّك على الذكاء الاصطناعي.
لنبدأ في إنشاء المحتوى
أهداف الدورة التعليمية
- كيفية إعداد مجموعة AlloyDB ومثيلها وشبكتها بنقرة زر
- كيفية إعداد الإضافة للتحضير لعملية الدمج
- كيفية إعداد عملية الدمج من BigQuery إلى AlloyDB
- اختبار ذلك
المتطلبات
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
- تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعّلة في مشروع.
- ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل على Google Cloud. انقر على تفعيل Cloud Shell في أعلى Google Cloud Console.
- بعد الاتصال بـ Cloud Shell، تحقَّق من أنّك قد تم التحقّق من هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:
gcloud auth list
- شغِّل الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.
gcloud config list project
- إذا أردت المصادقة
gcloud auth login
- إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- فعِّل واجهات برمجة التطبيقات المطلوبة: شغِّل هذا الأمر لتفعيل جميع واجهات برمجة التطبيقات المطلوبة:
gcloud services enable \
alloydb.googleapis.com \
bigquery.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com \
compute.googleapis.com \
servicenetworking.googleapis.com
المشاكل الشائعة وتحديد المشاكل وحلّها
متلازمة "المشروع الوهمي" | لقد شغّلت الأمر |
حاجز الفوترة | لقد فعّلت المشروع، ولكنك نسيت حساب الفوترة. AlloyDB هو محرّك عالي الأداء، ولن يبدأ إذا كان "خزان الوقود" (الفوترة) فارغًا. |
تأخير انتشار واجهة برمجة التطبيقات | لقد نقرت على "تفعيل واجهات برمجة التطبيقات"، ولكن سطر الأوامر لا يزال يعرض |
مستنقعات الحصص | إذا كنت تستخدم حسابًا تجريبيًا جديدًا تمامًا، قد تصل إلى حصة إقليمية لمثيلات AlloyDB. إذا تعذّر استخدام |
3. إعداد البيانات
تأكَّد من توفّر البيانات المنظَّمة التي استخرجناها من ملفات PDF غير المنظَّمة في BigQuery، ومن إعداد عملية دمج بيانات BigQuery في AlloyDB واختبارها أيضًا. إذا لم تكن قد أكملت هذه الخطوات، هذا هو الوقت المناسب للانتقال إلى هنا و هنا وتنفيذ هذه الخطوات البسيطة للجزأين 1 و2 على التوالي.
ملاحظة:
إذا كنت تجرب هذا الدرس التطبيقي حول الترميز، عليك عدم تنفيذ خطوة التنظيف في الجزء 2 (خطوة حذف المجموعة والمثيل) لأننا نحتاج إلى تنسيق AlloyDB للنظام المستنِد إلى الذكاء الاصطناعي الوكيل الموضّح هنا.
بالإضافة إلى هذه البيانات التي أنشأناها في الجزء 2، نحتاج إلى إنشاء جدول إضافي واحد في مثيل AlloyDB. انتقِل إلى AlloyDB Studio باستخدام الرابط:
https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio
غيِّر اسم المجموعة في الرابط أعلاه إذا كنت تستخدم مجموعة مختلفة.
في AlloyDB Studio، في علامة تبويب "محرّر طلبات البحث" جديدة، شغِّل العبارة التالية:
CREATE TABLE live_orders (
order_id SERIAL PRIMARY KEY,
customer_name VARCHAR(100),
product_id VARCHAR(100),
quantity INT,
order_status VARCHAR(50) DEFAULT 'Pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
من المفترض أن يؤدي ذلك إلى إنشاء جدول live_orders في قاعدة بياناتك.
4. تحديد التجريد (ملف tools.yaml)
أولاً، نسجّل رسميًا عمليات قاعدة البيانات. ننشئ ملف tools.yaml يحدّد كيفية تفاعل الوكيل مع AlloyDB الذي يحتوي على بيانات المعاملات والبيانات التحليلية (البيانات التحليلية من عملية دمج BigQuery).
- انتقِل إلى وحدة طرفية في Cloud Shell. بدِّل إلى "وضع المحرّر".
- أنشِئ مجلدًا جديدًا في الدليل الجذر: "froyo-agent"
- داخل المجلد، أنشِئ ملف tools.yaml والصِق المحتوى التالي: (استبدِل القيم الخاصة بك للمشروع والمجموعة والمثيل وكلمة المرور)
# tools.yaml
sources:
alloydb-source:
kind: "alloydb-postgres"
project: "*******"
region: "us-central1"
cluster: "my-alloydb-cluster"
instance: "my-primary-inst"
database: "postgres"
user: "postgres"
password: "*******"
ipType: "private"
tools:
check_allergens:
kind: postgres-sql
source: alloydb-source
description: Queries the federated BigQuery tables to find allergens for a product.
statement: |
SELECT a.allergen_name
FROM consistsof c
INNER JOIN product p ON c.product_id = p.product_id
INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
WHERE UPPER(p.product_name) LIKE UPPER($1)
parameters:
- name: product_name
type: string
description: The name of the product to check. (e.g., '%Midnight%')
place_order:
kind: postgres-sql
source: alloydb-source
description: Inserts a new live transaction into the native AlloyDB orders table.
statement: |
INSERT INTO live_orders (customer_name, product_id, quantity)
VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
parameters:
- name: customer_name
type: string
description: The name of the customer placing the order.
- name: product_name
type: string
description: The name of the product being ordered.
- name: quantity
type: integer
description: The quantity of the product being ordered.
toolsets:
alloydb_tools:
- check_allergens
- place_order
لقد حدّدنا إمكانات الوكيل بأداتَين: التحقّق من المواد المسبّبة للحساسية وتقديم الطلب.
5. نشر خادم MCP Toolbox على Cloud Run
لإتاحة ذلك لتطبيقنا، ننشر خادم MCP Toolbox بشكل آمن باستخدام gcloud CLI. يؤدي ذلك إلى إنشاء نقطة نهاية لطبقة التجريد.
- بدِّل إلى وحدة طرفية في Cloud Shell، وانتقِل إلى دليل العمل عن طريق تشغيل الأمر:
cd froyo-agent
- احفَظ ملف tools.yaml في سر باسم "tools-froyo":
gcloud secrets create tools-froyo --data-file=tools.yaml
- انشر حاوية خادم MCP Toolbox على Cloud Run
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox-froyo \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-froyo:latest" \
--args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--network easy-alloydb-vpc \
--subnet easy-alloydb-subnet \
--allow-unauthenticated \
--vpc-egress private-ranges-only
يجب استبدال قيمتَي "الشبكة" و"الشبكة الفرعية" إذا كنت قد استخدمت قيمًا مختلفة عن القيم التي ضبطناها في الدرس التطبيقي حول الترميز في الجزء 2.
- دوِّن عنوان URL الناتج على Cloud Run (مثلاً، https://toolbox-froyo-xxx.run.app).
سنستخدم نقطة نهاية خادم MCP Toolbox المنشورة هذه في خطوة إعداد الوكيل.
6. الواجهة الخلفية المستنِدة إلى الذكاء الاصطناعي الوكيل (app.py)
بعد تجريد قاعدة البيانات، يمكن أن يركّز رمز Python بالكامل على التنسيق والاستنتاج.
نستخدم حزمة تطوير الوكلاء (ADK) جنبًا إلى جنب مع Flask. توفّر حزمة تطوير الوكلاء ذاكرة جلسة على مستوى المؤسسة (InMemorySessionService)، ما يعني أنّ الوكيل يتذكر سياق المحادثة. تتكامل حزمة تطوير الوكلاء بشكل أساسي مع ToolboxSyncClient لجلب أدواتنا بسلاسة من Cloud Run.
إليك ملف app.py:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py
يربط تطبيق Python Flask البسيط وكيل حزمة تطوير الوكلاء بالأدوات التي حدّدناها في خادم MCP Toolbox الذي يتفاعل بدوره مع AlloyDB (والبيانات المدمجة في BigQuery أيضًا) ويستجيب للمستخدم.
للحصول على هذا المشروع في "محرّر Cloud Shell"، يمكنك استنساخ مستودع الوكيل عن طريق تشغيل الأوامر التالية من "وحدة طرفية في Cloud Shell":
cd
git clone https://github.com/AbiramiSukumaran/froyo-data
من المفترض أن تظهر بنية المشروع التالية:
خطوات مواصلة تجربة البيانات بدون حساب الفوترة:
- تتوفّر ملفات البيانات التالية في المستودع لتسهيل الوصول إليها:
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.allergen.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.consistsof.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.containsallergen.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.froyo_data_materialized.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.ingredient.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.product.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.suppliedby.csv
- https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.supplier.csv
يجب أن تكون هذه الملفات موجودة في المجلد نفسه الذي يحتوي على ملف app.py.
ب. ملف Python باسم app-nobill.py في المسار نفسه
- في المجلد الجذر للمشروع، يوجد ملف باسم app-nobill.py
- تم تصميم هذا الملف لإنشاء تجربة التطبيق نفسها ولكن بدون الحاجة الصريحة إلى الاتصال بمصادر البيانات هذه لأنّ البيانات أصبحت متاحة في الملفات.
- يجب أن تظل جميع الملفات الأخرى كما هو مذكور في المختبر سليمة لهذا الإصدار أيضًا (ما عليك سوى عدم تنفيذ ملف app.py)
7. واجهة المستخدم وتشغيل التطبيق
لمنح مديري المتجر تجربة مناسبة، أنشأنا واجهة مستخدم أنيقة ذات تأثير زجاجي (templates/index.html) تتضمّن شريطًا جانبيًا لعرض كتالوج المنتجات المباشر وواجهة محادثة تفاعلية.
يمكنك العثور على ملف index.html في ملف المستودع هنا:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html
قبل تشغيل التطبيق، تأكَّد من توفّر التبعيات في ملف requirements.txt بالمحتوى التالي:
Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv
وملف .env الذي تم ملؤه:
GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***
كيفية الحصول على GOOGLE_API_KEY
اتّبِع التعليمات الواردة في هذه المدونة لإعداد مفتاح Google API.
كيفية الحصول على MCP_TOOLBOX_SERVER_URL
لقد أعددنا ذلك في الخطوة السابقة في هذا الدرس التطبيقي حول الترميز ونسخت نقطة نهاية خادم MCP Toolbox المنشورة. استخدِم هذا الرابط لمتغيّر البيئة MCP_TOOLBOX_SERVER_URL.
شغِّل تطبيقك:
من "وحدة طرفية في Cloud Shell"، تأكَّد من أنّك في مجلد المشروع، وشغِّل الأوامر التالية واحدًا تلو الآخر:
انتقِل إلى المجلد الجذر للمشروع:
cd froyo-data
ثبِّت التبعيّات:
pip install -r requirements.txt
تنفيذ ملف Python:
python app.py
انقر على الرابط الذي يظهر في الوحدة الطرفية أو افتح http://localhost:8080.
8. الاختبار النهائي
لننقر على منتج من الكتالوج لنسأل الوكيل:
Does Midnight Swirl have any allergens?
من المفترض أن تظهر لك الاستجابة التالية:
لقطات من وراء الكواليس:
- يتلقّى وكيل حزمة تطوير الوكلاء الطلب ويقرّر استخدام أداة check_allergens.
- يستدعي خادم MCP Toolbox بشكل آمن على Cloud Run.
- ينفّذ خادم MCP Toolbox طلب البحث في AlloyDB، الذي يدمج على الفور مع BigQuery لفحص العلاقات المعقّدة التي أنشأناها في الجزء 1.
- تعرض قاعدة البيانات "Soy"، التي يلخّصها الوكيل بدقة في واجهة المستخدم.
بعد ذلك، نقول:
Order 2 Midnight Swirl for Alice.
يمرر الوكيل السلسلة "Midnight Swirl" إلى خادم MCP Toolbox. يحلّ SQL الأساسي السلسلة ديناميكيًا إلى رقم تعريف عدد صحيح من خلال BigQuery، ويُدرج الطلب المباشر في AlloyDB، ويؤكّد المعاملة.
مستودع الرموز
9. تَنظيم
بعد إكمال هذا المختبر، لا تنسَ حذف مجموعة AlloyDB ومثيلها.
من المفترض أن يؤدي ذلك إلى تنظيف المجموعة مع مثيلاتها.
10. تهانينا على الوكيل الذي أنشأته.
لنفكّر في ما أنجزناه للتو:
يتفاعل نظامنا المستنِد إلى الذكاء الاصطناعي الوكيل والمنسّق جيدًا مع خادم MCP Toolbox لقواعد البيانات فقط. يعالج ذلك من وراء الكواليس استدعاء الأداة ومنطق البيانات إلى الذكاء الاصطناعي لتطبيقنا، ما يحافظ على بساطة التدفق:
- يمكن لتطبيق المعاملات (الذي يعمل على AlloyDB) معالجة جلسات المستخدمين السريعة والمتزامنة.
- عندما يحتاج إلى بيانات تحليلية مكثفة أو سياق سابق (مثل تفاصيل المورّد أو عمليات الربط المعقّدة للمكوّنات)، يستعلم عن مخطط froyo_data في BigQuery.
- لا حاجة إلى عملية ETL. لا تنقطع مسارات البيانات. لا توجد قواعد بيانات غير متزامنة. نخزّن البيانات مرة واحدة (في BigQuery) ونحسبها عند الحاجة.
بعد إكمال الوكيل وأساس البيانات، سواء التحليلية أو الخاصة بالمعاملات، لننتقل إلى الجزء التالي.
ما الخطوة التالية؟
يعمل الوكيل بشكل مثالي... في المسار السعيد. في الجزء 4، سننشئ مسار تقييم الوكيل لاختبار صحة نظامنا المستنِد إلى الذكاء الاصطناعي الوكيل وأدائه وأساسه بدقة. يسعدنا انضمامك إلينا.