Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

יצירת שאילתות SQL באמצעות שאלות בשפה טבעית

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

כדי להפעיל את התוסף alloydb_ai_nl, שהוא ממשק ה-API לתמיכה בשפה טבעית ב-AlloyDB ל-PostgreSQL, מבצעים את השלבים הבאים:

מתקינים את התוסף alloydb_ai_nl.
הגדרת תצורה בשפה טבעית לאפליקציה.
רישום סכימה.
הוספת הקשר.
הוספת תבניות של שאילתות.
הגדרת סוגי מושגים ויצירת אינדקס ערכים.
יצירת הצהרות SQL באמצעות ממשק שפה טבעית.

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

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

הפעלת התוסף הנדרש

כדי להתקין את התוסף AlloyDB AI natural language ולהשתמש בו, צריך להפעיל אותו באמצעות הוספת הדגל alloydb_ai_nl.enabled.

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

יצירת אשכול והפעלת השילוב של Gemini Enterprise Agent Platform

יצירת אשכול ומכונה של AlloyDB. משתמשים במכונת AlloyDB כדי ליצור את מסד הנתונים של האפליקציה ואת הסכימה.
הפעלת השילוב של פלטפורמת הסוכנים. מידע נוסף זמין במאמר בנושא שילוב עם פלטפורמת סוכנים.

התפקידים הנדרשים

כדי להתקין את התוסף alloydb_ai_nl ולהעניק גישה למשתמשים אחרים, אתם צריכים את התפקיד הבא בניהול הזהויות והרשאות הגישה (IAM) בפרויקט Google Cloud שבו אתם משתמשים:

‫roles/alloydb.admin (תפקיד IAM מוגדר מראש של אדמין AlloyDB)

מידע נוסף זמין במאמר בנושא ניהול משתמשי PostgreSQL באמצעות אימות רגיל.

הכנת הסביבה

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

התקנת התוסף `alloydb_ai_nl`

התוסף alloydb_ai_nl משתמש בתוסף google_ml_integration, שמתקשר עם מודלים גדולים של שפה (LLM), כולל מודלים של Gemini בפלטפורמת הסוכנים.

כדי להתקין את התוסף alloydb_ai_nl, מתחברים למסד הנתונים ומריצים את הפקודה הבאה:

CREATE EXTENSION alloydb_ai_nl cascade;

שדרוג התוסף `alloydb_ai_nl`

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

בודקים אם צריך לשדרג את התוסף. אם התאריך default_version מאוחר יותר מהתאריך installed_version, צריך לשדרג את התוסף.
```
SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';
```
משדרגים את התוסף.
```
ALTER EXTENSION alloydb_ai_nl UPDATE;
```

יצירת הגדרה של שפה טבעית ורישום של סכימה

השפה הטבעית של AlloyDB AI משתמשת ב-nl_config כדי לשייך אפליקציות לסכימות מסוימות, לתבניות של שאילתות ולנקודות קצה של מודלים. ‫nl_config היא הגדרה שמקשרת אפליקציה לסכימה, לתבניות ולהקשרים אחרים. באפליקציה גדולה אפשר להשתמש גם בתצורות שונות לחלקים שונים של האפליקציה, בתנאי שמציינים את התצורה הנכונה כששאלה נשלחת מהחלק הזה של האפליקציה. אתם יכולים לרשום סכימה שלמה, או לרשום אובייקטים ספציפיים בסכימה, כמו טבלאות, תצוגות ועמודות.

כדי ליצור הגדרה של שפה טבעית, משתמשים בדוגמה הבאה:
```
SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );
```
‫gemini-2.0-flash:generateContent היא נקודת הקצה של המודל.

כדי לרשום סכימה להגדרה ספציפית, משתמשים בדוגמה הבאה:

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

הוספת הקשר

הקשר כולל כל סוג של מידע שאפשר להשתמש בו כדי לענות על שאלה של משתמש קצה, למשל:

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

הוספת הקשר כללי לכללים ספציפיים לאפליקציות

פריטי הקשר הכלליים כוללים כללים ספציפיים לאפליקציה, הצהרות של לוגיקה עסקית או כל מינוח ספציפי לאפליקציה ולדומיין שלא מקושר לאובייקט ספציפי של סכימה.

כדי להוסיף הקשר כללי לכללים ספציפיים לאפליקציה ולטרמינולוגיה ספציפית לאפליקציה או לדומיין, פועלים לפי השלבים הבאים:

כדי להוסיף פריט הקשר כללי להגדרה שצוינה, מריצים את השאילתה הבאה:
```
SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );
```
ההצהרה הקודמת עוזרת ל-AlloyDB AI בשפה טבעית לספק תשובות באיכות גבוהה יותר לשאלות של משתמשים בשפה טבעית.
כדי להציג את ההקשרים הכלליים של ההגדרה שצוינה, מריצים את השאילתה הבאה:
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

יצירה ובדיקה של הקשר סכימה

הקשר הסכימה מתאר אובייקטים של סכימה, כולל טבלאות, תצוגות, תצוגות חומריות ועמודות. ההקשר הזה מאוחסן כ-COMMENT של כל אובייקט סכימה.

כדי ליצור הקשרים לאובייקטים של סכימה, קוראים לממשקי ה-API הבאים. כדי לקבל את התוצאות הטובות ביותר, צריך לוודא שטבלאות מסד הנתונים מכילות נתונים מייצגים.
```
-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );
```
כדי לבדוק את ההקשרים של הסכימה שנוצרה, מריצים את השאילתה הבאה:
```
SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;
```
הקשרים של הסכימה שנוצרו מאוחסנים בתצוגה שלמעלה.

אופציונלי: מעדכנים את ההקשרים של הסכימה שנוצרה.

SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

מחילים את ההקשר. כשמחילים את ההקשר, הוא נכנס לתוקף באופן מיידי ונמחק מהתצוגה generated_schema_context_view.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

אופציונלי: מאמתים את ההקשר שנוצר. ממשק ה-API הבא מאפשר לבדוק את הקשרים של הסכימה, שמשמשים כשיוצרים הצהרות SQL.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

החלת הקשר של הסכימה שנוצרה.
```
SELECT alloydb_ai_nl.apply_generated_schema_context(
  'nla_demo_cfg',
  TRUE);
```
העברת TRUE מחליפה את ההקשר הקיים של אובייקטים שרשומים ב-'nla_demo_cfg'.

אופציונלי: הגדרה ידנית של הקשר הסכמה.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

יצירת תבניות של שאילתות

כדי לשפר את האיכות של אפליקציות AI גנרטיבי שמבוססות על מודלים של שפה גדולה (LLM), אפשר להוסיף תבניות. תבנית שאילתה היא אוסף של שאלות מייצגות או נפוצות בשפה טבעית, עם שאילתות SQL תואמות והסברים שמספקים נימוק הצהרתי ליצירת SQL משפה טבעית (NL2SQL). התבניות מיועדות בעיקר לציון על ידי האפליקציה, אבל אפשר גם ליצור אותן באופן אוטומטי על ידי התוסף alloydb_ai_nl על סמך שאילתות SQL שנמצאות בשימוש תדיר. כל תבנית חייבת להיות משויכת לnl_config.

התוסף alloydb_ai_nl משתמש בtemplate_store כדי לשלב באופן דינמי תבניות SQL רלוונטיות בתהליך של יצירת הצהרת SQL למענה על השאלה של משתמש הקצה. ‫template_store מבצע את הפעולות הבאות:

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

אם אין תבנית עם אותה כוונה כמו השאלה שמשתמש הקצה שאל, ‫alloydb_ai_nl משתמש בכל תבנית והקשר רלוונטיים כדי ליצור הצהרת SQL.

הוספת תבנית לחנות התבניות

כדי להוסיף תבניות, מציינים את השאלה באמצעות פרמטר בשם intent ואת שאילתת ה-SQL.

כדי להוסיף תבנית לחנות התבניות, מריצים את השאילתה הבאה:

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    sql => 'SELECT COUNT(T1.account_id)
            FROM bird_dev_financial.account AS T1
            INNER JOIN bird_dev_financial.loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN bird_dev_financial.district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

כשהערך של check_intent הוא TRUE, הפונקציה alloydb_ai_nl מבצעת בדיקה סמנטית כדי לוודא שהכוונה שצוינה תואמת להצהרת ה-SQL שהועברה. אם הכוונה לא תואמת להצהרת ה-SQL, התבנית לא מתווספת.

ה-SQL וה-Intent מכילים פרמטרים של alloydb_ai_nl. התצוגה alloydb_ai_nl.template_store_view חושפת את הצהרות ה-SQL עם הפרמטרים ואת הכוונות שלהן.

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

ההצהרה הזו מחזירה את הערכים הבאים:

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

ציון פרמטרים מותאמים אישית

