لمحة عن هذا الدرس التطبيقي حول الترميز
1. نظرة عامة
MCP Toolbox for Databases هو خادم مفتوح المصدر من Google يسهِّل إنشاء أدوات الذكاء الاصطناعي التوليدي للتفاعل مع قواعد البيانات. ويتيح لك تطوير الأدوات بسهولة أكبر وأسرع وأمان أكبر من خلال التعامل مع التعقيدات، مثل تجميع الاتصالات والمصادقة وغير ذلك. يساعدك على إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتيح لوكلاءك الوصول إلى البيانات في قاعدة بياناتك. يوفّر "مربّع الأدوات" ما يلي:
التطوير المبسّط: يمكنك دمج الأدوات لوكيلك في أقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين وكلاء أو أُطر عمل متعدّدة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.
أداء أفضل: يمكنك الاطّلاع على أفضل الممارسات، مثل تجميع الاتصال والمصادقة وغير ذلك.
إعدادات أمان محسّنة: يمكنك الحصول على مصادقة مُدمجة للوصول إلى بياناتك بشكل أكثر أمانًا.
إمكانية الملاحظة من البداية إلى النهاية: تتوفّر مقاييس جاهزة للاستخدام مع ميزة التتبُّع مع دعم مضمّن لأداة OpenTelemetry.
يقع "صندوق الأدوات" بين إطار عمل تنسيق تطبيقك وقاعدة بياناتك، ما يوفر خطة تحكّم تُستخدَم لتعديل الأدوات أو توزيعها أو تشغيلها. ويبسّط هذا الإجراء إدارة أدواتك من خلال تزويدك بموقع مركزي لتخزين الأدوات وتعديلها، ما يتيح لك مشاركة الأدوات بين موظّفي الدعم والتطبيقات وتعديل هذه الأدوات بدون إعادة نشر تطبيقك بالضرورة.
ما الذي ستقوم ببنائه
وفي إطار هذا التمرين، ستنشئ تطبيقًا يستخدم أداة لتنفيذ طلب قاعدة بيانات بسيط (AlloyDB) يمكن استدعاؤه من الوكيل أو من تطبيق الذكاء الاصطناعي التوليدي. لهذا السبب، سوف
- تثبيت مجموعة أدوات MCP لقواعد البيانات
- إعداد الأداة (المصمّمة لتنفيذ مهمة في AlloyDB) على خادم "مجموعة الأدوات"
- نشر مجموعة أدوات MCP لقواعد البيانات على تشغيل السحابة الإلكترونية
- اختبار الأداة باستخدام نقطة نهاية Cloud Run الخاصة بها
- إنشاء دالة التشغيل في السحابة الإلكترونية لاستدعاء مجموعة الأدوات
المتطلبات
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، في صفحة أداة اختيار المشاريع، اختَر مشروعًا على Google Cloud أو أنشِئه.
- تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع.
- ستستخدم Cloud Shell، وهي بيئة سطر أوامر يتم تشغيلها في Google Cloud. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".
- بعد الربط بخدمة Cloud Shell، تحقَّق مما إذا تمت مصادقتك وما إذا كان المشروع مضبوطًا على رقم تعريف المشروع الصحيح باستخدام الأمر التالي:
gcloud auth list
- شغِّل الأمر التالي في Cloud Shell للتأكّد من أنّ الأمر gcloud يعرف مشروعك.
gcloud config list project
- إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
gcloud config set project <YOUR_PROJECT_ID>
- يمكنك تفعيل واجهات برمجة التطبيقات المطلوبة عن طريق تشغيل الأوامر التالية واحدًا تلو الآخر في الوحدة الطرفية في 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 ومثيل وجدول يتم فيه تحميل مجموعة بيانات التجارة الإلكترونية.
إنشاء مجموعة ومثيل
- انتقِل إلى صفحة AlloyDB في Cloud Console.
من الطرق السهلة للعثور على معظم الصفحات في Cloud Console البحث عنها باستخدام شريط البحث في وحدة التحكّم.
- اختَر "إنشاء مجموعة" من هذه الصفحة:
- ستظهر لك شاشة مثل التي تظهر أدناه. أنشِئ مجموعة ومثيل باستخدام القيم التالية (تأكَّد من تطابق القيم في حال استنساخ رمز التطبيق من المستودع):
- معرّف المجموعة: "
vector-cluster" - كلمة المرور: "
alloydb" - التوافق مع PostgreSQL 15
- المنطقة: "
us-central1" - جارٍ الاتصال بالشبكات: "
default"
- عند اختيار الشبكة التلقائية، ستظهر لك شاشة مثل التي تظهر أدناه. انقر على "إعداد الاتصال".
- من هناك، حدد "استخدام نطاق IP مخصَّص تلقائيًا" ثم انقر على "متابعة". بعد مراجعة المعلومات، انقر على "إنشاء اتصال".
- بعد إعداد الشبكة، يمكنك مواصلة إنشاء المجموعة. انقر على إنشاء مجموعة لإكمال إعداد المجموعة كما هو موضح أدناه:
تأكَّد من تغيير رقم تعريف المثيل إلى ".
vector-instance"
.
يُرجى العلم أنّ إنشاء المجموعة سيستغرق حوالى 10 دقائق. وبعد اكتمالها، من المفترض أن تظهر لك شاشة تعرض النظرة العامة للمجموعة التي أنشأتها للتو.
4. نقل البيانات
حان الوقت الآن لإضافة جدول يحتوي على بيانات حول المتجر. انتقِل إلى AlloyDB واختَر المجموعة الأساسية ثم AlloyDB Studio:
قد تحتاج إلى الانتظار حتى يتم الانتهاء من إنشاء المثيل. وبعد إكمال هذه الخطوة، سجِّل الدخول إلى AlloyDB باستخدام بيانات الاعتماد التي أنشأتها أثناء إنشاء المجموعة. استخدام البيانات التالية للمصادقة مع PostgreSQL:
- اسم المستخدم: "
postgres" - قاعدة البيانات: "
postgres" - كلمة المرور: "
alloydb"
بعد مصادقة تطبيق AlloyDB Studio بنجاح، يمكن إدخال أوامر SQL في المحرر. يمكنك إضافة نوافذ "محرِّر" متعددة باستخدام علامة الجمع على يسار النافذة الأخيرة.
يمكنك إدخال أوامر لتطبيق AlloyDB في نوافذ التحرير، باستخدام الخيارات "تشغيل" و"تنسيق" و"محو" حسب الضرورة.
تفعيل الإضافات
لإنشاء هذا التطبيق، سنستخدم الإضافتَين pgvector وgoogle_ml_integration. تسمح لك إضافة pgect بتخزين تضمينات المتجهات والبحث فيها. توفّر الإضافة google_ml_integration الوظائف التي تستخدمها للوصول إلى نقاط نهاية توقّعات Vertex AI للحصول على توقّعات في SQL. فعِّل هذه الإضافات عن طريق تشغيل الروابط المؤدّية إلى محتوى (DDL) التالية:
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 في علامة تبويب "Editor" (المحرر) الجديدة.
منح الإذن
شغِّل العبارة أدناه لمنح المستخدم postgres حقوق التنفيذ في دالة embedding:
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;
دعنا نلقي نظرة على هذا الاستعلام بالتفصيل:
في هذا الاستعلام،
- نص بحث المستخدم هو: "
I want a white plush teddy bear toy with a floral pattern." - ونحن بصدد تحويلها إلى تضمينات في الطريقة
embedding()باستخدام النموذج:text-embedding-005. من المفترض أن تبدو هذه الخطوة مألوفة بعد الخطوة الأخيرة، حيث طبقنا دالة التضمين على كل العناصر في الجدول. - تشير القيمة "
<=>" إلى استخدام طريقة المسافة COSINE SIMILARITY. يمكنك العثور على جميع مقاييس التشابه المتاحة في مستندات المتجهات. - نقوم بتحويل نتيجة طريقة التضمين إلى نوع متجه لجعلها متوافقة مع المتجهات المخزنة في قاعدة البيانات.
- LIMIT 5 يمثل أننا نريد استخراج 5 من الجيران الأقرب لنص البحث.
تظهر النتيجة على النحو التالي:
وكما تلاحظ في نتائجك، فإن النتائج المطابِقة قريبة جدًا من نص البحث. جرِّب تغيير النص للاطّلاع على كيفية تغيير النتائج.
7. إعداد AlloyDB لتفاعل صندوق الأدوات
استعدادًا لإعداد "مجموعة الأدوات"، لنفعِّل إمكانية اتصال عنوان IP العلني في مثيل AlloyDB حتى تتمكّن الأداة الجديدة من الوصول إلى قاعدة البيانات.
- انتقِل إلى مثيل AlloyDB، وانقر على "تعديل" (EDIT) وانتقِل إلى صفحة "تعديل المثيل الأساسي".
- انتقِل إلى قسم "اتصال عنوان IP العلني"، وضع علامة في مربّع الاختيار "تفعيل عنوان IP العلني"، وأدخِل عنوان IP لجهاز Cloud Shell.
- للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى Cloud Shell Terminal وأدخِل الأمر ifconfig. من النتيجة، حدِّد عنوان eth0 inet واستبدِل آخر رقمَين بـ 0.0 بحجم القناع " /16". على سبيل المثال، ستبدو على الشكل التالي "XX.XX.0.0/16" حيث XX هي أرقام.
- الصق عنوان IP هذا في المربع النصي "الشبكات الخارجية المسموح بها" في صفحة تعديل النسخة الافتراضية.
- انقر على "تحديث الحدث" بعد الانتهاء.
سيستغرق إكمال هذه الخطوة بضع دقائق.
8. مجموعة أدوات MCP لتثبيت قواعد البيانات
- يمكنك إنشاء مجلد مشروع لتخزين تفاصيل الأداة. في هذه الحالة، نظرًا لأننا نعمل على بيانات متجر الألعاب، لننشئ مجلدًا باسم "toystore" وننتقل إليه. انتقِل إلى Cloud Shell Terminal وتأكَّد من اختيار مشروعك وعرضه في رسالة المطالبة على الوحدة الطرفية. شغّل الأمر أدناه من الوحدة الطرفية في Cloud Shell:
mkdir toystore
cd toystore
- شغّل الأمر أدناه لتنزيل صندوق الأدوات وتثبيته في المجلد الجديد:
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
- انقر على مفتاح التبديل إلى محرِّر Cloud Shell. وسِّع المجلد الذي تم إنشاؤه حديثًا "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;
تم إعداد تعريف الأداة!
لمزيد من التفاصيل حول ضبط tool.yaml، ارجع إلى هذه الوثائق.
- بدِّل إلى "محطة Cloud Shell" وأدخِل الأمر التالي لبدء خادم صندوق الأدوات في ضبط الأدوات:
./toolbox --tools_file "tools.yaml"
- إذا فتحت الخادم الآن في وضع معاينة الويب على السحابة الإلكترونية، سيظهر لك خادم "مجموعة الأدوات" وهو قيد التشغيل بأداتك الجديدة المسماة
get-toy-price..
9. نشر مجموعة أدوات MCP لقواعد البيانات باستخدام Cloud Run
لننشره في Cloud Run حتى تتمكن من استخدام هذه الأداة على أرض الواقع.
- اتّبِع التعليمات الواردة في هذه الصفحة واحدًا تلو الآخر حتى تصل إلى الأمر
gcloud run deploy toolboxفي النقطة الثالثة ضمن القسم "النشر إلى تشغيل السحابة الإلكترونية". ستحتاج إلى الخيار الأول وليس الخيار الثاني المخصّص عند استخدام طريقة شبكة VPC. - وبعد النشر بنجاح، ستتلقّى نقطة نهاية تم تفعيلها من خلال "تشغيل السحابة الإلكترونية" لخادم "مجموعة الأدوات". ويمكنك اختباره باستخدام أمر CURL.
ملاحظات:
اتّبِع التعليمات الواردة في الصفحة بعناية ولا تفوِّت هذه المعلومات.
يمكنك الآن استخدام الأداة التي تم تفعيلها مؤخرًا في تطبيق الوكيل.
10. ربط تطبيقك بمجموعة أدوات MCP لقواعد البيانات
في هذا الجزء، سننشئ تطبيقًا صغيرًا لاختبار أداتك للتفاعل مع احتياجات التطبيق واسترداد الاستجابة.
- انتقِل إلى Google Colab وافتَح ورقة ملاحظات جديدة.
- قم بتشغيل ما يلي في دفتر ملاحظاتك
!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)
- يُفترض أن تظهر لك على النحو التالي:
هذه هي الأداة التي يتم استدعاؤها صراحةً في أحد تطبيقات Python التي تستخدم مجموعة الأدوات toolbox-langchain.
- إذا أردت استخدام هذه الأداة وربطها بوكيل داخل تطبيق LangGraph، يمكنك إجراء ذلك بسهولة باستخدام مجموعة الأدوات
langgraph. - يمكنك الرجوع إلى مقتطفات الرمز لإجراء ذلك.
11. نقل إلى السحابة الإلكترونية!!!
لنلتفّ مقتطف رمز Python هذا في دوال تشغيل السحابة الإلكترونية لنجعله بدون خادم.
- انسخ المصدر من مجلد مستودع الرموز للحصول على دوال Cloud.
- انتقِل إلى وحدة تحكّم دوال تشغيل السحابة الإلكترونية وانقر على "إنشاء وظيفة".
- اجعله غير مُصدَّق عليه للتطبيق التجريبي وحدد وقت تشغيل Python 3.11 في الصفحة التالية.
- انسخ الملفَّين
main.pyوrequirements.txtمن مستودع المصدر الذي تمّت مشاركته في الخطوة 1 والصقهما في الملفات المعنيّة. - استبدِل عنوان URL للخادم في main.py بعنوان URL للخادم.
- انشر الدالة وستكون لديك نقطة نهاية REST لأداة توقع السعر للوصول إليها في تطبيق ويب toystore.
- يجب أن تظهر نقطة النهاية على النحو التالي:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- يمكنك اختباره مباشرةً على وحدة تحكم Cloud Functions من خلال الانتقال إلى علامة تبويب "الاختبار" وإدخال ما يلي كإدخال للطلب:
{
"search": "White plush toy"
}
- انقر على "اختبار الوظيفة" أو شغِّله في Cloud Shell Terminal أيًا كنت تريد استخدامه. من المفترض أن ترى النتيجة على اليسار ضمن العنوان "الإخراج":
12. تهانينا
تهانينا! لقد نجحت في إنشاء أداة قوية ومفصَّلة يمكن أن تتفاعل مع بعضها البعض على مستوى قواعد البيانات والمنصات وأُطر عمل تنسيق الذكاء الاصطناعي التوليدي للمساعدة في إنشاء تطبيقك الوكيل.