تثبيت وإعداد مجموعة أدوات MCP لقواعد البيانات الخاصة بالذكاء الاصطناعي التوليدي والتطبيقات الوكلاء على AlloyDB

1. نظرة عامة

‫MCP Toolbox for Databases هو خادم مفتوح المصدر من Google يسهّل إنشاء أدوات الذكاء الاصطناعي التوليدي للتفاعل مع قواعد البيانات. تتيح لك هذه الخدمة تطوير الأدوات بسهولة أكبر وبسرعة أكبر وبشكل أكثر أمانًا من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك. تساعدك هذه الأداة في إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتيح للوكلاء الوصول إلى البيانات في قاعدة بياناتك. توفّر مجموعة الأدوات ما يلي:

تطوير مبسط: يمكنك دمج الأدوات في برنامجك الآلي باستخدام أقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين برامج آلية أو أُطر متعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.

أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك

أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا

إمكانية تتبُّع البيانات الشاملة: مقاييس وتتبُّع جاهزة للاستخدام مع دعم مدمج لـ OpenTelemetry

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

ما ستنشئه

في إطار هذا المختبر، ستنشئ تطبيقًا يستخدم أداة لتنفيذ طلب بحث بسيط في قاعدة بيانات (AlloyDB) يمكن استدعاؤه من الوكيل أو تطبيق الذكاء الاصطناعي التوليدي. لذلك، عليك

1. تثبيت MCP Toolbox for Databases
2. إعداد الأداة (المصمَّمة لتنفيذ مهمة في AlloyDB) على خادم Toolbox
3. نشر MCP Toolbox for Databases على Cloud Run
4. اختبار الأداة باستخدام نقطة نهاية Cloud Run التي تم نشرها
5. إنشاء دالة Cloud Run لاستدعاء "صندوق الأدوات"

المتطلبات

• متصفّح، مثل Chrome أو Firefox
• مشروع Google Cloud تم تفعيل الفوترة فيه (الخطوات في القسم التالي)

2. قبل البدء

إنشاء مشروع

1. في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع.
3. ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".

4. بعد الاتصال بـ Cloud Shell، تحقَّق مما إذا تمّت مصادقتك وما إذا تم ضبط المشروع على رقم تعريف المشروع الصحيح باستخدام الأمر التالي:

gcloud auth list

5. نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

6. إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

7. فعِّل واجهات برمجة التطبيقات المطلوبة من خلال تنفيذ الأوامر التالية واحدًا تلو الآخر في "وحدة Cloud Shell الطرفية":

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

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

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

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

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

3- إعداد قاعدة البيانات

في هذا الدرس التطبيقي، سنستخدم AlloyDB كقاعدة بيانات للاحتفاظ ببيانات البيع بالتجزئة. يستخدم المجموعات للاحتفاظ بجميع الموارد، مثل قواعد البيانات والسجلات. تحتوي كل مجموعة على مثيل أساسي يوفّر نقطة وصول إلى البيانات. ستحتوي الجداول على البيانات الفعلية.

لننشئ مجموعة ومثيل وجدول AlloyDB حيث سيتم تحميل مجموعة بيانات التجارة الإلكترونية.

إنشاء مجموعة ومثيل

1. انتقِل إلى صفحة AlloyDB في Cloud Console.

تتمثّل إحدى الطرق السهلة للعثور على معظم الصفحات في Cloud Console في البحث عنها باستخدام شريط البحث في وحدة التحكّم.

2. اختَر "إنشاء مجموعة" من تلك الصفحة:

3. ستظهر لك شاشة مشابهة للشاشة أدناه. أنشئ مجموعة ومثيل بالقيم التالية (تأكَّد من تطابق القيم في حال استنساخ الرمز البرمجي للتطبيق من المستودع):

• رقم تعريف المجموعة: "vector-cluster"
• كلمة المرور: "alloydb"
• متوافق مع PostgreSQL 15
• المنطقة: "us-central1"
• الشبكات: "default"

4. عند اختيار الشبكة الافتراضية، ستظهر لك شاشة مثل الشاشة أدناه. انقر على "إعداد الاتصال".
   
5. من هناك، اختَر "استخدام نطاق عناوين IP تم تخصيصه تلقائيًا" ثم انقر على "متابعة". بعد مراجعة المعلومات، انقر على "إنشاء ربط".
6. بعد إعداد شبكتك، يمكنك مواصلة إنشاء مجموعتك. انقر على CREATE CLUSTER (إنشاء مجموعة) لإكمال عملية إعداد المجموعة كما هو موضّح أدناه:

احرص على تغيير معرّف المثيل إلى "

vector-instance"

.

