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

بدء استخدام ميزة "إدراج المتجهات" في Cloud SQL for MySQL

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام ميزة دمج الذكاء الاصطناعي في Cloud SQL for MySQL لإجراء بحث دلالي باستخدام التضمينات، وكيفية تحسين الأداء باستخدام فهرس على بيانات المتّجهات.

المتطلبات الأساسية

فهم أساسي لـ Google Cloud وGoogle Cloud Console
خبرة أساسية في استخدام واجهة سطر الأوامر وCloud Shell

ما ستتعلمه

كيفية نشر مثيل Cloud SQL لخدمة MySQL
كيفية إنشاء قاعدة بيانات وتفعيل تكامل الذكاء الاصطناعي في Cloud SQL
كيفية تحميل البيانات إلى قاعدة البيانات
كيفية استخدام Cloud SQL Studio
كيفية استخدام نموذج التضمين في Vertex AI في Cloud SQL
كيفية استخدام Agent Platform Studio
كيفية تحسين النتيجة باستخدام نموذج Gemini Enterprise Agent Platform
كيفية تحسين الأداء باستخدام فهرس المتّجه

المتطلبات

حساب Google Cloud ومشروع Google Cloud
متصفّح ويب، مثل Chrome

2. الإعداد والمتطلبات

إعداد المشروع

سجِّل الدخول إلى Google Cloud Console. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب Google.

استخدام حساب شخصي بدلاً من حساب تديره المؤسسة التعليمية أو حساب تابع للعمل.

أنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. لإنشاء مشروع جديد في Google Cloud Console، انقر على اختيار مشروع في شريط الأدوات.

في نافذة "اختيار مشروع"، انقر على الزر "مشروع جديد" الذي سيفتح مربّع حوار للمشروع الجديد.

في مربّع الحوار، أدخِل اسم المشروع واختَر الموقع الجغرافي.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. لا تستخدم Google APIs اسم المشروع، ويمكن تغييره في أي وقت.
رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره (لا يمكن تغييره بعد ضبطه). تنشئ وحدة تحكّم Google Cloud تلقائيًا معرّفًا فريدًا، ولكن يمكنك تخصيصه. إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر أو تقديم معرّفك الخاص للتحقّق من توفّره. في معظم دروس Codelab، يمكنك الرجوع إلى رقم تعريف مشروعك، والذي يتم تحديده عادةً باستخدام العنصر النائب .
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، وتستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في مستندات إنشاء المشاريع وإدارتها.

تفعيل الفوترة

لتفعيل الفوترة، لديك خياران. يمكنك استخدام حساب الفوترة الشخصي أو تحصيل قيمة الرصيد باتّباع الخطوات التالية.

تحصيل قيمة أرصدة Google Cloud (اختياري)

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

إعداد حساب فوترة شخصي

إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.

لإعداد حساب فوترة شخصي، فعِّل الفوترة في وحدة تحكّم الفوترة في Google Cloud.

ملاحظات:

لا تتجاوز تكلفة إكمال هذا الدرس التطبيقي 5 دولارات أمريكية من موارد Google Cloud.
اتّبِع الخطوات الواردة في نهاية هذا الدرس التطبيقي لحذف الموارد وتجنُّب فرض رسوم إضافية.
يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
يمكن للمستخدمين الجدد والحاليين البدء باستخدام Cloud SQL من خلال مثيل الفترة التجريبية المجانية من Cloud SQL

بدء Cloud Shell

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

في Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

تفعيل Cloud Shell

بدلاً من ذلك، اضغط على g ثم s في Google Cloud Console، أو افتح Cloud Shell.

لا يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك الجهاز الطرفي المتصل:

لقطة شاشة لوحدة طرفية Google Cloud Shell توضّح أنّه تم ربط البيئة

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

3- قبل البدء

تفعيل واجهة برمجة التطبيقات

