SQL را با استفاده از زبان طبیعی AlloyDB AI تولید کنید

1. مقدمه

1dc4e2c0ebd1aa4c.png

در این نرم افزار کد، نحوه استقرار AlloyDB و استفاده از زبان طبیعی هوش مصنوعی برای پرس و جو کردن داده ها و تنظیم پیکربندی برای پرس و جوهای قابل پیش بینی و کارآمد را خواهید آموخت. این آزمایشگاه بخشی از مجموعه آزمایشگاهی است که به ویژگی های هوش مصنوعی AlloyDB اختصاص دارد. می توانید اطلاعات بیشتری را در صفحه AlloyDB AI در مستندات بخوانید.

پیش نیازها

  • درک اولیه از Google Cloud، کنسول
  • مهارت های اولیه در رابط خط فرمان و Cloud Shell

چیزی که یاد خواهید گرفت

  • نحوه استقرار AlloyDB برای Postgres
  • چگونه زبان طبیعی AlloyDB AI را فعال کنیم
  • نحوه ایجاد و تنظیم پیکربندی برای زبان طبیعی هوش مصنوعی
  • چگونه با استفاده از زبان طبیعی پرس و جوهای SQL تولید کنیم و نتیجه بگیریم

آنچه شما نیاز دارید

  • یک حساب Google Cloud و پروژه Google Cloud
  • یک مرورگر وب مانند کروم که از کنسول Google Cloud و Cloud Shell پشتیبانی می کند

2. راه اندازی و الزامات

تنظیم محیط خود به خود

  1. به Google Cloud Console وارد شوید و یک پروژه جدید ایجاد کنید یا از یک موجود استفاده مجدد کنید. اگر قبلاً یک حساب Gmail یا Google Workspace ندارید، باید یک حساب ایجاد کنید .

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • نام پروژه نام نمایشی برای شرکت کنندگان این پروژه است. این یک رشته کاراکتری است که توسط API های Google استفاده نمی شود. همیشه می توانید آن را به روز کنید.
  • شناسه پروژه در تمام پروژه‌های Google Cloud منحصربه‌فرد است و تغییرناپذیر است (پس از تنظیم نمی‌توان آن را تغییر داد). Cloud Console به طور خودکار یک رشته منحصر به فرد تولید می کند. معمولاً برای شما مهم نیست که چیست. در اکثر کدها، باید شناسه پروژه خود را ارجاع دهید (معمولاً با نام PROJECT_ID شناخته می شود). اگر شناسه تولید شده را دوست ندارید، ممکن است یک شناسه تصادفی دیگر ایجاد کنید. از طرف دیگر، می‌توانید خودتان را امتحان کنید، و ببینید آیا در دسترس است یا خیر. پس از این مرحله نمی توان آن را تغییر داد و در طول مدت پروژه باقی می ماند.
  • برای اطلاع شما، یک مقدار سوم وجود دارد، یک شماره پروژه ، که برخی از API ها از آن استفاده می کنند. در مورد هر سه این مقادیر در مستندات بیشتر بیاموزید.
  1. در مرحله بعد، برای استفاده از منابع Cloud/APIها باید صورتحساب را در کنسول Cloud فعال کنید . اجرا کردن از طریق این کد لبه هزینه زیادی نخواهد داشت. برای خاموش کردن منابع برای جلوگیری از تحمیل صورت‌حساب فراتر از این آموزش، می‌توانید منابعی را که ایجاد کرده‌اید حذف کنید یا پروژه را حذف کنید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان 300 دلاری هستند.

Cloud Shell را راه اندازی کنید

در حالی که Google Cloud را می توان از راه دور از لپ تاپ شما کار کرد، در این کد لبه از Google Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان که در Cloud اجرا می شود.

از Google Cloud Console ، روی نماد Cloud Shell در نوار ابزار بالا سمت راست کلیک کنید:

55efc1aaa7a4d3ad.png

تهیه و اتصال به محیط فقط چند لحظه طول می کشد. وقتی تمام شد، باید چیزی شبیه به این را ببینید:

7ffe5cbb04455448.png

این ماشین مجازی با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این یک فهرست اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد و احراز هویت شبکه را تا حد زیادی افزایش می دهد. تمام کارهای شما در این کد لبه را می توان در یک مرورگر انجام داد. شما نیازی به نصب چیزی ندارید.

3. قبل از شروع

فعال کردن API

