資料代理程式總覽

資料代理可讓您使用對話式語言與資料庫中的資料互動。您可以為資料庫中的一組表格定義內容，建立資料代理程式，讓資料代理程式將自然語言問題轉換為準確的查詢，以符合目標用途。

脈絡是資料庫專屬資訊，可讓 LLM 生成高準確度的查詢。內容包括範本和構面 (片段)，可協助代理程式瞭解資料庫結構定義和應用程式的商業邏輯。

系統支援下列資料庫：

  • AlloyDB for PostgreSQL
  • MySQL 適用的 Cloud SQL
  • PostgreSQL 適用的 Cloud SQL
  • Spanner

資料代理程式的使用時機

您可以使用資料代理程式建構對話式資料應用程式，適用於下列用途：

  • 顧客服務自動化：處理大量查詢，例如「我的訂單在哪裡？」或「我目前的餘額是多少？」。
  • 電子商務購物助理：協助使用者透過自然語言查詢 (例如「顯示 $100 美元以下的慢跑鞋」)，瀏覽大型產品目錄。
  • 預訂和訂位系統：讓使用者透過對話介面查看空位，以及預約行程、航班或餐飲服務。
  • 現場作業工具：讓行動員工即時查詢庫存量、零件供應情形或服務單詳細資料。

資料代理程式的運作方式

如要建構有效的代理程式應用程式，代理程式必須瞭解資料機構和業務邏輯。您以代理程式情境的形式提供這項資訊。

您可以在包含範本和構面 JSON 物件的檔案中定義代理程式內容。您可以使用 Gemini CLI 撰寫這些內容檔案。接著，將內容檔案上傳至您在 Google Cloud控制台中建立的資料代理程式。這個程序可讓代理程式瞭解資料庫的特定結構定義和應用程式的商業邏輯。

代理程式環境檔案類似於下列內容：

{
  "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"
      }
    }
  ],
  "fragments": [
    {
      "fragment": "T.\"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_fragment": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

當使用者以自然語言提問時，代理程式會優先將問題與開發人員審查過的範本和構面進行比對，一旦代理程式找出相符項目，就會使用所選查詢範本和 Facet 合成資料庫查詢。然後，代理程式會對資料庫執行該查詢，傳回準確的結果。

對話式數據分析 API 中的 QueryData 端點是代理工具，可與應用程式進行程式輔助整合，讓您從自然語言問題生成 SQL 查詢。在對話式應用程式中，QueryData 端點必須在管理對話記錄和脈絡的架構中使用。

代理程式脈絡

代理程式內容包含 JSON 格式的一組精選範本和構面，可引導代理程式將自然語言問題翻譯成特定資料庫的查詢。定義情境可確保針對常見查詢模式產生高準確度的 SQL。

請確保代理程式內容準確且涵蓋預期應用程式查詢，盡量提高準確度。

查詢範本

查詢範本是一組精選的代表性自然語言問題，並附上對應的 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：資料代理程式處理的自然語言查詢範例。
  • sql：自然語言查詢的 SQL 查詢。
  • intent：自然語言查詢的目標或用途。如未設定，這個值預設為自然語言查詢。
  • manifest：意圖的自動產生一般形式。
  • parameterized_intent：意圖的範本，會自動產生，並將實體值替換為參數。
  • parameterized_sql：系統自動生成的 SQL 查詢範本，對應於參數化意圖。

查詢 facet

查詢構面是一組精選的代表性自然語言條件，並附有對應的 SQL 述詞。Facet 可管理篩選條件，讓查詢範本執行多面向搜尋。

查詢構面 (片段) 物件如下所示：

{
...
"fragments": [
    {
      "fragment": "T.\"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_fragment": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

片段 JSON 物件的主要元件如下：

  • fragment：SQL 述詞。
  • intent：SQL 述詞的說明。
  • manifest：意圖的自動產生一般形式。
  • parameterized_intent：意圖的範本，會自動產生，並將實體值替換為參數。
  • parameterized_fragment：範本化的自動產生片段，對應於參數化意圖。

限制

資料代理程式有下列限制：

  • 資料庫的代理程式環境僅支援範本和構面。
  • 資料庫的代理程式環境僅供 Conversational Analytics API 中的 QueryData 端點使用。

後續步驟