لاستخدام Cloud SQL وCompute Engine وService Networking وGemini Enterprise Agent Platform، فعِّل واجهات برمجة التطبيقات الخاصة بها في مشروعك على Google Cloud.

في نافذة Cloud Shell، تأكَّد من ضبط رقم تعريف مشروعك:

gcloud config get project

إذا عرضت سلسلة فارغة، اضبطها على النحو التالي:

gcloud config set project [YOUR-PROJECT-ID]

اضبط متغيّر البيئة PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

فعِّل جميع واجهات برمجة التطبيقات اللازمة:

gcloud services enable sqladmin.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com

الناتج المتوقّع

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable sqladmin.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

يمكنك الاطّلاع على معلومات حول كل واجهة برمجة تطبيقات مفعَّلة في المستندات.

4. إنشاء مثيل Cloud SQL

أنشئ مثيلاً من Cloud SQL مع دمج قاعدة بيانات Gemini Enterprise Agent Platform.

إنشاء كلمة مرور لقاعدة البيانات

حدِّد كلمة مرور لمستخدم قاعدة البيانات التلقائي. يمكنك تحديد كلمة المرور الخاصة بك أو استخدام دالة عشوائية لإنشاء كلمة مرور:

export CLOUDSQL_PASSWORD=`openssl rand -hex 16`

عرض قيمة كلمة المرور التي تم إنشاؤها:

echo $CLOUDSQL_PASSWORD

دوِّن كلمة المرور التي تم إنشاؤها لاستخدامها لاحقًا.

إنشاء مثيل Cloud SQL for MySQL

يمكن إنشاء مثيلات Cloud SQL باستخدام عدة طرق، بما في ذلك Google Cloud Console أو Terraform أو Google Cloud CLI (gcloud). في هذا الدرس التطبيقي حول الترميز، ستستخدم gcloud. لمعرفة كيفية إنشاء آلة افتراضية باستخدام أدوات أخرى، راجِع مستند إنشاء آلات افتراضية.

يمكن تفعيل العلامة cloudsql_vector عند إنشاء مثيل. تتوفّر ميزة "البحث الدلالي" في MySQL 8.0 R20241208.01_00 أو الإصدارات الأحدث.

في جلسة Cloud Shell، نفِّذ ما يلي:

gcloud sql instances create my-cloudsql-instance \
--database-version=MYSQL_8_4 \
--tier=db-custom-2-8192 \
--region=us-central1 \
--enable-google-ml-integration \
--edition=ENTERPRISE \
--root-password=$CLOUDSQL_PASSWORD

اربط بنسخة Looker باستخدام gcloud sql connect. عندما يُطلب منك ذلك، أدخِل كلمة المرور:

gcloud sql connect my-cloudsql-instance --user=root

الناتج المتوقّع:

$gcloud sql connect my-cloudsql-instance --user=root
Allowlisting your IP for incoming connection for 5 minutes...done.                                                                                                                           
Connecting to database with SQL user [root].Enter password: 
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 71
Server version: 8.4.4-google (Google)

Copyright (c) 2000, 2025, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

يمكنك الخروج من جلسة mysql من خلال الضغط على Ctrl+D أو إدخال exit:

exit

تفعيل ميزة دمج Gemini Enterprise Agent Platform

امنح دور "إدارة الهوية وإمكانية الوصول" اللازم لحساب خدمة Cloud SQL لتفعيل عملية الربط بمنصة وكيل Gemini Enterprise.

استرجِع عنوان البريد الإلكتروني لحساب خدمة Cloud SQL وصدِّره كمتغيّر بيئة:

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe my-cloudsql-instance --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

امنح حساب خدمة Cloud SQL الدور roles/aiplatform.user:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
  --role="roles/aiplatform.user"

يمكنك الاطّلاع على مزيد من المعلومات حول إنشاء المثيل وإعداده في مستندات Cloud SQL هنا.

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