כדי לספק פרמטריזציה מותאמת אישית להצהרת SQL באמצעות הממשק הידני של הפונקציה add_template, מריצים את ההצהרה בדוגמה הבאה:

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

בהגדרה הקודמת, מופיע פרמטר של הצהרת ה-SQL. הפרמטרים הם $1 ו-$2, בהתאמה, עבור Slokolov ו-1950. המניפסט מסופק כגרסה כללית של הכוונה, שבה הערכים של המילים המילוליות מוחלפים בתיאורים כלליים של הערכים.

בדוגמה הזו, הערך של 1950 ב-Intent מוחלף ב-a given date, והערך של Slokolov מוחלף במניפסט ב-a given city. כשמספקים ערך TRUE לארגומנט האופציונלי check_intent , מתבצע אימות כוונות מבוסס-LLM במהלך add_template. במהלך הבדיקה הזו, אם משפט ה-SQL שצוין לא משקף את המטרה של משפט הכוונה שצוין, add_template נכשלת והסיבה לכך מוצגת כפלט.

בדוגמה הבאה, המטרה של התבנית – כפי שמצוין בכוונת המשתמש – היא לאחזר את מזהה החשבון של החשבונות שמשויכים לעומס ושנמצאים באזור מסוים. הצהרת ה-SQL שצוינה מחזירה את מספר החשבונות, ולא את רשימת מזהי החשבונות, כפי שמוצג בדוגמה הבאה.

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

אם check_intent מוגדר כ-TRUE, אי אפשר להוסיף את התבנית הקודמת לחנות התבניות. אם מריצים את ההצהרה הקודמת, מוחזרת שגיאה שדומה לזו:

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

ניהול תבניות

אפשר לנהל תבניות בחנות התבניות באמצעות ממשקי ה-API הבאים:

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

כשיוצרים תבנית, היא מופעלת כברירת מחדל. תבנית שמושבתת נשארת בחנות התבניות, אבל לא נעשה בה שימוש ב-alloydb_ai_nl לסינתזת שאילתות. אפשר להפעיל תבנית מושבתת באמצעות alloydb_ai_nl.enable_template. הפעלת הפקודה alloydb_ai_nl.drop_template תסיר את התבנית מחנות התבניות באופן סופי.

אפשר להשתמש ב-alloydb_ai_nl.template_store_view כדי לחלץ את template_id של תבנית, בהינתן התוכן שלה. לדוגמה, כדי למצוא את המזהה של תבניות עם כוונת הרכישה accounts that associated with loans, מריצים את השאילתה הבאה, שמחזירה מזהה תבנית ומציינת אם התבנית מופעלת מ-alloydb_ai_nl.template_store_view:

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

עדכון תבנית

כשמשתמשים בתבניות ב-alloydb_ai_nl.template_store_view, חשוב לוודא שהכוונה של כל תבנית עולה בקנה אחד עם הדברים הבאים:

הצהרת SQL
הצהרת SQL עם פרמטרים
הכוונה שמכילה פרמטרים
המניפסט של התבנית

‫alloydb_ai_nl יכול לאחזר תבניות רלוונטיות אם ההטמעה שמתבצעת לתבניות תואמת לתוכן התבנית.

כדי לעדכן תבנית:

מזהים את template_id באמצעות alloydb_ai_nl.template_store_view.
מסירים את התבנית.
מגדירים מחדש את התבנית החדשה עם השינוי הנדרש באמצעות הפונקציה alloydb_ai_nl.add_template.

יצירת קטעי שאילתות

אפשר להתאים תבניות בזמן השאילתה באמצעות פרגמנטים, שעוזרים לתבניות של שאילתות לבצע חיפוש עם היבטים שונים, כמו שאלות בשפה טבעית. פרגמנט הוא קבוצה שנבחרה בקפידה של תנאים מייצגים או נפוצים בשפה טבעית עם פרדיקטים תואמים של SQL. האפליקציה אמורה לציין את הקטעים.

כל מקטע צריך להיות משויך ל-nl_config_id ולמערך של טבלאות ותצוגות עם כינויים שהפרדיקט של המקטע חל עליהם. אפשר לאמת את המטרה של פרגמנט כשארגומנט check_intent מוגדר ל-TRUE. תוסף alloydb_ai_nl יכול להשתמש בתבנית עם שילוב של קטעי מידע כדי לסנתז את התשובה לשאילתה בשפה טבעית.

