1. نظرة عامة
في الجزء 1، نجحنا في تحويل ملفات PDF غير المنظَّمة والفوضوية إلى جداول نظيفة وذكية ومنظَّمة في BigQuery باستخدام Knowledge Catalog وDataScan. وأصبح لدينا الآن مستودع بيانات قوي. في الجزء 2، أعددنا AlloyDB كعمود فقري للمعاملات ودمجنا جداول BigQuery فيه، ما أدّى إلى إنشاء طبقة بيانات موحّدة بدون تكرار أي بايت واحد.
اليوم، سننشئ العقل. سننشئ تطبيقًا متعدد الوكلاء، وهو "مدير متجر FroyoOS"، الذي يستند إلى طبقة البيانات هذه للإجابة عن الأسئلة والتحقّق من مسبّبات الحساسية ومعالجة الطلبات المباشرة.
التحدي: فصل الذكاء الاصطناعي عن الوكيل
عند إنشاء وكيل ذكاء اصطناعي يحتاج إلى التحدّث إلى قواعد البيانات، يكون النمط غير المرغوب فيه الأكثر شيوعًا هو فرض البيانات ومنطق الذكاء الاصطناعي مباشرةً في تطبيق Python. يؤدي ذلك إلى جعل تطبيقك هشًا وغير آمن ويصعب جدًا صيانته مع توسّع بنية بياناتك.
لحلّ هذه المشكلة، سنستخدم أداة Model Context Protocol (MCP) Toolbox. تعمل أداة MCP Toolbox كطبقة تجريد بيانات موحّدة. نحدّد عمليات قاعدة البيانات بشكل تصريحي في ملف tools.yaml بسيط. ننشر هذه الأداة كنقطة نهاية آمنة وبدون خادم على 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. نشر الأداة على Cloud Run
لإتاحة هذه الأداة لتطبيقنا، ننشرها بأمان باستخدام 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).
6. الواجهة الخلفية المستندة إلى الذكاء الاصطناعي الوكيل (app.py)
بعد تجريد قاعدة البيانات، يمكن أن يركّز رمز Python بالكامل على التنسيق والاستنتاج.
نستخدم حزمة تطوير الوكلاء (ADK) جنبًا إلى جنب مع Flask. توفّر حزمة تطوير الوكلاء ذاكرة الجلسة على مستوى المؤسسة (InMemorySessionService)، ما يعني أنّ الوكيل يتذكّر سياق المحادثة. تتكامل حزمة تطوير الوكلاء بشكل أساسي مع ToolboxSyncClient لجلب أدواتنا بسلاسة من Cloud Run.
إليك app.py:
https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py
يربط تطبيق Python Flask البسيط وكيل حزمة تطوير الوكلاء بالأدوات التي حدّدناها في Toolbox والتي تتفاعل بدورها مع AlloyDB (والبيانات المدمجة في BigQuery أيضًا) وتستجيب للمستخدم.
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=***
من وحدة طرفية في Cloud Shell، تأكَّد من أنّك في مجلد المشروع، وشغِّل الأوامر التالية واحدًا تلو الآخر:
ثبِّت التبعيّات:
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.
- تنفّذ الأداة طلب البحث في AlloyDB، الذي يتكامل على الفور مع BigQuery لفحص العلاقات المعقّدة التي أنشأناها في الجزء 1.
- تعرض قاعدة البيانات "الصويا"، التي يلخّصها الوكيل بدقة في واجهة المستخدم.
بعد ذلك، نقول:
Order 2 Midnight Swirls for Alice.
يمرر الوكيل السلسلة "Midnight Swirl" إلى Toolbox. يحلّ SQL الأساسي السلسلة ديناميكيًا إلى رقم تعريف عدد صحيح من خلال BigQuery، ويُدرج الطلب المباشر في AlloyDB، ويؤكّد المعاملة.
مستودع الرموز
9. تَنظيم
بعد إكمال هذا المختبر، لا تنسَ حذف مجموعة AlloyDB ومثيلها.
من المفترض أن يؤدي ذلك إلى تنظيف المجموعة مع مثيلاتها.
10. تهانينا على الوكيل
لنفكّر في ما أنجزناه للتو:
يتفاعل نظامنا المستند إلى الذكاء الاصطناعي الوكيل والمنسّق جيدًا مع MCP Toolbox لقواعد البيانات فقط. تتعامل هذه الأداة وراء الكواليس مع استدعاء الأداة ومنطق البيانات إلى الذكاء الاصطناعي لتطبيقنا، ما يحافظ على بساطة التدفق:
- يمكن لتطبيق المعاملات (الذي يعمل على AlloyDB) معالجة جلسات المستخدمين السريعة والمتزامنة.
- عندما يحتاج إلى بيانات تحليلية مكثّفة أو سياق سابق (مثل تفاصيل المورّد أو عمليات الربط المعقّدة للمكوّنات)، يستعلم عن مخطط froyo_data في BigQuery.
- لا حاجة إلى عملية ETL. لا تتعطّل مسارات البيانات. لا توجد قواعد بيانات غير متزامنة. نخزّن البيانات مرة واحدة (في BigQuery) ونحسبها عند الحاجة.
بعد إكمال الوكيل وأساس البيانات، سواء التحليلية أو الخاصة بالمعاملات، لننتقل إلى الجزء التالي.
الخطوات اللاحقة
يعمل الوكيل بشكل مثالي... في المسار السعيد. في الجزء 4، سننشئ مسار تقييم الوكيل لاختبار صحة نظامنا المستند إلى الذكاء الاصطناعي الوكيل وأدائه وتحديد مصدره بدقة. يسعدنا انضمامك إلينا.