إنشاء قاعدة بيانات وتفعيل إمكانية البحث المتّجه

إنشاء قاعدة بيانات

أنشئ قاعدة بيانات باسم quickstart_db. يمكنك إنشاء قواعد بيانات باستخدام برامج قواعد البيانات (مثل mysql) أو واجهة سطر الأوامر (CLI) في Google Cloud أو Cloud SQL Studio. في هذه الخطوة، استخدِم gcloud.

في Cloud Shell، نفِّذ الأمر التالي لإنشاء قاعدة البيانات:

gcloud sql databases create quickstart_db --instance=my-cloudsql-instance

6. تحميل البيانات

أنشئ جداول في قاعدة البيانات وحمِّل البيانات باستخدام ملفات مجموعة بيانات Cymbal Store الوهمية المخزَّنة في حزمة Cloud Storage عامة بتنسيق CSV.

ستكون Cloud Shell بيئتك الرئيسية للاتصال بقاعدة بيانات وإنشاء جميع العناصر وتحميل البيانات.

أضِف عنوان IP العلني الخاص بـ Cloud Shell إلى قائمة الشبكات المصرّح بها لمثيل Cloud SQL.

في shell، نفِّذ ما يلي:

gcloud sql instances patch my-cloudsql-instance --authorized-networks=$(curl ifconfig.me)

في حال فقدان جلستك، أعِد ضبط متغير CLOUDSQL_PASSWORD أو اعمل من أداة أخرى ثمّ صدِّر المتغير مرة أخرى:

export CLOUDSQL_PASSWORD=...your password defined for the instance...

أنشئ عناصر قاعدة البيانات المطلوبة. استخدِم mysql مع curl لتنزيل المخطّط وتطبيقه من المصدر العام.

في shell، نفِّذ ما يلي:

export INSTANCE_IP=$(gcloud sql instances describe my-cloudsql-instance --format="value(ipAddresses.ipAddress)")
curl -LJ https://raw.githubusercontent.com/GoogleCloudPlatform/devrel-demos/main/infrastructure/cymbal-store-embeddings/cymbal_mysql_schema.sql | mysql --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD quickstart_db

تفاصيل الطلب: في الخطوة السابقة، ربطت قاعدة البيانات وشغّلت نص SQL البرمجي لإنشاء الجداول والفهارس والتسلسلات.

بعد ذلك، املأ قاعدة البيانات ببيانات cymbal_products من خلال تنفيذ curl وmysql:

curl -LJ https://raw.githubusercontent.com/GoogleCloudPlatform/devrel-demos/main/infrastructure/cymbal-store-embeddings/cymbal_products.csv | mysql --enable-local-infile --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD quickstart_db -e "LOAD DATA LOCAL INFILE '/dev/stdin'  INTO TABLE cymbal_products FIELDS TERMINATED BY ','  OPTIONALLY ENCLOSED BY '\"'  LINES TERMINATED BY '\n'  IGNORE 1 LINES;"

يُرجى مواصلة استخدام cymbal_stores.

curl -LJ https://raw.githubusercontent.com/GoogleCloudPlatform/devrel-demos/main/infrastructure/cymbal-store-embeddings/cymbal_stores.csv | mysql --enable-local-infile --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD quickstart_db -e "LOAD DATA LOCAL INFILE '/dev/stdin'  INTO TABLE cymbal_stores FIELDS TERMINATED BY ','  OPTIONALLY ENCLOSED BY '\"'  LINES TERMINATED BY '\n'  IGNORE 1 LINES;"

واكتملت البيانات بـ cymbal_inventory الذي يتضمّن عدد كل منتج في كل متجر.

