在 Spanner Studio 中測試 QueryData

本文說明如何測試 QueryData，以及更新內容集檔案。您可以測試 QueryData 從自然語言問題生成 SQL 查詢的能力。如果生成的查詢不準確，可以更新內容集檔案。

如要瞭解內容集，請參閱「內容集總覽」。

事前準備

請確認已建立脈絡集，並將脈絡集檔案上傳至 QueryData 代理程式。詳情請參閱「在 Spanner Studio 中管理內容集」

測試 QueryData

如要測試 QueryData，請按照下列步驟操作：

前往 Google Cloud 控制台的「Spanner」頁面。

前往 Spanner
從清單中選取執行個體，然後選取資料庫。
在導覽選單中，按一下「Spanner Studio」。
在「Explorer」窗格中，點選所用內容集旁邊的「查看動作」。
按一下「測試內容集」。
在查詢編輯器中，按一下「Generate SQL」(產生 SQL)，開啟「幫我寫程式碼」面板。
在編輯器中輸入自然語言問題，生成 SQL 查詢，然後點選「生成」。
檢查 SQL 查詢是否正確。

下載及更新內容集

如果您對自然語言問題生成的 SQL 查詢不滿意，請下載現有的內容集檔案。接著，您可以檢查並更新查詢範本，然後將更新後的結構定義檔案重新上傳至代理程式。

如要下載及更新內容集，請按照下列步驟操作：

在「Explorer」窗格中，按一下「查看動作」。
按一下「下載結構定義檔案」。
按照「使用 Gemini CLI 建構脈絡資料」一文中的步驟，使用其他查詢組合更新脈絡資料。
在「Explorer」窗格中，點選所用內容集旁邊的「查看動作」。
按一下「編輯情境集」。
按一下「Upload context set file」(上傳內容集檔案) 專區中的「Browse」(瀏覽)，然後選取更新後的內容集檔案。
按一下「儲存」即可更新內容集。

確認回覆內容準確無誤後，即可使用 QueryData 端點將應用程式連結至內容集。

找出內容集 ID

如要將資料應用程式連結至 QueryData 代理程式，您需要內容集 ID。

前往 Google Cloud 控制台的「Spanner」頁面。

前往 Spanner
從清單中選取執行個體，然後選取資料庫。
在導覽選單中，按一下「Spanner Studio」。
在「Explorer」窗格中，點選所用內容集旁邊的「查看動作」。
按一下「編輯情境集」。
記下「Context set ID」(脈絡集 ID) 中的脈絡 ID。內容集 ID 格式類似於 projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates。

將 QueryData 連結至應用程式

在 QueryData 方法呼叫中設定內容集 ID，為資料庫資料來源 (例如 AlloyDB、Spanner、Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 提供撰寫的內容。詳情請參閱「為資料庫資料來源定義資料代理程式環境」。

測試完內容集後，您可以在 QueryData 呼叫中參照資料庫資料來源。

附有撰寫背景資訊的 `QueryData` 要求範例

以下範例顯示使用 spanner_reference 資料庫資料來源的 QueryData 要求。agent_context_reference.context_set_id 欄位用於連結至資料庫中預先撰寫的內容。

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "context-set-project"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

要求主體包含下列欄位：

prompt：終端使用者的自然語言問題。
context：包含資料來源的相關資訊。
- datasource_references：指定資料來源類型。
  - spanner_reference：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而有所不同。
    - database_reference：指定與資料庫執行個體相關的資訊。
      - engine：資料庫的 SQL 方言。Spanner 資料庫請設為 GOOGLE_SQL。
      - project_id：資料庫執行個體的專案 ID。
      - region：Spanner 執行個體的區域。
      - instance_id：Spanner 執行個體的執行個體 ID。
      - database_id：資料庫 ID。
    - agent_context_reference：資料庫中撰寫的內容連結。
      - context_set_id：儲存在資料庫中的完整情境集 ID。例如：projects/context-set-project/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates。
generationOptions：設定要產生的輸出類型。
- generate_query_result：設為 true 可產生並傳回查詢結果。
- generate_natural_language_answer：選用。如設為 true，則會生成自然語言答案。
- generate_explanation：選用。如果設為 true，系統會生成 SQL 查詢的說明。
- generate_disambiguation_question：選用。如果設為 true，系統會在查詢內容模稜兩可時生成消歧問題。

`QueryData` 回應範例

以下是 QueryData 呼叫成功的回應範例：

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}