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

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

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

  1. מתקינים את התוסף alloydb_ai_nl.
  2. הגדירו את האפליקציה בשפה טבעית.
  3. רושמים סכימה.
  4. הוספת הקשר.
  5. הוספת תבניות של שאילתות.
  6. הגדירו סוגי קונספטים וצרו אינדקס ערכים.
  7. ליצור הצהרות SQL באמצעות ממשק בשפה טבעית.

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

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

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

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

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

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

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

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

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

הכנת הסביבה

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

התקנת התוסף alloydb_ai_nl

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

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

CREATE EXTENSION alloydb_ai_nl cascade;

שדרוג התוסף alloydb_ai_nl

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

  1. בודקים אם צריך לשדרג את התוסף. אם default_version מאוחרת יותר מ-installed_version, צריך לשדרג את התוסף.

    SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';

  2. משדרגים את התוסף.

    ALTER EXTENSION alloydb_ai_nl UPDATE;

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

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

  1. כדי ליצור הגדרה של שפה טבעית, אפשר להשתמש בדוגמה הבאה:

    SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

    ‫gemini-3.5-flash-lite:generateContent היא נקודת הקצה של המודל שמוגדרת כברירת מחדל.

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

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

הוספת הקשר

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

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

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

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

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

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

    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 לספק תשובות איכותיות יותר לשאלות של המשתמשים בשפה טבעית.

  2. כדי לראות את ההקשרים הכלליים של ההגדרות שצוינו, מריצים את השאילתה הבאה:

    SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);

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

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

  1. כדי ליצור הקשרים לאובייקטים של סכימה, צריך להפעיל את ממשקי ה-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
  );

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

    SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;

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

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

    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.'
  );

  4. החלת ההקשר. כשמחילים את ההקשר, הוא נכנס לתוקף באופן מיידי ונמחק מהתצוגה 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
  );

  5. אופציונלי: בודקים את ההקשר שנוצר. באמצעות ה-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'
  );

  6. מחילים את הקשר הסכימה שנוצר.

    SELECT alloydb_ai_nl.apply_generated_schema_context(
  'nla_demo_cfg',
  TRUE);

    העברת TRUE מחליפה את ההקשר הקיים של אובייקטים שרשומים ב-"nla_demo_cfg".

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

    -- 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 שהועברה. אם ה-intent לא תואם להצהרת ה-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. המניפסט מסופק כגרסה כללית של ה-Intent, שבה הערכים של הליטרלים מוחלפים בתיאורים כלליים של הערכים.

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

בדוגמה הבאה, המטרה של התבנית – כפי שצוין ב-intent – היא לאחזר את מזהה החשבון של החשבונות שמשויכים לעומס ונמצאים באזור מסוים. הצהרת ה-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 עם הפרמטרים
  • ה-Intent עם הפרמטרים
  • המניפסט של התבנית

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

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

  1. מזהים את template_id באמצעות alloydb_ai_nl.template_store_view.
  2. מסירים את התבנית.
  3. מגדירים מחדש את התבנית החדשה עם השינוי הנדרש באמצעות הפונקציה 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 מחלץ מניפסט מה-intent שסופק, והתוסף מגדיר את הפרמטרים של ה-intent ושל התנאי לפרגמנט, אם אפשר. הפרגמנטים הזמינים נחשפים על ידי תצוגות כמו 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

מניפסט בקטע נוצר באופן אוטומטי מהכוונה, והוא מייצג גרסה כללית של הכוונה. לדוגמה, המספרים 6000 ו-10000 ב-Intent מוחלפים ב-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 עם הפרמטרים
  • ה-Intent עם הפרמטרים

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

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

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

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

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

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

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

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

  1. מבקשים מ-AlloyDB ליצור תבניות על סמך היסטוריית השאילתות:

    SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);

    משתמשים בתצוגה שסופקה, alloydb_ai_nl.generated_templates_view, כדי לבדוק את generated_templates.

    בפלט הבא מוצג מספר התבניות שנוצרו:

    -[ RECORD 1 ]------+--
generate_templates | 1

  2. בודקים את התבניות שנוצרו בתצוגה 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).

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

    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?'

);

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

    -- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

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

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

הגדרת סוגי מושגים ואינדקסים של ערכים

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

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

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

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

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

    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'
  );

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

    SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );

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

    SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );

  4. כדי להפעיל את השפה הטבעית של AlloyDB AI כך שתתאים למילים נרדפות של ערך, מריצים את ההצהרה לדוגמה הבאה:

    SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );

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

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

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

    לדוגמה, אם משתמש שואל שאלה כמו "What is the population of the United States?‎" שמשתמשת בשאילתת 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')

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

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

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

  1. כדי ליצור שיוכים, צריך לשלוח קריאה לממשקי ה-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'
);

  2. כדי לבדוק את השיוכים שנוצרו, מריצים את השאילתה הבאה.

    SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

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

    -- 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
);

  4. אופציונלי: מסירים שיוך שנוצר.

    SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

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

    -- 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
);

  6. מרעננים את אינדקס הערכים כדי לשקף את השינויים.

    SELECT alloydb_ai_nl.refresh_value_index(
  nl_config_id_in => 'my_app_config'
);

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

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

  1. כדי להשתמש בשפה טבעית ולקבל תוצאות ממסד הנתונים באמצעות הפונקציה 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?"
}

  2. אופציונלי: כדי לחלץ את שאילתת ה-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 שנאכפת על ידי תצוגות מאובטחות עם פרמטרים, מסנני האבטחה הייעודיים יחולו כשקבוצת התוצאות תופק והסיכום ייווצר.

בדיקה ושיפור

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

המאמרים הבאים