يُرجى العِلم أنّ إنشاء المجموعة سيستغرق حوالي 10 دقائق. بعد إتمام العملية بنجاح، من المفترض أن تظهر لك شاشة تعرض نظرة عامة على المجموعة التي أنشأتها للتو.

4. نقل البيانات

حان الوقت الآن لإضافة جدول يتضمّن بيانات حول المتجر. انتقِل إلى AlloyDB، واختَر المجموعة الأساسية، ثم AlloyDB Studio:

قد تحتاج إلى الانتظار إلى أن يكتمل إنشاء مثيلك. بعد اكتمالها، سجِّل الدخول إلى AlloyDB باستخدام بيانات الاعتماد التي أنشأتها أثناء إنشاء المجموعة. استخدِم البيانات التالية للمصادقة على PostgreSQL:

• اسم المستخدم : "postgres"
• قاعدة البيانات : "postgres"
• كلمة المرور : "alloydb"

بعد إكمال عملية المصادقة بنجاح في AlloyDB Studio، يمكن إدخال أوامر SQL في "المحرّر". يمكنك إضافة نوافذ "المحرّر" متعددة باستخدام علامة الجمع على يسار النافذة الأخيرة.

يمكنك إدخال أوامر AlloyDB في نوافذ المحرّر، باستخدام الخيارات "تشغيل" و"تنسيق" و"محو" حسب الحاجة.

تفعيل الإضافات

لإنشاء هذا التطبيق، سنستخدم الإضافتين pgvector وgoogle_ml_integration. تتيح لك إضافة pgvector تخزين عمليات التضمين المتجهة والبحث عنها. توفّر إضافة google_ml_integration دوال يمكنك استخدامها للوصول إلى نقاط نهاية التوقّع في Vertex AI من أجل الحصول على توقّعات في SQL. فعِّل هذه الإضافات من خلال تنفيذ تعريفات البيانات التالية:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

إذا أردت التحقّق من الإضافات التي تم تفعيلها في قاعدة البيانات، نفِّذ أمر SQL التالي:

select extname, extversion from pg_extension;

إنشاء جدول

أنشئ جدولاً باستخدام عبارة DDL أدناه:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

بعد تنفيذ الأمر أعلاه بنجاح، يجب أن تتمكّن من عرض الجدول في قاعدة البيانات.

نقل البيانات

في هذا التمرين العملي، لدينا بيانات اختبار تتضمّن حوالي 72 سجلاً في ملف SQL هذا. يحتوي على الحقول id, name, description, quantity, price, image_url. سيتم ملء الحقول الأخرى لاحقًا في الدرس التطبيقي.

انسخ الأسطر أو عبارات الإدراج من هناك، ثم الصِق هذه الأسطر في علامة تبويب محرِّر فارغة وانقر على "تنفيذ".

للاطّلاع على محتوى الجدول، وسِّع قسم "المستكشف" إلى أن يظهر الجدول باسم "الملابس". انقر على رمز النقاط الثلاث العمودية (⋮) للاطّلاع على خيار "طلب البحث في الجدول". سيتم فتح عبارة SELECT في علامة تبويب "المحرّر" جديدة.

منح الإذن

نفِّذ العبارة أدناه لمنح حقوق التنفيذ على الدالة embedding للمستخدم postgres:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

منح دور "مستخدم Vertex AI" لحساب خدمة AlloyDB

انتقِل إلى وحدة Cloud Shell الطرفية وأدخِل الأمر التالي:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5- إنشاء تضمينات للسياق

فمن الأسهل على أجهزة الكمبيوتر معالجة الأرقام مقارنةً بمعالجة النصوص. يحوّل نظام التضمين النص إلى سلسلة من الأرقام النقطية العائمة، تُعرف باسم عمليات التضمين المتجهة، والتي من المفترض أن تمثّل النص، بغض النظر عن صياغته أو اللغة المستخدَمة فيه أو غير ذلك.

على سبيل المثال، قد يُطلق على مكان يقع على شاطئ البحر اسم "على الماء" أو "على شاطئ البحر" أو "يمكنك المشي من غرفتك إلى المحيط" أو "sur la mer" أو "на берегу океана" وما إلى ذلك. تبدو هذه العبارات مختلفة، ولكن يجب أن يكون معناها الدلالي أو ما يُعرف في مصطلحات تعلّم الآلة باسم "التضمينات" قريبًا جدًا من بعضه البعض.

بعد أن أصبحت البيانات والسياق جاهزين، سننفّذ طلب SQL لإضافة تضمينات وصف المنتج إلى الجدول في الحقل embedding. تتوفّر مجموعة متنوعة من نماذج التضمين التي يمكنك استخدامها. نحن نستخدم text-embedding-005 من Vertex AI. احرص على استخدام نموذج التضمين نفسه طوال مدة المشروع.

