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

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

אלה מסדי הנתונים הנתמכים:

  • ‫AlloyDB ל-PostgreSQL
  • Cloud SQL ל-MySQL
  • Cloud SQL ל-PostgreSQL
  • Spanner
  • ‫Firestore עם תאימות ל-MongoDB

מהן קבוצות הקשרים

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

אתם מגדירים את ההקשר בקבצים שמכילים אובייקטים בפורמט JSON לכל סוג הקשר. אפשר ליצור את קובצי ההקשר האלה בעזרת הסוכן להנדסת הקשר. לאחר מכן מעלים את קובץ ההקשר לערכת הקשר שיוצרים במסוף Google Cloud. התהליך הזה מאפשר לכלים כמו QueryData ללמוד את הסכימה הספציפית של מסד הנתונים ואת הלוגיקה העסקית של האפליקציה.

קובץ ההקשר נראה כך:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "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'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_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\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

פורמט הקובץ של קבוצת ההקשרים

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

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

אפשר ליצור קבוצות הקשר באזורים us-central1,‏ us-east1,‏ europe-west4 ו-asia-southeast1.

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

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

אובייקט של תבנית שאילתה נראה כך:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "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'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_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\" = $1"
      }
    }
  ],
  ...
}

הרכיבים העיקריים של אובייקט ה-JSON של תבנית השאילתה הם:

  • ‫nl_query: דוגמה לשאילתה בשפה טבעית שכלים כמו QueryData מטפלים בה.
  • ‫sql: שאילתת ה-SQL של השאילתה בשפה טבעית.
  • ‫intent: המטרה של השאילתה בשפה טבעית. אם לא מגדירים את הערך הזה, ברירת המחדל היא השאילתה בשפה טבעית.
  • ‫manifest: צורה כללית של הכוונה שנוצרת אוטומטית.
  • parameterized_intent: תבנית שנוצרת אוטומטית של ה-intent, שבה ערכי הישויות מוחלפים בפרמטרים.
  • ‫parameterized_sql: טופס של שאילתת SQL שנוצר אוטומטית על סמך תבנית, שמתאים לכוונת המשתמש עם הפרמטרים.

היבטים של שאילתות

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

אובייקט של מאפיין שאילתה נראה בערך כך:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

הרכיבים העיקריים של אובייקט ה-JSON של המאפיין הם:

  • ‫sql_snippet: קטע קוד SQL. כדי למנוע אי-בהירות, צריך להוסיף לשמות העמודות את שמות הטבלאות (לדוגמה, table_name.column_name).
  • ‫intent: הסבר על פרדיקט ה-SQL.
  • ‫manifest: צורה כללית של הכוונה שנוצרה אוטומטית.
  • ‫parameterized_intent: טופס של הכוונה שנוצר אוטומטית באמצעות תבנית, עם פרמטרים במקום ערכי ישויות.
  • ‫parameterized_sql_snippet: תבנית שנוצרה אוטומטית של sql_snippet שתואמת לכוונה עם הפרמטרים.

שאילתות חיפוש של ערכים

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

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

קישור ערכים משפר את הדיוק של ההמרה משפה טבעית ל-SQL. לדוגמה, אם משתמש שואל "יש טיסות מנמל התעופה הית'רו?", יכול להיות שבמסד הנתונים יישמר שם שדה התעופה כ-"London Heathrow". בלי קישור ערכים, יכול להיות שקוד ה-SQL שנוצר יסנן לפי WHERE name = 'Heathrow' ולא יחזיר תוצאות. שאילתות חיפוש של ערכים עוזרות לסוכן למפות את "נתב"ג" לערך הנכון במסד הנתונים, "נמל התעופה בן גוריון", ולמיקום שלו בסכימה (airports.name), כדי לוודא ששאילתת ה-SQL שנוצרת מדויקת.

דוגמה לשאילתת חיפוש של ערך:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

הרכיבים העיקריים של אובייקט ה-JSON של חיפוש הערכים הם:

  • query: הצהרת SQL עם פרמטרים שמגדירה את הלוגיקה להתאמה בין ביטוי ערך לבין הערכים שמאוחסנים במסד נתונים. קבוצת התוצאות בדרך כלל מציגה את הערך התואם, את מיקום הסכימה, את סוג הקונספט ואת מדד המרחק המנורמל (בין 0 ל-1).
  • ‫concept_type: תווית סמנטית שמוקצית לערך, למשל district או loan_status. התווית הזו עוזרת לקשר בין ערכים, ובסופו של דבר עוזרת לכלים כמו QueryData API להבין את התפקיד של ביטוי הערך בסכימה. הוא גם עוזר ליצור הצהרת SQL שמכוונת למושג של הערך, וגם לטבלה ולעמודה שבהן מופיע הביטוי של הערך.
  • ‫description: תיאור של לוגיקת החיפוש.

מגבלות

יש כמה מגבלות לגבי קבוצות של הקשרים:

  • הגדרות הקשר למסדי נתונים תומכות רק בתבניות, בהיבטים ובחיפושי ערכים.
  • קבוצות הקשר למסדי נתונים משמשות רק את נקודת הקצה QueryData ב-Conversational Analytics API.

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