curl -LJ https://raw.githubusercontent.com/GoogleCloudPlatform/devrel-demos/main/infrastructure/cymbal-store-embeddings/cymbal_inventory.csv | mysql --enable-local-infile --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD quickstart_db -e "LOAD DATA LOCAL INFILE '/dev/stdin'  INTO TABLE cymbal_inventory FIELDS TERMINATED BY ','  OPTIONALLY ENCLOSED BY '\"'  LINES TERMINATED BY '\n'  IGNORE 1 LINES;"

اختياري: إذا كانت لديك مجموعة بيانات نموذجية خاصة بك، يمكنك استيراد ملفات CSV متوافقة باستخدام "أداة الاستيراد" في Google Cloud Console بدلاً من ذلك.

7. إنشاء تضمينات

إنشاء تضمينات لأوصاف المنتجات باستخدام نموذج text-embedding-005 من Gemini Enterprise Agent Platform وتخزينها كبيانات متجهة

لتخزين بيانات المتجهات، عليك تفعيل وظيفة المتجهات في مثيل Cloud SQL.

نفِّذ ما يلي في Cloud Shell:

gcloud sql instances patch my-cloudsql-instance \
--database-flags=cloudsql_vector=on

الربط بقاعدة البيانات:

mysql --host=$INSTANCE_IP --user=root --password=$CLOUDSQL_PASSWORD quickstart_db

أنشئ عمودًا جديدًا embedding في جدول cymbal_products باستخدام دالة التضمين. سيتضمّن هذا العمود الجديد تضمينات المتجهات استنادًا إلى النص في العمود product_description:

ALTER TABLE cymbal_products ADD COLUMN embedding vector(768) using varbinary;
UPDATE cymbal_products SET embedding = mysql.ml_embedding('text-embedding-005', product_description);

ملاحظة: يستغرق إنشاء عمليات التضمين لـ 2,000 صف عادةً أقل من 5 دقائق.

الخروج من جلسة mysql:

exit

8. تشغيل "البحث عن صور مشابهة"

إجراء بحث عن التشابه من خلال مقارنة عمليات تضمين المتّجهات المحسوبة لأوصاف المنتجات بعملية التضمين لطلب بحث

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

إنشاء مستخدم MySQL لـ Cloud SQL Studio

تحتاج إلى مستخدم قاعدة بيانات جديد يمكنه استخدام Cloud SQL Studio. أنشئ مستخدمًا من النوع المضمّن student باستخدام كلمة المرور نفسها التي استخدمتها للمستخدم الجذر.

في Cloud Shell، نفِّذ ما يلي:

gcloud sql users create student  --instance=my-cloudsql-instance --password=$CLOUDSQL_PASSWORD --host=%

بدء Cloud SQL Studio

في Google Cloud Console، انتقِل إلى مثيلات Cloud SQL وانقر على my-cloudsql-instance.

قائمة مثيلات Cloud SQL في Google Cloud Console

في قائمة التنقّل، انقر على Cloud SQL Studio.

عنصر قائمة Cloud SQL Studio

في مربّع حوار المصادقة، أدخِل اسم قاعدة البيانات وبيانات الاعتماد:
- قاعدة البيانات: quickstart_db
- المستخدم: student
- كلمة المرور:
انقر على مصادقة.

مربّع حوار المصادقة في Cloud SQL Studio

انقر على علامة التبويب طلب بدون عنوان لفتح "محرّر SQL".

علامة التبويب "محرّر SQL" في Cloud SQL Studio

تنفيذ طلب البحث

نفِّذ طلب بحث لاسترداد أفضل 5 منتجات ذات صلة بطلب بحث العميل: "ما هي أنواع أشجار الفاكهة التي تنمو جيدًا هنا؟"

تنفيذ طلب بحث باستخدام cosine_distance للبحث المتّجه (الدقيق) عن أقرب جار (KNN)