התוסף alloydb_ai_nl משתמש ב-fragment_store כדי לשלב באופן דינמי את התנאים בקטעים רלוונטיים בתהליך של יצירת הצהרת SQL, במטרה לענות על השאלה של משתמש הקצה. קודם כל, template_store מזהה תבניות עם כוונות דומות לשאלה בשפה הטבעית שהמשתמש הקצה שאל. בשלב הבא, המערכת מאחזרת את הפרגמנטים שיכולים לספק התמחות לתבניות שזוהו. החלפת הפרמטרים מתבצעת גם בתבניות וגם בקטעי קוד כדי ליצור הצהרת SQL.

ערכי הפרמטרים מחולצים מהשאלה בשפה טבעית ומוחלפים על ידי מודל ה-LLM באמצעות הדפוסים שמשתמעים מתבניות ומקטעים רלוונטיים. עם זאת, אם השילוב של התבניות והקטעים לא משרת את אותה מטרה של השאלה שהמשתמש הקצה שאל, alloydb_ai_nl משתמש בכל תבנית והקשר רלוונטיים כדי ליצור הצהרת SQL.

הוספת פרגמנט

כדי להוסיף פרגמנט, מריצים את השאילתות הבאות לדוגמה באמצעות הפונקציה alloydb_ai_nl.add_fragment. כל מקטע חייב להיות משויך למזהה nl_config_id מהאפליקציה.

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

כשמפעילים את alloydb_ai_nl.add_fragment, התוסף alloydb_ai_nl מחלץ מניפסט מהכוונה שסופקה, ואם אפשר, התוסף מגדיר פרמטרים לכוונה ולתנאי של הקטע. תצוגות כמו alloydb_ai_nl.fragment_store_view חושפות את המקטעים הזמינים, כמו בדוגמה הבאה:

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

השאילתה מחזירה קבוצת תוצאות שדומה לזו:

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

קובץ מניפסט ב-Fragment נוצר אוטומטית מתוך כוונת המשתמש, והוא מייצג גרסה מוכללת של כוונת המשתמש. לדוגמה, המספרים 6000 ו-10000 בכוונת המשתמש מוחלפים ב-a given number במניפסט. המספרים מוחלפים ב-$2 וב-$1, בהתאמה, בעמודות pfragment ו-pintent. העמודות pfragment ו-pintent ב-alloydb_ai_nl.fragment_store_view הן, בהתאמה, הייצוג עם הפרמטרים של fragment ו-intent.

כדי לספק פרמטריזציה מותאמת אישית של קטע, צריך להשתמש בגרסה הידנית של alloydb_ai_nl.add_fragment, כמו בדוגמה הבאה:

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

ניהול פרגמנטים

כדי לנהל פרגמנטים, משתמשים בממשקי ה-API הבאים:

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

אתם יכולים להשתמש בתצוגה alloydb_ai_nl.fragment_store_view כדי לחלץ את fragment_id של קטע, בהינתן התוכן שלו. לדוגמה, כדי למצוא את המזהה של קטע עם הכוונה Average salary between 6000 and 10000, מריצים את השאילתה הבאה לדוגמה:

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

עדכון מקטע

כשמעדכנים קטע, חשוב לוודא שהכוונה של הקטע עקבית עם הדברים הבאים:

המניפסט והצהרת ה-SQL של הפראגמנט
הצהרת SQL עם פרמטרים
הכוונה שמכילה פרמטרים

כדי לשמור על עקביות כשמעדכנים קטע, פועלים לפי השלבים הבאים:

מסירים את החלק שרוצים לשנות באמצעות הפונקציה alloydb_ai_nl.drop_fragment.
מכניסים את הקטע המעודכן באמצעות הפונקציה alloydb_ai_nl.add_fragment.

יצירה אוטומטית של תבניות

אחרי שיהיה לכם מערך נתונים מייצג בטבלאות, מומלץ להריץ שאילתות SQL שמתאימות לשאלות הנפוצות שמשתמשי הקצה שלכם עשויים לשאול. חשוב לוודא שלשאילתות יש תוכניות שאילתה מלאות ושהן פועלות בצורה טובה.

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

יצירת התבנית באופן אוטומטי מבוססת על השאילתות הנפוצות ביותר ביומן השאילתות, google_db_advisor_workload_statements. השאילתות מסוננות לפי הקריטריונים הבאים:

SELECT דוחות
קובצי הפעלה: אפשר לעבד את השאילתה בהצלחה באמצעות הפקודה EXPLAIN.
ללא כפילויות: השאילתה לא שימשה בעבר ליצירת תבניות.
כל הטבלאות והתצוגות שאליהן יש הפניה נמצאות בהיקף של nl_config.