در داخل Cloud Shell، مطمئن شوید که ID پروژه شما تنظیم شده است:

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 استفاده شود. اگر آن را نداریم، باید آن را ایجاد کنیم، آن را اختصاص دهیم تا توسط سرویس‌های داخلی گوگل استفاده شود و پس از آن می‌توانیم خوشه و نمونه را ایجاد کنیم.

محدوده 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 برای خوشه خود ایجاد کنید. اگر اتصال شما قطع شده است، باید دوباره متغیرهای محیط نام منطقه و خوشه را تعریف کنید.

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 را ایجاد کنید

اگر اولین خوشه 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.

در همان جلسه پوسته ابری، یک نمونه اولیه AlloyDB برای خوشه خود ایجاد کنید. اگر اتصال شما قطع شده است، باید دوباره متغیرهای محیط نام منطقه و خوشه را تعریف کنید.

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 را با استفاده از علامت "+" در بالا باز کنید.

4ca978f5142bb6ce.png

در تب جدید پوسته ابری اجرا کنید: 

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 اجرا کرد. برای اجرای دستور باید رابط کنسول وب را برای خوشه AlloyDB خود با کلیک بر روی نمونه اولیه باز کنید.

ef4bfbcf0ed2ef3a.png

سپس روی AlloyDB Studio در سمت چپ کلیک کنید:

5c155cbcd7d43a1.png

پایگاه داده postgres، user postgres را انتخاب کنید و رمز عبوری را که هنگام ایجاد کلاستر ذکر شده است، ارائه دهید. سپس بر روی دکمه "Authenticate" کلیک کنید.

1c9dab73c6836798.png

رابط AlloyDB Studio را باز می کند. برای اجرای دستورات در پایگاه داده، روی تب "Editor 1" در سمت راست کلیک کنید.

b36c28f8165119ca.png

این رابط را باز می کند که در آن می توانید دستورات SQL را اجرا کنید

cf43aa20f292797e.png

ایجاد پایگاه داده

ایجاد شروع سریع پایگاه داده

در ویرایشگر AlloyDB Studio دستور زیر را اجرا کنید.

ایجاد پایگاه داده: 

CREATE DATABASE quickstart_db

خروجی مورد انتظار: 

Statement executed successfully

به Quickstart_db متصل شوید

با استفاده از دکمه تغییر کاربر/پایگاه داده، دوباره به استودیو متصل شوید.

e826ad973eb23a74.png

پایگاه داده جدید quickstart_db را از لیست کشویی انتخاب کنید و از همان کاربر و رمز عبور قبلی استفاده کنید.

1ca70c59b5aea8c1.png

این یک اتصال جدید را باز می کند که در آن می توانید با اشیاء از پایگاه داده quickstart_db کار کنید.

6. داده های نمونه

حالا باید آبجکت هایی را در پایگاه داده ایجاد کنیم و داده ها را بارگذاری کنیم. ما قصد داریم از فروشگاه خیالی "Cymbal ecomm" با مجموعه ای از جداول برای فروشگاه های آنلاین استفاده کنیم. این شامل چندین جدول است که با کلیدهای آنها شبیه به یک طرح پایگاه داده رابطه ای متصل شده اند.

مجموعه داده آماده شده و به عنوان یک فایل SQL قرار می گیرد که می تواند با استفاده از رابط واردات در پایگاه داده بارگذاری شود. در پوسته ابری دستورات زیر را اجرا کنید: 

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 استفاده می‌کند و یک طرح ecomm ایجاد می‌کند و سپس داده‌های نمونه را مستقیماً از سطل GCS به پایگاه داده وارد می‌کند و تمام اشیاء لازم را ایجاد می‌کند و داده‌ها را درج می‌کند.

پس از وارد کردن، می توانیم جداول را در استودیو AlloyDB بررسی کنیم

9ee57986d4cdf20f.png

و تعداد ردیف های جدول را بررسی کنید.

541ae6486ea6abb0.png

7. NL SQL را پیکربندی کنید

در این فصل ما NL را برای کار با طرح نمونه شما پیکربندی می کنیم

پسوند alloydb_nl_ai را نصب کنید

ما باید پسوند alloydb_ai_nl را در پایگاه داده خود نصب کنیم. قبل از انجام این کار، باید پایگاه داده flag alloydb_ai_nl.enabled را در on تنظیم کنیم.

در جلسه 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