في ما يلي طلب البحث الذي يمكنك تنفيذه لاختيار أول 5 عناصر الأنسب لطلبنا باستخدام الدالة cosine_distance:

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cosine_distance(cp.embedding ,@query_vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 5;

في Cloud SQL Studio، أدخِل الاستعلام وانقر على تنفيذ (أو نفِّذ الاستعلام في جلسة sql):

تنفيذ طلب بحث SQL في Cloud SQL Studio

يعرض طلب البحث المنتجات المطابقة مرتّبة حسب مسافة جيب التمام:

+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| product_name    | description                                                                      | sale_price | zip_code | distance            |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| Malus Domestica | Malus Domestica, the classic apple tree, brings beauty and delicious fruit to yo |     100.00 |    93230 | 0.37740096545831603 |
| Cerasus         | Cerasus: A beautiful cherry tree that brings delicious fruit and vibrant color t |      75.00 |    93230 |   0.405704177142419 |
| Persica         | Persica: Enjoy homegrown, delicious peaches with this beautiful peach tree. Reac |     150.00 |    93230 | 0.41031799106722877 |
| Meyer Lemon     | Grow your own juicy Meyer Lemons with this semi-dwarf tree, California's favorit |      34.00 |    93230 | 0.42823360959352186 |
| Acer            | Acer, the classic maple. Known for vibrant fall foliage in reds, oranges, and ye |     100.00 |    93230 | 0.42953897057301615 |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
5 rows in set (0.13 sec)

يبلغ وقت تنفيذ طلب البحث 0.13 ثانية تقريبًا باستخدام الدالة cosine_distance.

تشغيل طلب البحث باستخدام approx_distance للبحث المتّجه (التطابُق التام) في خوارزمية الجار الأقرب

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

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        approx_distance(cp.embedding ,@query_vector, 'distance_measure=cosine') as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 5;

في ما يلي قائمة بالمنتجات التي أرجعها طلب البحث.

+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| product_name    | description                                                                      | sale_price | zip_code | distance            |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| Malus Domestica | Malus Domestica, the classic apple tree, brings beauty and delicious fruit to yo |     100.00 |    93230 | 0.37740096545831603 |
| Cerasus         | Cerasus: A beautiful cherry tree that brings delicious fruit and vibrant color t |      75.00 |    93230 |   0.405704177142419 |
| Persica         | Persica: Enjoy homegrown, delicious peaches with this beautiful peach tree. Reac |     150.00 |    93230 | 0.41031799106722877 |
| Meyer Lemon     | Grow your own juicy Meyer Lemons with this semi-dwarf tree, California's favorit |      34.00 |    93230 | 0.42823360959352186 |
| Acer            | Acer, the classic maple. Known for vibrant fall foliage in reds, oranges, and ye |     100.00 |    93230 | 0.42953897057301615 |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
5 rows in set, 1 warning (0.12 sec)

لم يستغرق تنفيذ الاستعلام سوى 0.12 ثانية. حصلنا على النتائج نفسها كما في دالة KNN exact cosine_distance.

يمكنك الاطّلاع على مزيد من المعلومات حول الدالة في مستندات Cloud SQL for MySQL.

9. تحسين ردود النموذج اللغوي الكبير باستخدام البيانات المسترجَعة

تحسين ردّ الذكاء الاصطناعي التوليدي على تطبيق العميل من خلال تمرير نتائج طلب البحث كسياق مستند إلى بيانات واقعية في طلب إلى نموذج لغوي أساسي في Agent Platform من Gemini Enterprise

ولإجراء ذلك:

إنشاء حمولة JSON من نتيجة البحث المتّجه في Cloud SQL
اختبِر الطلب في Agent Platform Studio.
تنفيذ الطلب الشامل مباشرةً من SQL باستخدام عملية الدمج google_ml

إنشاء ناتج بتنسيق JSON

عدِّل الاستعلام لتنسيق النتيجة كملف JSON وإرجاع صف واحد:

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (approx_distance(cp.embedding ,@query_vector, 'distance_measure=cosine')) ASC
LIMIT 1)
SELECT json_arrayagg(json_object('product_name',product_name,'description',description,'sale_price',sale_price,'zip_code',zip_code,'product_id',product_id)) FROM trees;

