דף זה תורגם על ידי Cloud Translation API.

יצירת SQL באמצעות שפה טבעית ב-AlloyDB AI

1. מבוא

ב-codelab הזה תלמדו איך לפרוס את AlloyDB ואיך להשתמש בשפה טבעית מבוססת-AI כדי לשלוח שאילתות לנתונים ולשנות את ההגדרות כדי לקבל שאילתות צפויות ויעילות. ה-Lab הזה הוא חלק מאוסף של Labs שמוקדשים לתכונות של AlloyDB AI. מידע נוסף זמין בדף AlloyDB AI בתיעוד.

דרישות מוקדמות

הבנה בסיסית של Google Cloud ושל המסוף
מיומנויות בסיסיות בממשק שורת הפקודה וב-Cloud Shell

מה תלמדו

איך פורסים את AlloyDB ל-Postgres
איך מפעילים את השפה הטבעית של AlloyDB AI
איך יוצרים ומכווננים הגדרה של שפה טבעית מבוססת-AI
איך ליצור שאילתות SQL ולקבל תוצאות באמצעות שפה טבעית

מה צריך

חשבון Google Cloud ופרויקט Google Cloud
דפדפן אינטרנט כמו Chrome שתומך במסוף Google Cloud וב-Cloud Shell

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

נכנסים ל-Google Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, אתם צריכים ליצור חשבון.

שם הפרויקט הוא השם המוצג למשתתפים בפרויקט. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית. בדרך כלל לא צריך לדעת מה היא. ברוב ה-Codelabs, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-PROJECT_ID). אם אתם לא אוהבים את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא נשארת לאורך הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים נוספים אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.

הפעלת Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-Google Cloud Console, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:

המכונה הווירטואלית הזו כוללת את כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות של הרשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.

3. לפני שמתחילים

הפעלת ה-API

ב-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, צריך להגדיר ב-VPC טווח כתובות IP פרטיות שיהיה זמין לשימוש על ידי מכונת 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

בפרקים הבאים, אפשר להריץ ב-AlloyDB Studio את כל פקודות ה-SQL שדורשות חיבור למסד הנתונים. כדי להריץ את הפקודה, צריך לפתוח את ממשק מסוף האינטרנט של אשכול AlloyDB על ידי לחיצה על המופע הראשי.

אחר כך לוחצים על AlloyDB Studio בצד ימין:

בוחרים את מסד הנתונים של postgres, את המשתמש postgres ומזינים את הסיסמה שרשמתם כשיצרתם את האשכול. לאחר מכן לוחצים על הלחצן 'אימות'.

ממשק AlloyDB Studio ייפתח. כדי להריץ את הפקודות במסד הנתונים, לוחצים על הכרטיסייה Editor 1 (עורך 1) בצד שמאל.

ייפתח ממשק שבו אפשר להריץ פקודות SQL

יצירת מסד נתונים

מדריך להתחלה מהירה ליצירת מסד נתונים

בעורך של AlloyDB Studio, מריצים את הפקודה הבאה.

יצירת מסד נתונים:

CREATE DATABASE quickstart_db

הפלט אמור להיראות כך:

Statement executed successfully

התחברות ל-quickstart_db

מתחברים מחדש ל-Studio באמצעות הלחצן להחלפת משתמש או מסד נתונים.

בוחרים את מסד הנתונים החדש 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

בפרק הזה נגדיר את NL כך שיפעל עם סכימת הדוגמה

התקנה של התוסף alloydb_nl_ai

צריך להתקין את התוסף alloydb_ai_nl במסד הנתונים. לפני שמבצעים את הפעולה הזו, צריך להגדיר את דגל מסד הנתונים 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

העדכון של המופע יתחיל. אפשר לראות את הסטטוס של עדכון המכונה במסוף האינטרנט:

אחרי שהמופע מתעדכן (הסטטוס של המופע ירוק), אפשר להפעיל את התוסף 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 במקום בטבלה products, והשתמשה בה כדי ליצור את השאילתה. יכול להיות שזה יעבוד במקרים מסוימים, אבל לא בסכימה שלנו. במקרה שלנו, הטבלה 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. עבודה עם מדד הערך

קישור ערכים משפר את השאילתות בשפה טבעית על ידי קישור של צירופי מילים שמייצגים ערכים לסוגי מושגים ולשמות עמודות שרשומים מראש. זה יכול לעזור להפוך את התוצאות לצפויות יותר.

הגדרת מדד הערך

אנחנו יכולים ליצור את השאילתות שלנו באמצעות העמודה brand בטבלה products ולחפש מוצרים עם מותגים יציבים יותר על ידי הגדרת סוג המושג ושיוכו לעמודה 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 כשמסיימים את שיעור ה-Lab

מחיקת אשכול 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. מזל טוב

כל הכבוד, סיימתם את ה-Codelab. עכשיו אפשר לנסות להטמיע פתרונות משלכם באמצעות התכונות של NL2SQL ב-AlloyDB. מומלץ לנסות מדריכי Codelab נוספים שקשורים ל-AlloyDB ול-AlloyDB AI. ב-codelab הזה מוסבר איך הטמעות מולטימודאליות פועלות ב-AlloyDB.

מה למדנו

איך פורסים את AlloyDB ל-Postgres
איך מפעילים את השפה הטבעית של AlloyDB AI
איך יוצרים ומכווננים הגדרה של שפה טבעית מבוססת-AI
איך ליצור שאילתות SQL ולקבל תוצאות באמצעות שפה טבעית

13. סקר

פלט:

איך תשתמשו במדריך הזה?

רק קוראים את המידע

קוראים את המידע ומבצעים את התרגילים