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

1. مقدمة

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

30b7c4dcdd8bb68f.png

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

  • فهم أساسي لوحدة تحكّم Google Cloud
  • المهارات الأساسية في واجهة سطر الأوامر وCloud Shell

ما ستتعرّف عليه

  • كيفية نشر مثيل Cloud SQL for PostgreSQL
  • كيفية إنشاء قاعدة بيانات وتفعيل دمج الذكاء الاصطناعي في Cloud SQL
  • كيفية تحميل البيانات إلى قاعدة البيانات
  • كيفية استخدام نموذج التضمين في Vertex AI في Cloud SQL
  • كيفية تحسين النتيجة باستخدام النموذج التوليدي في Vertex AI
  • كيفية تحسين الأداء باستخدام فهرس المتجهات

المتطلبات

  • حساب Google Cloud ومشروع Google Cloud
  • متصفّح ويب، مثل Chrome، متوافق مع وحدة تحكّم Google Cloud وCloud Shell

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

إعداد البيئة حسب السرعة التي تناسبك

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

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

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

بدء Cloud Shell

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

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

55efc1aaa7a4d3ad.png

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

7ffe5cbb04455448.png

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

3- قبل البدء

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

إخراج:

في Cloud Shell، تأكَّد من إعداد رقم تعريف مشروعك:

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 مع دمج قاعدة البيانات مع Vertex AI.

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

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

export CLOUDSQL_PASSWORD=`openssl rand -hex 12`

دوِّن القيمة التي تم إنشاؤها لكلمة المرور:

echo $CLOUDSQL_PASSWORD

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

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

gcloud sql instances create my-cloudsql-instance \
--database-version=POSTGRES_16 \
--tier=db-custom-1-3840 \
--region=us-central1 \
--edition=ENTERPRISE \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

بعد إنشاء المثيل، علينا ضبط كلمة مرور للمستخدم التلقائي في المثيل والتحقّق مما إذا كان بإمكاننا الاتصال باستخدام كلمة المرور.

gcloud sql users set-password postgres \
    --instance=my-cloudsql-instance \
    --password=$CLOUDSQL_PASSWORD

نفِّذ الأمر وأدخِل كلمة المرور في الطلب عندما يصبح الجهاز جاهزًا للاتصال.

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

تفعيل دمج Vertex AI

امنح الامتيازات اللازمة لحساب خدمة Cloud SQL الداخلي لتتمكّن من استخدام عملية دمج Vertex AI.

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

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

امنح حساب خدمة Cloud SQL إذن الوصول إلى Vertex AI:

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

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

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

نحتاج الآن إلى إنشاء قاعدة بيانات وتفعيل ميزة دعم المتجهات.

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

أنشئ قاعدة بيانات باسم quickstart_db .لإجراء ذلك، لدينا خيارات مختلفة مثل عملاء قاعدة بيانات سطر الأوامر، مثل psql لـ PostgreSQL أو حزمة تطوير البرامج (SDK) أو Cloud SQL Studio. سنستخدم حِزمة تطوير البرامج (gcloud) لإنشاء قواعد البيانات والربط بالمثيل.

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

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

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

لنتمكّن من العمل مع Vertex AI والمتجهات، علينا تفعيل علامتَين إضافتَين في قاعدة البيانات التي أنشأناها.

في Cloud Shell، نفِّذ الأمر للربط بقاعدة البيانات التي تم إنشاؤها (ستحتاج إلى تقديم كلمة المرور).

gcloud sql connect my-cloudsql-instance --database quickstart_db --user=postgres

بعد ذلك، بعد إجراء عملية الاتصال بنجاح، عليك تنفيذ أمرَين في جلسة sql:

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

للخروج من جلسة SQL:

exit;

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

نحتاج الآن إلى إنشاء عناصر في قاعدة البيانات وتحميل البيانات. سنستخدم بيانات خيالية لمتجر Cymbal Store. تتوفّر البيانات في حزمة Google Storage العامة بتنسيق CSV.

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

في Cloud Shell، نفِّذ الأمر التالي وقدِّم كلمة المرور التي تم تدوينها أثناء إنشاء المثيل:

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |gcloud sql connect my-cloudsql-instance --database quickstart_db --user=postgres

ما الذي فعلناه بالضبط في الأمر السابق؟ لقد ربطنا بقاعدة بياناتنا ونفّذنا رمز SQL الذي تم تنزيله والذي أنشأ الجداول والفهارس والتسلسلات.