الردّ المتوقّع بتنسيق JSON:

[{"zip_code": 93230, "product_id": "23e41a71d63d8bbc9bdfa1d118cfddc5", "sale_price": 100.00, "description": "Malus Domestica, the classic apple tree, brings beauty and delicious fruit to yo", "product_name": "Malus Domestica"}]

تشغيل الطلب في Agent Platform Studio

قدِّم ملف JSON الذي تم إنشاؤه كسياق في طلب إلى نموذج توليدي في Agent Platform Studio.

في Google Cloud Console، افتح Agent Platform Studio.

التنقّل في Agent Platform Studio

أدخِل الطلب التالي في Agent Platform Studio:

إدخال الطلب في Agent Platform Studio

You are a friendly advisor helping to find a product based on the customer's needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","description":"some description","sale_price":10,"zip_code": 10234, "produt_id": "02056727942aeb714dc9a2313654e1b0"}
Here is the list of products:
<JSON_OUTPUT>
The customer asked "What tree is growing the best here?"
You should give information about the product, price and some supplemental information.
Do not ask any additional questions and assume location based on the zip code provided in the list of products.

استبدِل باستجابة JSON من طلب البحث:

You are a friendly advisor helping to find a product based on the customer's needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","description":"some description","sale_price":10,"zip_code": 10234, "produt_id": "02056727942aeb714dc9a2313654e1b0"}
Here is the list of products:
{"zip_code": 93230, "product_id": "23e41a71d63d8bbc9bdfa1d118cfddc5", "sale_price": 100.00, "description": "Malus Domestica, the classic apple tree, brings beauty and delicious fruit to yo", "product_name": "Malus Domestica"}
The customer asked "What tree is growing the best here?"
You should give information about the product, price and some supplemental information.
Do not ask any additional questions and assume location based on the zip code provided in the list of products.

الطلب في Agent Platform Studio

أرسِل الطلب.

نتيجة الطلب في Agent Platform Studio

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

تشغيل الطلب في SQL

يمكنك أيضًا استخدام عملية دمج الذكاء الاصطناعي في Cloud SQL مع "منصة وكيل Gemini Enterprise" للحصول على ردود من نموذج توليدي مباشرةً في SQL.

أولاً، سجِّل النموذج.

سجِّل نموذج gemini-3.5-flash لإنشاء الردود (استبدِل برقم تعريف مشروعك):

CALL
  mysql.ml_create_model_registration(
  'gemini-3.5-flash',
  'https://aiplatform.googleapis.com/v1/projects/<PROJECT_ID>/locations/global/publishers/google/models/gemini-3.5-flash:generateContent',
  'google',
  'GENERIC',
  NULL,
  'auth_type_cloudsql_service_agent_iam',
  NULL, NULL, NULL, NULL);

يمكننا أيضًا استخدام عملية دمج الذكاء الاصطناعي في Cloud SQL مع "منصة وكيل Gemini Enterprise" للحصول على الردّ المشابه من نموذج توليدي باستخدام SQL مباشرةً في قاعدة البيانات.

يمكننا الآن استخدام النتائج التي تم إنشاؤها في طلب فرعي مع نتائج JSON لتوفيرها كجزء من الطلب إلى نموذج الذكاء الاصطناعي التوليدي النصي باستخدام SQL.