ملاحظة: إذا كنت تستخدم مشروعًا قديمًا على Google Cloud، قد تحتاج إلى مواصلة استخدام إصدارات قديمة من نموذج تضمين النص، مثل textembedding-gecko.

ارجع إلى علامة التبويب AlloyDB Studio واكتب عبارة DML التالية:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

انظر إلى جدول toys مرة أخرى للاطّلاع على بعض التضمينات. احرص على إعادة تنفيذ عبارة SELECT للاطّلاع على التغييرات.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

من المفترض أن يعرض هذا الطلب متّجه التضمين الذي يبدو كصفيف من الأرقام العشرية، لوصف اللعبة كما هو موضّح أدناه:

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

6. إجراء بحث عن المتّجهات

بعد أن أصبح الجدول والبيانات والتضمينات جاهزة، لننفّذ الآن البحث المتّجه في الوقت الفعلي عن نص بحث المستخدم.

لنفترض أنّ المستخدم يسأل:

"I want a white plush teddy bear toy with a floral pattern".

يمكنك العثور على نتائج مطابقة لذلك من خلال تنفيذ طلب البحث أدناه:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

لنلقِ نظرة على هذا الاستعلام بالتفصيل:

في هذا الاستعلام،

1. نص البحث الذي أدخله المستخدم هو: "I want a white plush teddy bear toy with a floral pattern."
2. نحن نحولها إلى تضمينات باستخدام الطريقة embedding() والنموذج text-embedding-005. من المفترض أن تكون هذه الخطوة مألوفة بعد الخطوة الأخيرة، حيث طبّقنا دالة التضمين على جميع العناصر في الجدول.
3. يمثّل "<=>" استخدام طريقة قياس المسافة COSINE SIMILARITY. يمكنك العثور على جميع مقاييس التشابه المتاحة في مستندات pgvector.
4. نحوّل نتيجة طريقة التضمين إلى نوع متّجه لجعلها متوافقة مع المتّجهات المخزّنة في قاعدة البيانات.
5. يشير LIMIT 5 إلى أنّنا نريد استخراج 5 جيران أقرب لنص البحث.

تبدو النتيجة على النحو التالي:

كما تلاحظ في نتائجك، تكون المطابقات قريبة جدًا من نص البحث. جرِّب تغيير النص لمعرفة كيف تتغير النتائج.

7. إعداد AlloyDB للتفاعل مع مجموعة الأدوات

استعدادًا لإعداد Toolbox، لنفعِّل إمكانية الاتصال بعنوان IP علني في مثيل AlloyDB حتى تتمكّن الأداة الجديدة من الوصول إلى قاعدة البيانات.

1. انتقِل إلى آلة AlloyDB الافتراضية، وانقر على "تعديل" (EDIT)، ثم انتقِل إلى صفحة "تعديل الآلة الأساسية" (Edit primary instance).
2. انتقِل إلى قسم "الاتصال بعنوان IP علني" (Public IP connectivity)، وضَع علامة في المربّع "تفعيل عنوان IP علني" (Enable public IP)، ثم أدخِل عنوان IP لجهاز Cloud Shell.
3. للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى "وحدة Cloud Shell الطرفية" وأدخِل ifconfig. من النتيجة، حدِّد عنوان inet الخاص بـ eth0 واستبدِل آخر رقمَين بـ 0.0 مع حجم قناع "‎/16". على سبيل المثال، سيبدو على النحو التالي: "XX.XX.0.0/16" حيث XX هي أرقام.
4. ألصِق عنوان IP هذا في مربّع النص "الشبكات" ضمن "الشبكات الخارجية المعتمَدة" في صفحة تعديل المثيل.

5. انقر على "تعديل المثيل" بعد الانتهاء.

سيستغرق إكمال هذه الخطوة بضع دقائق.

8. تثبيت MCP Toolbox for Databases

1. يمكنك إنشاء مجلد مشروع لتخزين تفاصيل الأداة. في هذه الحالة، بما أنّنا نعمل على بيانات متجر ألعاب، لننشئ مجلدًا باسم "toystore" وننتقل إليه. انتقِل إلى وحدة Cloud Shell الطرفية وتأكَّد من اختيار مشروعك وعرضه في موجّه الوحدة الطرفية. نفِّذ الأمر التالي من "وحدة Cloud Shell الطرفية":

mkdir toystore

cd toystore