الخطوة التالية هي تحميل البيانات، ولإجراء ذلك، علينا تنزيل ملفات CSV من Google Cloud Storage.

gcloud storage cp gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv .
gcloud storage cp gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv .
gcloud storage cp gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv .

بعد ذلك، علينا الاتصال بقاعدة البيانات.

gcloud sql connect my-cloudsql-instance --database quickstart_db --user=postgres

واستيراد البيانات من ملفات CSV

\copy cymbal_products from 'cymbal_products.csv' csv header

\copy cymbal_inventory from 'cymbal_inventory.csv' csv header

\copy cymbal_stores from 'cymbal_stores.csv' csv header

للخروج من جلسة SQL:

exit;

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

7- إنشاء عمليات التضمين

الخطوة التالية هي إنشاء embeddings لأوصاف منتجاتنا باستخدام نموذج textembedding-004 من Google Vertex AI وتخزينها كبيانات متجهة.

الاتصال بقاعدة البيانات:

gcloud sql connect my-cloudsql-instance --database quickstart_db --user=postgres

وأنشئ عمودًا افتراضيًا embedding في جدول cymbal_products باستخدام دالة embedding.

ALTER TABLE cymbal_products ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-004',product_description)) STORED;

قد يستغرق الأمر بعض الوقت، ولكن بالنسبة إلى 900 إلى 1,000 صف، من المفترض ألا يستغرق أكثر من 5 دقائق، وعادةً ما يكون أسرع بكثير.

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

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

يمكن تنفيذ طلب البحث SQL من واجهة سطر الأوامر نفسها باستخدام gcloud sql connect أو، كخيار بديل، من Cloud SQL Studio. من الأفضل إدارة أي استعلام معقد ومتعدّد الصفوف في Cloud SQL Studio.

ابدأ Cloud SQL Studio.

في وحدة التحكّم، انقر على مثيل Cloud SQL الذي أنشأناه سابقًا.

b8d4844da1114a0b.png

عندما يكون مفتوحًا في اللوحة اليمنى، يمكننا رؤية Cloud SQL Studio. انقر عليه.

ce3f27dc21367f2e.png

سيؤدي ذلك إلى فتح مربّع حوار حيث يمكنك تقديم اسم قاعدة البيانات وبيانات الاعتماد:

  • قاعدة البيانات: quickstart_db
  • المستخدم: postgres
  • كلمة المرور: كلمة المرور التي سجّلتها لمستخدم قاعدة البيانات الرئيسي

انقر على الزر "مصادقة".

2591c8bbc93e4e97.png

سيؤدي ذلك إلى فتح النافذة التالية التي تنقر فيها على علامة التبويب "المحرِّر" على يسار الصفحة لفتح محرِّر SQL.

74307cb101a3ba9d.png

نحن الآن جاهزون لتشغيل استفساراتنا.

تنفيذ الطلب

يمكنك إجراء طلب بحث للحصول على قائمة بالمنتجات المتاحة الأكثر صلةً بطلبك. الطلب الذي سنرسله إلى Vertex AI للحصول على قيمة المتجه يبدو مثل "ما هو نوع أشجار الفاكهة التي تنمو جيدًا هنا؟"

في ما يلي طلب البحث الذي يمكنك تنفيذه لاختيار أوّل 10 عناصر تناسب طلبنا:

SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (cp.embedding <=> embedding('text-embedding-004','What kind of fruit trees grow well here?')::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 10;

انسخ طلب البحث والصقه في محرِّر Cloud SQL Studio واضغط على الزر "تشغيل" (RUN) أو الصقه في جلسة سطر الأوامر التي تتصل بقاعدة بيانات quickstart_db.

cd07549522fd04c9.png

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

product_name       |                                   description                                    | sale_price | zip_code |      distance       
-------------------------+----------------------------------------------------------------------------------+------------+----------+---------------------
 Cherry Tree             | This is a beautiful cherry tree that will produce delicious cherries. It is an d |      75.00 |    93230 | 0.43922018972266397
 Meyer Lemon Tree        | Meyer Lemon trees are California's favorite lemon tree! Grow your own lemons by  |         34 |    93230 |  0.4685112926118228
 Toyon                   | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e |      10.00 |    93230 |  0.4835677149651668
 California Lilac        | This is a beautiful lilac tree that can grow to be over 10 feet tall. It is an d |       5.00 |    93230 |  0.4947204525907498
 California Peppertree   | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e |      25.00 |    93230 |  0.5054166905547247
 California Black Walnut | This is a beautiful walnut tree that can grow to be over 80 feet tall. It is a d |     100.00 |    93230 |  0.5084219510932597
 California Sycamore     | This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is  |     300.00 |    93230 |  0.5140519790508755
 Coast Live Oak          | This is a beautiful oak tree that can grow to be over 100 feet tall. It is an ev |     500.00 |    93230 |  0.5143126438081371
 Fremont Cottonwood      | This is a beautiful cottonwood tree that can grow to be over 100 feet tall. It i |     200.00 |    93230 |  0.5174774727252058
 Madrone                 | This is a beautiful madrona tree that can grow to be over 80 feet tall. It is an |      50.00 |    93230 |  0.5227400803389093
(10 rows)

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

يمكننا تحسين ردّ نموذج اللغة الكبير المستنِد إلى الذكاء الاصطناعي التوليدي على تطبيق العميل باستخدام نتيجة طلب البحث الذي تم تنفيذه وإعداد ناتج ذي معنى باستخدام نتائج طلب البحث المقدَّمة كجزء من الطلب المرسَل إلى نموذج اللغة الأساسي التوليدي في Vertex AI.

لتحقيق ذلك، نحتاج إلى إنشاء ملف JSON يتضمّن نتائجنا من البحث عن المتّجهات، ثم استخدام ملف JSON الذي تم إنشاؤه كإضافة إلى طلب لنموذج LLM في Vertex AI لإنشاء ناتج ذي معنى. في الخطوة الأولى، ننشئ ملف JSON، ثم نختبره في Vertex AI Studio، وفي الخطوة الأخيرة، ندمجه في عبارة SQL التي يمكن استخدامها في أحد التطبيقات.

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

عدِّل طلب البحث لإنشاء الإخراج بتنسيق JSON وعرض صف واحد فقط لنقله إلى Vertex AI.

Cloud SQL for PostgreSQL

في ما يلي مثال على طلب البحث:

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
        (cp.embedding <=> embedding('text-embedding-004','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

في ما يلي تنسيق JSON المتوقّع في الإخراج:

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

تنفيذ الطلب في Vertex AI Studio

يمكننا استخدام ملف JSON الذي تم إنشاؤه لتقديمه كجزء من الطلب إلى نموذج النصوص الذكي التوليدي في Vertex AI Studio.

افتح ميزة "محادثة Vertex AI Studio" في وحدة تحكّم السحابة الإلكترونية.

449b5959fa0e93bd.png

قد يُطلب منك تفعيل واجهات برمجة تطبيقات إضافية، ولكن يمكنك تجاهل الطلب. لا نحتاج إلى أي واجهات برمجة تطبيقات إضافية لإكمال الدرس التطبيقي.

في ما يلي الطلب الذي سنستخدمه:

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:
[place your JSON here]
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:
[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]
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 واستخدام نموذج gemini-2.0-flash:

2c5145ebc04daae1.png

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

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

يبلغ سعره 75.00 دولار أمريكي.

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

تنفيذ الطلب في PSQL

يمكننا أيضًا استخدام دمج الذكاء الاصطناعي في Cloud SQL مع Vertex AI للحصول على ردّ مشابه من نموذج توليدي باستخدام SQL مباشرةً في قاعدة البيانات. ولكن لاستخدام نموذج gemini-2.0-flash-exp، علينا تسجيله أولاً.

التشغيل في Cloud SQL for PostgreSQL

عليك ترقية الإضافة إلى الإصدار 1.4.2 أو إصدار أحدث (إذا كان الإصدار الحالي أقل). اربط قاعدة بيانات quickstart_db من gcloud sql connect كما هو موضّح من قبل (أو استخدِم Cloud SQL Studio) ونفِّذ ما يلي:

SELECT extversion from pg_extension where extname='google_ml_integration';

إذا كانت القيمة المعروضة أقل من 1.4.2، نفِّذ ما يلي:

ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2';

بعد ذلك، علينا ضبط علامة قاعدة بيانات google_ml_integration.enable_model_support على "تفعيل". لتنفيذ ذلك، يمكنك استخدام واجهة وحدة تحكّم الويب أو تنفيذ الأمر gcloud التالي.

gcloud sql instances patch my-cloudsql-instance \
--database-flags google_ml_integration.enable_model_support=on,cloudsql.enable_google_ml_integration=on

يستغرق تنفيذ الأمر في الخلفية مدة تتراوح بين دقيقة واحدة و3 دقائق تقريبًا. بعد ذلك، يمكنك التحقّق من العلامة الجديدة في جلسة psql أو باستخدام Cloud SQL Studio للربط بقاعدة بيانات quickstart_db.

show google_ml_integration.enable_model_support;

الناتج المتوقّع من جلسة psql هو "on":

quickstart_db => show google_ml_integration.enable_model_support;
 google_ml_integration.enable_model_support 
--------------------------------------------
 on
(1 row)

بعد ذلك، علينا تسجيل نموذجَين. النموذج الأول هو نموذج text-embedding-004 المستخدَم سابقًا. يجب تسجيله لأنّنا فعّلنا إمكانات تسجيل النماذج.

لتسجيل النموذج الذي تم تشغيله في psql أو Cloud SQL Studio، أدخِل الرمز البرمجي التالي:

CALL
  google_ml.create_model(
    model_id => 'text-embedding-004',
    model_provider => 'google',
    model_qualified_name => 'text-embedding-004',
    model_type => 'text_embedding',
    model_auth_type => 'cloudsql_service_agent_iam',
    model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
    model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

والنموذج التالي الذي يجب تسجيله هو gemini-2.0-flash-001 الذي سيتم استخدامه لإنشاء الإخراج الملائم للمستخدمين.

CALL
  google_ml.create_model(
    model_id => 'gemini-2.0-flash-001',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'cloudsql_service_agent_iam');

يمكنك في أي وقت التحقّق من قائمة النماذج المسجّلة من خلال اختيار المعلومات من google_ml.model_info_view.

select model_id,model_type from google_ml.model_info_view;

في ما يلي عيّنة من النتائج

quickstart_db=> select model_id,model_type from google_ml.model_info_view;
               model_id               |   model_type   
--------------------------------------+----------------
 textembedding-gecko                  | text_embedding
 textembedding-gecko@001              | text_embedding
 gemini-1.5-pro:streamGenerateContent | generic
 gemini-1.5-pro:generateContent       | generic
 gemini-1.0-pro:generateContent       | generic
 text-embedding-004                   | text_embedding
 gemini-2.0-flash-001                 | generic

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

في جلسة psql أو Cloud SQL Studio، يمكنك تشغيل الاستعلام في قاعدة البيانات.

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
        (cp.embedding <=> google_ml.embedding('text-embedding-004',
        'What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1),
prompt AS (
SELECT
        '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_agg(trees) || '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
        json_array_elements(google_ml.predict_row( model_id =>'gemini-2.0-flash-001',
        request_body => json_build_object('contents',
        json_build_object('role',
        'user',
        'parts',
        json_build_object('text',
        prompt_text)))))->'candidates'->0->'content'->'parts'->0->'text' AS resp
FROM
        prompt)
SELECT
        string_agg(resp::text,
        ' ')
FROM
        response;

في ما يلي النتيجة المتوقّعة. قد يختلف الناتج حسب إصدار النموذج والمَعلمات:

"That" "'s a great question! Based on your location (assuming you're" " in zip code 93230), I have a suggestion for a" " fruit tree that should thrive.\n\nWe have the **Cherry Tree** available.\n\n**Product Name:** Cherry Tree\n\n**Description:** This is a beautiful cherry" " tree that will produce delicious cherries. It's a deciduous tree (meaning it loses its leaves in the fall) growing to about 15 feet tall." " The leaves are dark green in summer, turning a beautiful red in the fall. Cherry trees are known for their beauty, shade, and privacy.\n\n**Sale Price:** $75.00\n\n**Important Considerations for Growing" " Cherry Trees:**\n\n* **Climate:** Cherry trees prefer a cool, moist climate, and 93230 falls within a suitable range (USDA zones 4-9). However, it's always a good idea to" " check the specific microclimate of your property (sun exposure, drainage etc.).\n* **Soil:** They do best in sandy soil. If your soil is different, you may need to amend it to improve drainage.\n* **Pollination:** Many cherry varieties require a second, compatible cherry tree for proper pollination" ". Check the specific pollination needs of this variety before purchase if you want a significant cherry yield.\n\nThis cherry tree is a beautiful addition to any yard and will provide you with delicious cherries if you can meet its needs. Would you like to know more about its pollination requirements, or perhaps see if we have any other" " fruit trees suitable for your area?\n" ""

10. إنشاء فهرس أقرب العناصر

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

إنشاء فهرس HNSW

سنحاول استخدام نوع فهرس HNSW في الاختبار. يشير الاختصار HNSW إلى Hierarchical Navigable Small World ويمثّل فهرسًا للرسم البياني المتعدّد الطبقات.

لإنشاء فهرس لعمود التضمين، علينا تحديد عمود التضمين ودالة المسافة والمَعلمات الاختيارية مثل m أو ef_constructions. يمكنك الاطّلاع على المَعلمات بالتفصيل في المستندات.

CREATE INDEX cymbal_products_embeddings_hnsw ON cymbal_products
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

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

quickstart_db=> CREATE INDEX cymbal_products_embeddings_hnsw ON cymbal_products
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
CREATE INDEX
quickstart_db=>

مقارنة الردّ

يمكننا الآن تشغيل طلب البحث بالاستناد إلى المتجهات في وضع EXPLAIN والتحقّق مما إذا تم استخدام الفهرس.

EXPLAIN (analyze) 
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
        (cp.embedding <=> embedding('text-embedding-004','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

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

 Aggregate  (cost=779.12..779.13 rows=1 width=32) (actual time=1.066..1.069 rows=1 loops=1)
   ->  Subquery Scan on trees  (cost=769.05..779.12 rows=1 width=142) (actual time=1.038..1.041 rows=1 loops=1)
         ->  Limit  (cost=769.05..779.11 rows=1 width=158) (actual time=1.022..1.024 rows=1 loops=1)
               ->  Nested Loop  (cost=769.05..9339.69 rows=852 width=158) (actual time=1.020..1.021 rows=1 loops=1)
                     ->  Nested Loop  (cost=768.77..9316.48 rows=852 width=945) (actual time=0.858..0.859 rows=1 loops=1)
                           ->  Index Scan using cymbal_products_embeddings_hnsw on cymbal_products cp  (cost=768.34..2572.47 rows=941 width=941) (actual time=0.532..0.539 rows=3 loops=1)
                                 Order By: (embedding <=> '[0.008864171,0.03693164,-0.024245683,...
<redacted>
...,0.017593635,-0.040275685,-0.03914233,-0.018452475,0.00826032,-0.07372604
]'::vector)
                           ->  Index Scan using product_inventory_pkey on cymbal_inventory ci  (cost=0.42..7.17 rows=1 width=37) (actual time=0.104..0.104 rows=0 loops=3)
                                 Index Cond: ((store_id = 1583) AND (uniq_id = (cp.uniq_id)::text))
                                 Filter: (inventory > 0)
                                 Rows Removed by Filter: 1
                     ->  Materialize  (cost=0.28..8.31 rows=1 width=8) (actual time=0.133..0.134 rows=1 loops=1)
                           ->  Index Scan using product_stores_pkey on cymbal_stores cs  (cost=0.28..8.30 rows=1 width=8) (actual time=0.129..0.129 rows=1 loops=1)
                                 Index Cond: (store_id = 1583)
 Planning Time: 112.398 ms
 Execution Time: 1.221 ms

من خلال النتيجة، يمكننا أن نرى بوضوح أنّ طلب البحث كان يستخدم "فهرسة البحث باستخدام cymbal_products_embeddings_hnsw".

وإذا أجرينا الاستعلام بدون explain:

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
        (cp.embedding <=> embedding('text-embedding-004','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

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

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

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

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

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. تهانينا

تهانينا على إكمال دورة codelab.

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

  • كيفية نشر مثيل Cloud SQL for PostgreSQL
  • كيفية إنشاء قاعدة بيانات وتفعيل دمج الذكاء الاصطناعي في Cloud SQL
  • كيفية تحميل البيانات إلى قاعدة البيانات
  • كيفية استخدام نموذج التضمين في Vertex AI في Cloud SQL
  • كيفية تحسين النتيجة باستخدام النموذج التوليدي في Vertex AI
  • كيفية تحسين الأداء باستخدام فهرس المتجهات

جرِّب codelab مشابهًا لـ AlloyDB باستخدام فهرس ScaNN بدلاً من HNSW.

13. استطلاع

إخراج:

كيف ستستخدم هذا الدليل التعليمي؟

القراءة فقط القراءة وإكمال التمارين