في جلسة mysql أو Cloud SQL Studio لقاعدة البيانات، شغِّل الاستعلام

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
WITH trees AS (
SELECT
        cp.product_name,
        cp.product_description AS description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id AS product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci ON
        ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON
        cs.store_id = ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
         (approx_distance(cp.embedding ,@query_vector, 'distance_measure=cosine')) ASC
LIMIT 1),
prompt AS (
SELECT
       CONCAT( 'You are a friendly advisor helping to find a product based on the customer''s needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","product_description":"some description","sale_price":10}
Here is the list of products:', json_arrayagg(json_object('product_name',trees.product_name,'description',trees.description,'sale_price',trees.sale_price,'zip_code',trees.zip_code,'product_id',trees.product_id)) , 'The customer asked "What kind of fruit trees grow well here?"
You should give information about the product, price and some supplemental information') AS prompt_text
FROM
        trees),
response AS (
SELECT
       mysql.ML_PREDICT_ROW('gemini-3.5-flash',
        json_object('contents',
        json_object('role',
        'user',
        'parts',
        json_array(
        json_object('text',
        prompt_text))))) AS resp
FROM
        prompt)
SELECT
JSON_EXTRACT(resp, '$.candidates[0].content.parts[0].text')
FROM
        response;

وفي ما يلي نموذج للناتج. قد يختلف الناتج الذي يظهر على جهازك استنادًا إلى إصدار النموذج والمعلَمات.

"Hello there! I'd be happy to help you find the perfect fruit tree for your space. \n\nBased on your area, a wonderful option we currently have in stock is the **Malus Domestica** (the classic Apple Tree)!\n\nHere are the key details:\n\n* **Product Name:** Malus Domestica (Classic Apple Tree)\n* **Price:** $100.00\n\n### Why it's a great choice:\n* **Beautiful Seasonal Foliage:** It features vibrant green leaves during the summer that turn into gorgeous shades of red, orange, and yellow in the autumn. \n* **Shade & Size:** It grows to approximately 30 feet tall, making it a strong, durable tree that offers excellent shade for your yard alongside delicious fresh fruit.\n* **Growing Conditions:** It thrives best in cool, moist climates with well-draining, loamy soil and is ideal for USDA Hardiness Zones 4–8.\n\n### Supplemental Care Tips:\n* **Planting Location:** Choose a spot that gets full sunlight (at least 6 hours a day) to ensure maximum fruit production.\n* **Soil:** Make sure the soil is rich and loamy with good drainage so the roots stay healthy.\n* **Cross-Pollination:** Apple trees often produce a higher yield when planted near another compatible apple tree variety, so if you have extra space, adding a companion tree in the future can boost your harvest!\n\nLet me know if you have any questions about planting or care, or if you'd like help adding this to your cart!"

يتم تقديم الناتج بتنسيق Markdown.

10. إنشاء فهرس أقرب جيران

بالنسبة إلى مجموعات البيانات الكبيرة التي تحتوي على ملايين المتجهات، قد يتطلّب البحث عن المتجهات موارد حوسبة كبيرة. لتحسين أداء طلب البحث، أنشئ فهرسًا على تضمينات المتّجهات.

إنشاء فهرس ScaNN

سنحاول استخدام نوع فهرس ScaNN في اختبارنا.

لإنشاء الفهرس لعمود التضمين، عليك تحديد مقياس المسافة لعمود التضمين. يمكنك الاطّلاع على تفاصيل حول المَعلمات في المستندات.

CREATE VECTOR INDEX cymbal_products_embedding_idx ON cymbal_products(embedding) USING SCANN DISTANCE_MEASURE=COSINE;

مقارنة الردود

أعِد تنفيذ طلب البحث عن المتّجه واطّلِع على النتائج:

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        approx_distance(cp.embedding ,@query_vector, 'distance_measure=cosine') as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 5;

الناتج المتوقّع:

+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| product_name    | description                                                                      | sale_price | zip_code | distance            |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
| Malus Domestica | Malus Domestica, the classic apple tree, brings beauty and delicious fruit to yo |     100.00 |    93230 | 0.37740096545831603 |
| Cerasus         | Cerasus: A beautiful cherry tree that brings delicious fruit and vibrant color t |      75.00 |    93230 |   0.405704177142419 |
| Persica         | Persica: Enjoy homegrown, delicious peaches with this beautiful peach tree. Reac |     150.00 |    93230 | 0.41031799106722877 |
| Meyer Lemon     | Grow your own juicy Meyer Lemons with this semi-dwarf tree, California's favorit |      34.00 |    93230 | 0.42823360959352186 |
| Acer            | Acer, the classic maple. Known for vibrant fall foliage in reds, oranges, and ye |     100.00 |    93230 | 0.42953897057301615 |
+-----------------+----------------------------------------------------------------------------------+------------+----------+---------------------+
5 rows in set (0.08 sec)

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

تحقَّق من خطة التنفيذ باستخدام الأمر EXPLAIN:

SELECT mysql.ML_EMBEDDING('text-embedding-005','What kind of fruit trees grow well here?') into @query_vector;
EXPLAIN ANALYZE SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        approx_distance(cp.embedding ,@query_vector, 'distance_measure=cosine') as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 5;

خطة التنفيذ (مقتطف):

...
-> Nested loop inner join  (cost=443 rows=5) (actual time=1.14..1.18 rows=5 loops=1)
                                -> Vector index scan on cp  (cost=441 rows=5) (actual time=1.1..1.1 rows=5 loops=1)
                                -> Single-row index lookup on cp using PRIMARY (uniq_id=cp.uniq_id)  (cost=0.25 rows=1) (actual time=0.0152..0.0152 rows=1 loops=5)

...

تعرض هذه الخطة عملية فحص فهرس المتجهات في جدول cp(اسم مستعار لجدول cymbal_products).

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

11. تنظيف البيئة

حذف مثيل Cloud SQL

محو مثيل Cloud SQL عند الانتهاء من الميزة الاختبارية

في Cloud Shell، حدِّد متغيرات المشروع والبيئة إذا تم قطع الاتصال وفقدت جميع الإعدادات السابقة:

export INSTANCE_NAME=my-cloudsql-instance
export PROJECT_ID=$(gcloud config get-value project)

لحذف موضع التكرار:

gcloud sql instances delete $INSTANCE_NAME --project=$PROJECT_ID

الناتج المتوقّع في وحدة التحكّم:

student@cloudshell:~$ gcloud sql instances delete $INSTANCE_NAME --project=$PROJECT_ID
All of the instance data will be lost when the instance is deleted.

Do you want to continue (Y/n)?  y

Deleting Cloud SQL instance...done.                                                                                                                
Deleted [https://sandbox.googleapis.com/v1beta4/projects/test-project-001-402417/instances/my-cloudsql-instance].

12. تهانينا

تهانينا على إكمال هذا الدرس العملي.

المسار التعليمي في Google Cloud

يشكّل هذا المختبر جزءًا من مسار "الذكاء الاصطناعي الجاهز للإنتاج" التعليمي على Google Cloud.

استكشِف المنهج الدراسي الكامل لسدّ الفجوة بين النموذج الأوّلي والإنتاج.
شارِك مستوى تقدّمك باستخدام الهاشتاغ #ProductionReadyAI.

المواضيع التي تناولتها

كيفية نشر مثيل Cloud SQL لخدمة MySQL
كيفية إنشاء قاعدة بيانات وتفعيل تكامل الذكاء الاصطناعي في Cloud SQL
كيفية تحميل البيانات إلى قاعدة البيانات
كيفية استخدام Cloud SQL Studio
كيفية استخدام نموذج التضمين في Vertex AI في Cloud SQL
كيفية استخدام Agent Platform Studio
كيفية تحسين النتيجة باستخدام نموذج Gemini Enterprise Agent Platform
كيفية تحسين الأداء باستخدام فهرس المتّجه

جرِّب درسًا تطبيقيًا مشابهًا حول الترميز لـ AlloyDB أو درسًا تطبيقيًا حول الترميز لـ Cloud SQL for Postgres

استطلاع

إخراج:

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط

قراءة المحتوى وإكمال التمارين