2. نفِّذ الأمر أدناه لتنزيل مجموعة الأدوات وتثبيتها في مجلدك الجديد:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. انتقِل إلى Cloud Shell Editor. وسِّع المجلد الذي تم إنشاؤه حديثًا "toystore" وأنشئ ملفًا جديدًا باسم tools.yaml. انسخ المحتوى أدناه. استبدِل YOUR_PROJECT_ID وتحقَّق مما إذا كانت جميع تفاصيل الاتصال الأخرى دقيقة.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

في هذه الأداة، نعثر على المنتج الأقرب إلى نص بحث المستخدم (وصف اللعبة المخصّصة) ونعرض سعره. يمكنك أيضًا تعديلها للعثور على متوسط سعر أفضل 5 ألعاب مطابقة:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

اكتملت عملية تحديد تعريف الأداة.

لمزيد من التفاصيل حول ضبط ملف tools.yaml، يُرجى الرجوع إلى هذه المستندات.

4. انتقِل إلى "وحدة طرفية Cloud Shell" وأدخِل الأمر التالي لبدء خادم مجموعة الأدوات باستخدام إعدادات أدواتك:

./toolbox --tools_file "tools.yaml"

5. الآن، إذا فتحت الخادم في وضع معاينة على الويب على السحابة الإلكترونية، من المفترض أن تتمكّن من رؤية خادم Toolbox يعمل مع أداتك الجديدة التي تحمل الاسم get-toy-price.

9- نشر MCP Toolbox for Databases على Cloud Run

لننشره على Cloud Run حتى تتمكّن من استخدامه فعليًا.

1. اتّبِع التعليمات الواردة في هذه الصفحة واحدة تلو الأخرى إلى أن تصل إلى الأمر gcloud run deploy toolbox الوارد في النقطة الثالثة ضمن القسم "النشر على Cloud Run". عليك استخدام الخيار الأول وليس الخيار الثاني الذي يُستخدَم عند استخدام طريقة شبكة VPC.
2. بعد نشرها بنجاح، ستتلقّى نقطة نهاية نشر Cloud Run لخادم "مجموعة الأدوات". اختبِرها باستخدام أمر CURL.

ملاحظات:

اتّبِع التعليمات الواردة في الصفحة بعناية ولا تفوّت أي خطوة.

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

10. ربط تطبيقك بأداة MCP Toolbox لقواعد البيانات

في هذا الجزء، سننشئ تطبيقًا صغيرًا لاختبار أداتك للتفاعل مع احتياجات التطبيق واسترداد الرد.

1. انتقِل إلى Google Colab وافتح دفتر ملاحظات جديدًا.
2. نفِّذ ما يلي في دفتر الملاحظات

!pip install toolbox-core
from toolbox_core import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

# Invoke the tool with a search text to pass as the parameter
 result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. يجب أن تظهر النتيجة على النحو التالي:

هذه هي الأداة التي يتم استدعاؤها بشكل صريح في تطبيق Python يستخدم مجموعة الأدوات toolbox-langchain.

4. إذا أردت استخدام هذه الأداة وربطها بوكيل ضمن تطبيق متكامل مع LangGraph، يمكنك إجراء ذلك بسهولة باستخدام مجموعة أدوات langgraph.
5. يمكنك الرجوع إلى مقتطفات الرموز لمعرفة المزيد.

11. انقلها إلى السحابة الإلكترونية!!!

لنغلف مقتطف رمز Python البرمجي هذا في Cloud Run Functions لجعله بلا خادم.

1. انسخ المصدر من مجلد مستودع الرموز البرمجية لنقل هذا المصدر إلى Cloud Functions.
2. انتقِل إلى وحدة تحكّم دوال Cloud Run وانقر على CREATE FUNCTION (إنشاء دالة).
3. اتركها بدون مصادقة لتطبيق العرض التوضيحي واختَر وقت تشغيل Python 3.11 في الصفحة التالية.
4. انسخ الملفَين main.py وrequirements.txt من مستودع المصدر المشترَك في الخطوة 1 والصقهما في الملفات المعنية.
5. استبدِل عنوان URL للخادم في ملف main.py بعنوان URL الخاص بخادمك.
6. يمكنك نشر الدالة، وبذلك تحصل على نقطة نهاية REST يمكن الوصول إليها في تطبيق الويب الخاص بمتجر الألعاب.
7. يجب أن تبدو نقطة النهاية على النحو التالي:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. يمكنك اختبارها مباشرةً على وحدة تحكّم Cloud Functions من خلال الانتقال إلى علامة التبويب TESTING وإدخال ما يلي كمدخل للطلب:

{

           "search": "White plush toy"

}

3. انقر على TEST THE FUNCTION أو شغِّل في Cloud Shell Terminal أيًّا كان ما تختاره لاستخدامه. من المفترض أن تظهر لك النتيجة على اليسار تحت العنوان "الناتج":

12. تهانينا

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