تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء SQL باستخدام اللغة الطبيعية في AlloyDB AI

1. مقدمة

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

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

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

ما ستتعلمه

كيفية نشر AlloyDB for Postgres
كيفية تفعيل ميزة "اللغة الطبيعية" في AlloyDB AI
كيفية إنشاء إعدادات اللغة الطبيعية للذكاء الاصطناعي وضبطها
كيفية إنشاء طلبات بحث بلغة الاستعلامات البنيوية (SQL) والحصول على نتائج باستخدام لغة طبيعية

المتطلبات

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

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

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

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

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

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

بدء Cloud Shell

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

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

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

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا ثابتًا بسعة 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 alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com \
                       secretmanager.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 alloydb.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. نشر AlloyDB

أنشئ مجموعة AlloyDB ومثيلًا أساسيًا. يوضّح الإجراء التالي كيفية إنشاء مجموعة ومثيل AlloyDB باستخدام Google Cloud SDK. إذا كنت تفضّل استخدام وحدة التحكّم، يمكنك اتّباع التعليمات الواردة في المستندات هنا.

قبل إنشاء مجموعة AlloyDB، نحتاج إلى نطاق عناوين IP خاصة متاح في شبكة السحابة الإلكترونية الخاصة الافتراضية (VPC) لاستخدامه في مثيل AlloyDB المستقبلي. إذا لم يكن لدينا، علينا إنشاؤه وتعيينه ليتم استخدامه من قِبل خدمات Google الداخلية، وبعد ذلك سنتمكّن من إنشاء المجموعة والمثيل.

إنشاء نطاق عناوين IP خاص

علينا ضبط إعدادات ميزة "الوصول إلى الخدمات الخاصة" في شبكة VPC الخاصة بنا من أجل AlloyDB. الافتراض هنا هو أنّ لدينا شبكة VPC "تلقائية" في المشروع وسيتم استخدامها في جميع الإجراءات.

أنشئ نطاق عناوين IP الخاصّة:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

أنشئ اتصالاً خاصًا باستخدام نطاق عناوين IP المخصّص:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

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

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

إنشاء مجموعة AlloyDB

في هذا القسم، سننشئ مجموعة AlloyDB في المنطقة us-central1.

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

export PGPASSWORD=`openssl rand -hex 12`

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

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

دوِّن كلمة مرور PostgreSQL لاستخدامها في المستقبل.

echo $PGPASSWORD

ستحتاج إلى كلمة المرور هذه في المستقبل للاتصال بالجهاز الظاهري بصفتك مستخدم postgres. أنصحك بتدوينه أو نسخه في مكان ما لتتمكّن من استخدامه لاحقًا.

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

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

إنشاء مجموعة من الفترات التجريبية المجانية

إذا لم يسبق لك استخدام AlloyDB، يمكنك إنشاء مجموعة تجريبية مجانية باتّباع الخطوات التالية:

حدِّد المنطقة واسم مجموعة AlloyDB. سنستخدم المنطقة us-central1 وalloydb-aip-01 كاسم مجموعة:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

نفِّذ الأمر التالي لإنشاء المجموعة:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL

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

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

أنشئ مثيلاً أساسيًا من AlloyDB لمجموعتك في جلسة Cloud Shell نفسها. في حال انقطاع الاتصال، عليك تحديد متغيرات بيئة اسم المنطقة واسم المجموعة مرة أخرى.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

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

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

إنشاء مجموعة AlloyDB Standard

إذا لم تكن هذه هي مجموعة AlloyDB الأولى في المشروع، يمكنك المتابعة لإنشاء مجموعة عادية.

حدِّد المنطقة واسم مجموعة AlloyDB. سنستخدم المنطقة us-central1 وalloydb-aip-01 كاسم مجموعة:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

نفِّذ الأمر التالي لإنشاء المجموعة:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

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

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

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

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

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

علينا إنشاء قاعدة بيانات وتفعيل تكامل Vertex AI وإنشاء عناصر قاعدة البيانات واستيراد البيانات.

منح الأذونات اللازمة إلى AlloyDB