כדי ליצור תבניות באופן אוטומטי, לבדוק אותן ולהחיל אותן, פועלים לפי השלבים הבאים:

מבקשים מ-AlloyDB ליצור תבניות על סמך היסטוריית השאילתות:
```
SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);
```
כדאי להשתמש בתצוגה שסיפקת, alloydb_ai_nl.generated_templates_view, כדי לבדוק את generated_templates.

בפלט הבא מוצג מספר התבניות שנוצרו:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

בודקים את התבניות שנוצרו באמצעות התצוגה של generated_templates_view.

SELECT *
FROM alloydb_ai_nl.generated_templates_view;

דוגמה לפלט שמתקבל:

-[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

התוכן manifest בפלט שמוחזר הוא תבנית כללית או תיאור רחב של סוג השאלה או הפעולה שאפשר לבצע. ‫pintent היא גרסה עם פרמטרים של intent, והיא מכלילה את intent על ידי החלפת הערך הספציפי (1997) במציין מיקום ($1).

כדי לעדכן תבנית שנוצרה, מריצים את הצהרת הדוגמה הבאה:

SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

החלת התבניות. התבניות שאתם מחילים מתווספות מיד לחנות התבניות, והן נמחקות מתצוגת הבדיקה.
```
-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');
```

הגדרת אבטחה לשפה טבעית

כדי להגדיר אבטחה לשפה טבעית ב-AlloyDB AI, אפשר לעיין במאמר בנושא ניהול אבטחת נתונים באפליקציות באמצעות תצוגות מאובטחות עם פרמטרים.

הגדרת סוגי מושגים ומדדי ערך

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

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

אינדקס ערכים הוא אינדקס של הערכים בעמודות שכלולות בהגדרת השפה הטבעית nl_config, שמבוסס על סוגי המושגים שמשויכים לכל עמודה. אינדקס ערכים מאפשר התאמה יעילה של ביטויי ערכים לשאלה שנשאלת ולערכים במסד הנתונים.

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

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

SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

כדי ליצור אינדקס ערכים שמבוסס על כל העמודות שכלולות בהגדרת שפה טבעית ומשויכות לסוג מושג, מריצים את ההצהרה הבאה:
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
כשמשייכים סוגי מושגים לעמודות חדשות, צריך לרענן את אינדקס הערכים כדי שהשינויים יבואו לידי ביטוי.
```
SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
כדי להפעיל את השפה הטבעית של AlloyDB AI כדי להתאים מילים נרדפות לערך, מריצים את הצהרת הדוגמה הבאה:
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
למרות שבנתונים בטבלאות יכול להיות שיש ערך ספציפי – למשל, אם נעשה שימוש ב-United States כדי לזהות מדינה – אתם יכולים להגדיר קבוצת מילים נרדפות שמכילה את כל המילים הנרדפות ל-United States. אם אחד מהמילים הנרדפות מופיע בשאלה בשפה טבעית, AlloyDB AI מתאים את המילים הנרדפות לערכים בטבלאות.

מבצעים חיפוש ערכים כדי למצוא את הערכים הנכונים במסד הנתונים, בהינתן מערך של ביטויי ערכים.

SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

לדוגמה, אם משתמש שואל שאלה כמו 'מה מספר התושבים בארצות הברית?' באמצעות שאילתת get_sql הבאה, השפה הטבעית של AlloyDB AI משתמשת בפונקציה get_concept_and_value עם ערך הביטוי United States כדי לבצע חיפוש משוער באינדקסים של הערכים. חיפוש משוער הוא טכניקת חיפוש שמוצאת התאמות גם כששאילתת החיפוש לא תואמת בדיוק לנתונים המתאימים.

השפה הטבעית מוצאת תוצאה – הערך USA – שקרובה לשאילתת החיפוש, ומשתמשת בתוצאה הזו כדי ליצור את שאילתת ה-SQL.

SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

בטבלה הבאה מפורטים סוגי המושגים המובנים שמוגדרים בשפה הטבעית של AlloyDB AI.

שם הרעיון	תיאור
`generic_entity_name`	אפשר להשתמש בעמודה מסוג מחרוזת יחידה לשם של ישות כללית. לדוגמה: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
`country_name`, `city_name`, `region_name`	שמות של מדינות, ערים ואזורים. השימוש זהה בדיוק לשימוש בסוג המושג `generic_entity_name`.
`full_person_name`	שם האדם, שכולל את השם הפרטי, שם המשפחה והשם האמצעי. אפשר להשתמש בעד שלוש עמודות מסוג מחרוזת כדי לציין את השם המלא של האדם. אפשר לדלג על כל אחת מהעמודות כשמשייכים עמודות של שמות אל `full_person_name`. לדוגמה: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	עמודה אחת של מחרוזת שמכילה מספר תעודת זהות. לדוגמה: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
`date`	תאריך או חותמת זמן. לדוגמה: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

יצירה אוטומטית של שיוכים לסוגי קונספט

כדי לשייך עמודות לסוגי מושגים באופן אוטומטי, משתמשים בתכונה של שיוך אוטומטי של סוגי מושגים ב-AlloyDB AI Natural Language API. שיוך של סוג קונספט מגדיר את הקשר בין סוג קונספט לבין עמודה אחת או יותר במסד נתונים. זהו תנאי מוקדם ליצירת אינדקסים של ערכים.

כדי ליצור שיוכים אוטומטיים של סוגי מושגים:

כדי ליצור שיוכים, קוראים לממשקי ה-API הבאים.

-- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

מריצים את השאילתה הבאה כדי לבדוק את השיוכים שנוצרו.
```
SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;
```

אופציונלי: מעדכנים את השיוכים שנוצרו.

-- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

אופציונלי: הסרת שיוך שנוצר.

SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

החלת השיוכים שנוצרו.

-- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

כדי שהשינויים יבואו לידי ביטוי, צריך לרענן את מדד הערכים.
```
SELECT alloydb_ai_nl.refresh_value_index(
  nl_config_id_in => 'my_app_config'
);
```

יצירת הצהרות SQL מקלט בשפה טבעית

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

כדי להשתמש בשפה טבעית כדי לקבל תוצאות ממסד הנתונים באמצעות הפונקציה alloydb_ai_nl.get_sql, אפשר להשתמש בדוגמה הבאה:

SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

מוחזר פלט ה-JSON הבא:

{
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

אופציונלי: כדי לחלץ את שאילתת ה-SQL שנוצרה כמחרוזת טקסט, מוסיפים את ->>'sql':
```
SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';
```
האופרטור ->> משמש לחילוץ ערך JSON כטקסט. הפונקציה alloydb_ai_nl.get_sql מחזירה אובייקט JSON, שהוא החלק של ההצהרה שמחלץ את הערך שמשויך למפתח sql. הערך הזה הוא שאילתת ה-SQL שנוצרה.

יצירת סיכומי תוצאות מקלט של שפה טבעית

אתם יכולים להשתמש בשפה טבעית ב-AlloyDB AI כדי ליצור סיכומי תוצאות מקלט בשפה טבעית. הפונקציה alloydb_ai_nl.get_sql_summary מבצעת באופן מאובטח את השאלה בשפה טבעית בטבלה הבסיסית, מסכמת מדגם של קבוצת התוצאות ומחזירה את הסיכום בשפה טבעית.

כדי ליצור סיכום של תוצאות לשאלה בשפה טבעית במסד הנתונים, משתמשים בפונקציה alloydb_ai_nl.get_sql_summary כמו בדוגמה הבאה:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

הפעלת ההצהרה הקודמת יוצרת את אובייקט ה-JSON הבא לדוגמה:

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

אפשר לאבטח את הטבלאות והתצוגות שהשאילתה ניגשת אליהן ב-alloydb_ai_nl.get_sql_summary באמצעות תצוגות מאובטחות עם פרמטרים. השמות של הפרמטרים והערכים שלהם זמינים לאפליקציה, והם נדרשים על ידי alloydb_ai_nl.get_sql_summary.

לדוגמה, יכול להיות שהאפליקציה תרצה לספק את הפרמטר user_id למשתמש מאומת עם מזהה משתמש 123. כדי לעשות את זה, צריך לספק את הערכים param_names ו-param_values, כמו בדוגמה הבאה:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

הוספת הארגומנטים param_names ו-param_values מבטיחה שאם אפשר לענות על nl_question באמצעות הצהרת SQL שנאכפת על ידי תצוגות מאובטחות עם פרמטרים, מסנני האבטחה שצוינו יחולו כשמפיקים את קבוצת התוצאות ויוצרים את הסיכום.

בדיקה ושיפור

כדי לשפר את השאילתות שנוצרות באופן אוטומטי, כדאי לשנות או להוסיף הקשר טוב יותר, תבניות של שאילתות ואינדקסים של ערכים, ואז לחזור על הפעולה עד שתקבלו את התוצאות הרצויות.