تثبيت Toolbox وإعداده لتطبيقات الذكاء الاصطناعي العام والتطبيقات المستندة إلى موظّفي الدعم على AlloyDB

1. نظرة عامة

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

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

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

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

إمكانية المراقبة من البداية إلى النهاية: مقاييس وتتبُّع فوريَين مع ميزة مدمجة متوافقة مع OpenTelemetry

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

ما ستُنشئه

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

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

المتطلبات

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

2. قبل البدء

إنشاء مشروع

1. في Google Cloud Console، في صفحة أداة اختيار المشاريع، اختَر مشروعًا على Google Cloud أو أنشِئه.
2. تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع.
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. اختَر CREATE CLUSTER (إنشاء مجموعة) من هذه الصفحة:

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

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

4. عند اختيار الشبكة التلقائية، ستظهر لك شاشة مثل الشاشة أدناه. انقر على "إعداد الاتصال" (SET UP CONNECTION).
   
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. فعِّل هذه الإضافات من خلال تنفيذ عبارات 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. سيتم ملء الحقول الأخرى لاحقًا في هذا الدرس التطبيقي.

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

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

منح الإذن

نفِّذ العبارة أدناه لمنح المستخدم 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 واكتب لغة الاستعلامات البنيوية التالية:

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- إجراء بحث في Vector

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

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

"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. يمكنك العثور على جميع مقاييس التشابه المتاحة في مستندات pgvector.
4. نحن بصدد تحويل نتيجة طريقة التضمين إلى نوع متجه لجعلها متوافقة مع المتجهات المخزّنة في قاعدة البيانات.
5. يشير LIMIT 5 إلى أنّنا نريد استخراج 5 جيران أقرب لنص البحث.

تظهر النتيجة على النحو التالي:

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

7- إعداد AlloyDB للتفاعل مع Toolbox

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

1. انتقِل إلى مثيل AlloyDB، وانقر على "تعديل" للانتقال إلى صفحة "تعديل المثيل الأساسي".
2. انتقِل إلى قسم "إمكانية الاتصال بعنوان IP المتاح للجميع"، وضَع علامة في مربّع الاختيار "تفعيل عنوان IP المتاح للجميع" وأدخِل عنوان IP لجهاز Cloud Shell.
3. للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى Cloud Shell Terminal وأدخِل ifconfig. من النتيجة، حدِّد عنوان inet الخاص بـ eth0 واستبدِل آخر رقمين بـ 0.0 مع حجم قناع "‎/16". على سبيل المثال، سيظهر على النحو التالي: "XX.XX.0.0/16" حيث يكون XX أرقامًا.
4. الصِق عنوان IP هذا في مربّع نص "الشبكات" للشبكات الخارجية المعتمَدة في صفحة تعديل المثيل.

5. انقر على "تعديل النسخة" عند الانتهاء.

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

8. تثبيت "صندوق الأدوات"

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

mkdir toystore

cd toystore

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

# 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

3. بدِّل إلى "محرِّر 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;

لقد تم ضبط تعريف الأداة.

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

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

./toolbox --tools_file "tools.yaml"

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

9. نشر "صندوق الأدوات" باستخدام Cloud Run

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

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

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

10. ربط تطبيقك بـ Toolbox

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

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

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

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

# 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 لجعله لا يستخدِم خادمًا.

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

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

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

{

               "`search`"`:` "`White plush toy`"

}

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

12. تهانينا

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