أضِف أذونات Vertex AI إلى وكيل خدمة AlloyDB.

افتح علامة تبويب أخرى في Cloud Shell باستخدام علامة "+" في أعلى الصفحة.

في علامة تبويب 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"

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

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ 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"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

أغلِق علامة التبويب من خلال تنفيذ الأمر "exit" في علامة التبويب:

exit

الربط بـ AlloyDB Studio

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

بعد ذلك، انقر على AlloyDB Studio في يمين الصفحة:

اختَر قاعدة بيانات postgres ومستخدم postgres وأدخِل كلمة المرور التي دوّنتها عند إنشاء المجموعة. بعد ذلك، انقر على الزر "المصادقة".

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

يتم فتح واجهة يمكنك من خلالها تنفيذ أوامر SQL

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

إنشاء قاعدة بيانات باستخدام التشغيل السريع

في "محرّر AlloyDB Studio"، نفِّذ الأمر التالي.

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

CREATE DATABASE quickstart_db

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

Statement executed successfully

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

أعِد الاتصال بالاستوديو باستخدام الزرّ لتبديل المستخدم أو قاعدة البيانات.

اختَر قاعدة البيانات الجديدة quickstart_db من القائمة المنسدلة واستخدِم اسم المستخدم وكلمة المرور نفسها كما كان من قبل.

سيتم فتح اتصال جديد يمكنك من خلاله العمل مع عناصر من قاعدة بيانات quickstart_db.

6. عيّنات البيانات

الآن، علينا إنشاء عناصر في قاعدة البيانات وتحميل البيانات. سنستخدم متجرًا وهميًا باسم "Cymbal ecomm" يتضمّن مجموعة من الجداول للمتاجر على الإنترنت. يحتوي على عدة جداول مرتبطة بمفاتيحها تشبه مخطط قاعدة بيانات ارتباطية.

يتم إعداد مجموعة البيانات ووضعها كملف SQL يمكن تحميله إلى قاعدة البيانات باستخدام واجهة الاستيراد. في Cloud Shell، نفِّذ الأوامر التالية:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters import $ADBCLUSTER --region=$REGION --database=quickstart_db --gcs-uri='gs://sample-data-and-media/ecomm-retail/ecom_generic.sql' --user=postgres --sql

يستخدم الأمر AlloyDB SDK وينشئ مخططًا للتجارة الإلكترونية ثم يستورد بيانات نموذجية مباشرةً من حزمة GCS إلى قاعدة البيانات، ما يؤدي إلى إنشاء جميع العناصر اللازمة وإدراج البيانات.

بعد الاستيراد، يمكننا التحقّق من الجداول في AlloyDB Studio

وتأكَّد من عدد الصفوف في الجدول.

7. ضبط NL SQL

في هذا الفصل، سنضبط ميزة "اللغة الطبيعية" للعمل مع نموذج المخطط.

تثبيت إضافة alloydb_nl_ai

علينا تثبيت إضافة alloydb_ai_nl في قاعدة البيانات. قبل إجراء ذلك، علينا ضبط علامة قاعدة البيانات alloydb_ai_nl.enabled على "مفعَّلة".

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

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb instances update $ADBCLUSTER-pr \
  --cluster=$ADBCLUSTER \
  --region=$REGION \
  --database-flags=alloydb_ai_nl.enabled=on

سيؤدي ذلك إلى بدء عملية تحديث المثيل. يمكنك الاطّلاع على حالة تحديث الجهاز الظاهري في وحدة تحكّم الويب:

عند تعديل المثيل (تكون حالة المثيل خضراء)، يمكنك تفعيل الإضافة alloydb_ai_nl.

في AlloyDB Studio، نفِّذ

CREATE EXTENSION IF NOT EXISTS google_ml_integration;
CREATE EXTENSION alloydb_ai_nl cascade;

إنشاء إعدادات اللغة الطبيعية

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

في AlloyDB Studio، نفِّذ

SELECT
  alloydb_ai_nl.g_create_configuration(
    'cymbal_ecomm_config' 
  );

يمكننا الآن تسجيل مخطط التجارة الإلكترونية في الإعدادات. لقد استوردنا البيانات إلى مخطط التجارة الإلكترونية، لذا سنضيف هذا المخطط إلى إعدادات NL.

SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'cymbal_ecomm_config',
    schema_names_in => '{ecomm}'
  );

8. إضافة سياق إلى NL SQL

إضافة سياق عام

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

في AlloyDB Studio، نفِّذ ما يلي:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'cymbal_ecomm_config',
    general_context_in => '{"If the user doesn''t clearly define preferred brand then use Clades."}'
  );

لننتحقق من كيفية عمل السياق العام بالنسبة إلينا.

في AlloyDB Studio، نفِّذ ما يلي:

SELECT
  alloydb_ai_nl.get_sql(
    'cymbal_ecomm_config', -- nl_config
    'How many products do we have of our preferred brand?' -- nl question
  );

يستخدم طلب البحث الذي تم إنشاؤه علامتنا التجارية التلقائية المحدّدة سابقًا في السياق العام:

{"sql": "SELECT\n COUNT(*)\nFROM \"ecomm\".\"inventory_items\"\nWHERE\n \"product_brand\" = 'Clades';", "method": "default", "prompt": "", "retries": 0, "time(ms)": {"llm": 498.268000, "magic": 885.226000}, "error_msg": "", "nl_question": "How many products do we have of our preferred brand?", "toolbox_used": false}

يمكننا تنظيفها وعرض عبارة SQL فقط كنتيجة.

على سبيل المثال:

SELECT
  alloydb_ai_nl.get_sql(
    'cymbal_ecomm_config', -- nl_config
    'How many products do we have of our preferred brand?' -- nl question
  ) ->> 'sql';

الناتج الذي تم محوه:

SELECT COUNT(*) FROM "ecomm"."inventory_items" WHERE "product_brand" = 'Clades';

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

سياق المخطّط

يصف سياق المخطط عناصر المخطط، مثل الجداول وطرق العرض والأعمدة الفردية التي تخزّن المعلومات كتعليقات في عناصر المخطط.

يمكننا إنشاء ذلك تلقائيًا لجميع عناصر المخطط في الإعدادات المحدّدة باستخدام طلب البحث التالي:

SELECT
  alloydb_ai_nl.generate_schema_context(
    'cymbal_ecomm_config', -- nl_config
    TRUE
  );

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

بعد إنشاء السياق، يمكننا التحقّق من العناصر التي تم إنشاؤها لجدول عناصر المستودع باستخدام طلب البحث التالي:

SELECT
  object_context
FROM
  alloydb_ai_nl.generated_schema_context_view
WHERE
  schema_object = 'ecomm.inventory_items';

الناتج الذي تم محوه:

The `ecomm.inventory_items` table stores information about individual inventory items in an e-commerce system. Each item is uniquely identified by an `id` (primary key). The table tracks the `product_id` (foreign key referencing `ecomm.products`), the timestamp when the item was `created_at`, and the timestamp when it was `sold_at` (which can be null if the item hasn't been sold). The `cost` represents the cost of the item to the business, while `product_retail_price` is the price at which the item is sold. Additional product details include `product_category`, `product_name`, `product_brand`, `product_department`, and `product_sku` (stock keeping unit). The `product_distribution_center_id` (foreign key referencing `ecomm.distribution_centers`) indicates the distribution center where the item is located. The table includes information on both men's and women's apparel across various categories like jeans, tops & tees, activewear, sleep & lounge, intimates, swim, and accessories. The `sold_at` column indicates whether an item has been sold and when.

يبدو أنّ الوصف يفتقد إلى بعض الأجزاء الرئيسية التي يعرضها جدول inventory_items بشأن حركة العناصر. يمكننا تعديلها من خلال إضافة هذه المعلومات الأساسية إلى سياق العلاقة ecomm.inventory_items.

SELECT alloydb_ai_nl.update_generated_relation_context(
  'ecomm.inventory_items',
  'The `ecomm.inventory_items` table stores information about moving and sales of inventory items in an e-commerce system. Each movement is uniquely identified by an `id` (primary key) and used in order_items table as `inventory_item_id`. The table tracks sales and movements for the `product_id` (foreign key referencing `ecomm.products`), the timestamp when the movement for the item was `created_at`, and the timestamp when it was `sold_at` (which can be null if the item hasn''t been sold). The `cost` represents the cost of the item to the business, while `product_retail_price` is the price at which the item is sold. Additional product details include `product_category`, `product_name`, `product_brand`, `product_department`, and `product_sku` (stock keeping unit). The `product_distribution_center_id` (foreign key referencing `ecomm.distribution_centers`) indicates the distribution center where the item is located. The table includes information on both men''s and women''s apparel across various categories like jeans, tops & tees, activewear, sleep & lounge, intimates, swim, and accessories. The `sold_at` column indicates whether an item has been sold and when.'
);

يمكننا أيضًا التحقّق من دقة الوصف لجدول منتجاتنا.

SELECT
  object_context
FROM
  alloydb_ai_nl.generated_schema_context_view
WHERE
  schema_object = 'ecomm.products';

لقد تبيّن لي أنّ السياق الذي يتم إنشاؤه تلقائيًا لجدول المنتجات دقيق جدًا ولا يتطلّب أي تغييرات.

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

لنطبّق السياق الذي تم إنشاؤه على ecomm.inventory_items وecomm.products في عملية الإعداد.

SELECT alloydb_ai_nl.apply_generated_relation_context(
  'ecomm.inventory_items', 
  TRUE
);

SELECT alloydb_ai_nl.apply_generated_relation_context(
  'ecomm.products', 
  TRUE
);

هل تتذكّر طلبنا لإنشاء SQL للسؤال "كم عدد المنتجات التي لدينا من علامتنا التجارية المفضّلة؟" ؟ يمكننا الآن تكرار ذلك ومعرفة ما إذا كان الناتج قد تغيّر.

SELECT
  alloydb_ai_nl.get_sql(
    'cymbal_ecomm_config', -- nl_config
    'How many products do we have of our preferred brand?' -- nl question
  ) ->> 'sql';

إليك الناتج الجديد.

SELECT COUNT(*) FROM "ecomm"."products" WHERE "brand" = 'Clades';

والآن، يتم التحقّق من ecomm.products، وهو أكثر دقة ويعرض حوالي 300 منتج بدلاً من 5,000 عملية تتضمّن سلعًا في المستودع.

9- التعامل مع مؤشر القيمة

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

ضبط "مؤشر القيمة"

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

لننشئ المفهوم ونربطه بالعمود:

SELECT alloydb_ai_nl.add_concept_type(
    concept_type_in => 'brand_name',
    match_function_in => 'alloydb_ai_nl.get_concept_and_value_generic_entity_name',
    additional_info_in => '{
      "description": "Concept type for brand name.",
      "examples": "SELECT alloydb_ai_nl.get_concept_and_value_generic_entity_name(''Auto Forge'')" }'::jsonb
);
SELECT alloydb_ai_nl.associate_concept_type(
    'ecomm.products.brand',
    'brand_name',
    'cymbal_ecomm_config'
);

يمكنك التحقّق من المفهوم من خلال طلب البحث alloydb_ai_nl.list_concept_types()

SELECT alloydb_ai_nl.list_concept_types();

بعد ذلك، يمكننا إنشاء الفهرس في إعداداتنا لجميع عمليات الربط التي تم إنشاؤها والمُنشأة مسبقًا:

SELECT alloydb_ai_nl.create_value_index('cymbal_ecomm_config');

استخدام "مؤشر القيمة"

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

SELECT
  alloydb_ai_nl.get_sql(
    'cymbal_ecomm_config', -- nl_config
    'How many Clades do we have?' -- nl question
  ) ->> 'sql';

ويعرض الناتج التعريف الصحيح للكلمة "Clades" كاسم علامة تجارية

SELECT COUNT(*) FROM "ecomm"."products" WHERE "brand" = 'Clades';

10. العمل باستخدام نماذج طلبات البحث

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

إنشاء نموذج طلب بحث

