內容集總覽

脈絡資料集內含特定資料庫的資訊，助 QueryData 等工具生成高精確度的查詢。情境集可包含範本、Facet 和值搜尋，協助 QueryData 瞭解資料庫結構定義和應用程式的商業邏輯。

支援的資料庫如下：

  • AlloyDB for PostgreSQL
  • MySQL 適用的 Cloud SQL
  • PostgreSQL 適用的 Cloud SQL
  • Spanner
  • 與 MongoDB 相容的 Firestore
  • Bigtable

什麼是情境組合

如要建構有效的代理應用程式，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"
      }
    }
  ]
}

脈絡資料集檔案格式

脈絡資料集檔案包含一組精選範本、facet 和值搜尋，格式為 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 查詢的範本化自動生成形式，對應至參數化意圖。

查詢 facet

查詢 facet 是一組精選的代表性自然語言條件，具有對應的 SQL 述詞。Facet 會管理篩選條件和條件，讓查詢範本執行 Facet 搜尋。

查詢 facet 物件大致如下：

{
...
"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"
      }
    }
  ]
}

Facet JSON 物件的主要元件如下：

  • sql_snippet：SQL 程式碼片段。為避免混淆，請在資料欄名稱中加入資料表名稱 (例如 table_name.column_name)。
  • intent：SQL 述詞的說明。
  • manifest：自動生成的通用意圖形式。
  • parameterized_intent：自動生成的意圖範本，實體值會替換為參數。
  • parameterized_sql_snippet：範本化的自動生成 sql_snippet 形式，對應至參數化意圖。

搜尋查詢

值搜尋查詢 是開發人員定義的查詢，使用比對函式在資料庫中尋找值和其內容。值連結功能會使用這些查詢結果，找出哪些資料表和資料欄包含相符的值、瞭解值的概念類型，以及修正拼寫錯誤。

QueryData API 會使用值連結，更準確地將自然語言轉換為 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：搜尋邏輯的說明。

限制

情境組合有下列限制：

  • 不支援 SQL Server 適用的 Cloud SQL。
  • 資料庫的內容集僅支援範本、Facet 和值搜尋。
  • 資料庫的情境集僅供 Conversational Analytics API 中的 QueryData 端點使用。

後續步驟