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

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

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

  • ‫AlloyDB ל-PostgreSQL
  • Cloud SQL ל-MySQL
  • Cloud SQL ל-PostgreSQL
  • Spanner

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

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

אתם מגדירים את ההקשר בקבצים שמכילים אובייקטים בפורמט JSON לכל סוג הקשר. אתם יוצרים את קובצי ההקשר האלה בעזרת Gemini CLI. לאחר מכן מעלים את קובץ ההקשר לערכת הקשר שיוצרים במסוף 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: טופס של הכוונה שנוצר אוטומטית באמצעות תבנית, עם ערכי ישויות שהוחלפו בפרמטרים.
  • ‫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 שנוצר באופן אוטומטי על סמך תבנית, שתואם לכוונת המשתמש עם הפרמטרים.

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

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

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

קישור ערכים משפר את הדיוק של המרת שפה טבעית ל-SQL. לדוגמה, אם משתמש שואל "יש טיסות מנמל התעופה הית'רו?", יכול להיות ששם שדה התעופה יישמר במסד הנתונים כ"נמל התעופה הית'רו בלונדון". בלי קישור ערכים, יכול להיות ש-SQL שנוצר יסנן לפי WHERE name = 'Heathrow' ולא יחזיר תוצאות. שאילתות לחיפוש ערכים עוזרות לסוכן למפות את הערך 'Heathrow' לערך הנכון במסד הנתונים 'London 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.

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