لننشئ نموذج طلب بحث يربط عدة جداول للحصول على معلومات حول العملاء الذين اشتروا منتجات "Republic Outpost" في العام الماضي. نعلم أنّ طلب البحث يمكن أن يستخدم جدول ecomm.products أو جدول ecomm.inventory_items لأنّ كلاهما يتضمّن معلومات عن العلامات التجارية. ولكن يحتوي الجدول products على 15 مرة أقل من الصفوف وفهرس على المفتاح الأساسي لعملية الربط. قد يكون من الأسهل استخدام جدول المنتجات. لذلك، سننشئ نموذجًا للاستعلام.

SELECT alloydb_ai_nl.add_template(
    nl_config_id => 'cymbal_ecomm_config',
    intent => 'List the last names and the country of all customers who bought products of `Republic Outpost` in the last year.',
    sql => 'SELECT DISTINCT u."last_name", u."country" FROM "ecomm"."users" AS u INNER JOIN "ecomm"."order_items" AS oi ON u.id = oi."user_id" INNER JOIN "ecomm"."products" AS ep ON oi.product_id = ep.id WHERE ep.brand = ''Republic Outpost'' AND oi.created_at >= DATE_TRUNC(''year'', CURRENT_DATE - INTERVAL ''1 year'') AND oi.created_at < DATE_TRUNC(''year'', CURRENT_DATE)',
    sql_explanation => 'To answer this question, JOIN `ecomm.users` with `ecom.order_items` on having the same `users.id` and `order_items.user_id`, and JOIN the result with ecom.products on having the same `order_items.product_id` and `products.id`. Then filter rows with products.brand = ''Republic Outpost'' and by `order_items.created_at` for the last year. Return the `last_name` and the `country` of the users with matching records.',
    check_intent => TRUE
);

يمكننا الآن طلب إنشاء طلب بحث.

SELECT
  alloydb_ai_nl.get_sql(
    'cymbal_ecomm_config', -- nl_config
    'Show me last name and country about customers who bought "Republic Outpost" products last year. 
' -- nl question
  ) ->> 'sql';

وتنتج النتيجة المطلوبة.

SELECT DISTINCT u."last_name", u."country" FROM "ecomm"."users" AS u INNER JOIN "ecomm"."order_items" AS oi ON u.id = oi."user_id" INNER JOIN "ecomm"."products" AS ep ON oi.product_id = ep.id WHERE ep.brand = 'Republic Outpost' AND oi.created_at >= DATE_TRUNC('year', CURRENT_DATE - INTERVAL '1 year') AND oi.created_at < DATE_TRUNC('year', CURRENT_DATE)

أو يمكنك تنفيذ الاستعلام مباشرةً باستخدام الاستعلام التالي:

SELECT
alloydb_ai_nl.execute_nl_query(
    'Show me last name and country about customers who bought "Republic Outpost" products last year.',
    'cymbal_ecomm_config'
);

سيعرض النتائج بتنسيق JSON الذي يمكن تحليله.

                    execute_nl_query
--------------------------------------------------------
 {"last_name":"Adams","country":"China"}
 {"last_name":"Adams","country":"Germany"}
 {"last_name":"Aguilar","country":"China"}
 {"last_name":"Allen","country":"China"}

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

تدمير آلات AlloyDB الافتراضية والمجموعة عند الانتهاء من الدرس التطبيقي

حذف مجموعة AlloyDB وجميع مثيلاتها

يتم تدمير المجموعة باستخدام الخيار force الذي يؤدي أيضًا إلى حذف جميع المثيلات التابعة للمجموعة.

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

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

احذف المجموعة:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

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

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

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

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

حذف نُسخ AlloyDB الاحتياطية

احذف جميع نُسخ AlloyDB الاحتياطية للمجموعة:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

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

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

12. تهانينا

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

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

كيفية نشر AlloyDB for Postgres
كيفية تفعيل ميزة "اللغة الطبيعية" في AlloyDB AI
كيفية إنشاء إعدادات اللغة الطبيعية للذكاء الاصطناعي وضبطها
كيفية إنشاء طلبات بحث بلغة الاستعلامات البنيوية (SQL) والحصول على نتائج باستخدام لغة طبيعية

13. استطلاع

إخراج:

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

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

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