به روز رسانی نمونه را آغاز می کند. می توانید وضعیت نمونه به روز رسانی را در کنسول وب مشاهده کنید:

c296406c0aaf14c3.png

هنگامی که نمونه به روز می شود (وضعیت نمونه سبز است) می توانید پسوند alloydb_ai_nl را فعال کنید.

در استودیو AlloyDB اجرا کنید 

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

یک پیکربندی زبان طبیعی ایجاد کنید

برای استفاده از افزونه ها باید یک پیکربندی ایجاد کنیم. این پیکربندی برای مرتبط کردن برنامه‌ها با طرحواره‌های خاص، قالب‌های پرس و جو و نقاط پایانی مدل ضروری است. بیایید یک پیکربندی با id cymbal_ecomm_config ایجاد کنیم.

در استودیو AlloyDB اجرا کنید 

SELECT
  alloydb_ai_nl.g_create_configuration(
    'cymbal_ecomm_config' 
  );

اکنون می توانیم طرح ecomm خود را در پیکربندی ثبت کنیم. ما داده‌ها را به طرح ecomm وارد کرده‌ایم، بنابراین می‌خواهیم آن طرح را به پیکربندی NL خود اضافه کنیم. 

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

8. Context را به NL SQL اضافه کنید

اضافه کردن زمینه کلی

ما می توانیم زمینه ای برای طرحواره ثبت شده خود اضافه کنیم. این زمینه قرار است به ایجاد نتایج بهتر در بازگشت به درخواست‌های کاربران کمک کند. برای مثال می‌توانیم بگوییم که یک نام تجاری برای کاربر ترجیح داده می‌شود، در صورتی که به صراحت تعریف نشده باشد. بیایید Clades (مارک خیالی) را به عنوان مارک پیش فرض خود قرار دهیم.

در استودیو AlloyDB اجرا کنید: 

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 اجرا کنید: 

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_item برای ردیابی فروش استفاده می‌کند که اگر اطلاعات داخلی نداشته باشید ممکن است گمراه‌کننده باشد. ما بعداً بررسی خواهیم کرد که چگونه سؤالات خود را دقیق تر کنیم.

زمینه طرحواره

زمینه طرحواره، اشیای طرحواره مانند جداول، نماها و ستون‌های مجزا را توصیف می‌کند که اطلاعات را به‌عنوان نظرات در اشیای طرحواره ذخیره می‌کنند.

ما می توانیم آن را به طور خودکار برای تمام اشیاء طرحواره در پیکربندی تعریف شده با استفاده از پرس و جو زیر ایجاد کنیم: 

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 است که دقیق تر است و به جای 5000 عملیات با اقلام موجودی، حدود 300 محصول را برمی گرداند.

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. کار با Query Templates

قالب های پرس و جو به تعریف پرس و جوهای پایدار برای برنامه های کاربردی مهم تجاری کمک می کنند و عدم اطمینان را کاهش می دهند و دقت را بهبود می بخشند.

یک قالب Query ایجاد کنید

بیایید یک الگوی پرس و جو ایجاد کنیم که چندین جدول را به هم بپیوندد تا اطلاعاتی در مورد مشتریانی که محصولات "Republic Outpost" را در سال گذشته خریداری کرده اند به دست آوریم. می دانیم که پرس و جو می تواند از جدول ecomm.products یا جدول ecomm.inventory_items استفاده کند زیرا هر دو اطلاعاتی در مورد مارک ها دارند. اما محصولات جدول دارای 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 و همه نمونه ها را حذف کنید

خوشه با نیروی گزینه از بین می رود که همچنین تمام نمونه های متعلق به خوشه را حذف می کند.

در پوسته ابری، متغیرهای پروژه و محیط را تعریف کنید، اگر اتصال شما قطع شده و تمام تنظیمات قبلی از بین رفته است: 

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 را در این Codelab بررسی کنید.

آنچه را پوشش داده ایم

  • نحوه استقرار AlloyDB برای Postgres
  • چگونه زبان طبیعی AlloyDB AI را فعال کنیم
  • نحوه ایجاد و تنظیم پیکربندی برای زبان طبیعی هوش مصنوعی
  • چگونه با استفاده از زبان طبیعی پرس و جوهای SQL تولید کنیم و نتیجه بگیریم

13. نظرسنجی

خروجی:

چگونه از این آموزش استفاده خواهید کرد؟

فقط آن را بخوانید آن را بخوانید و تمرینات را کامل کنید