使用 Cloud SQL Studio 測試 QueryData

本文說明如何測試 QueryData，以及更新脈絡集檔案。您可以測試 QueryData 能否根據自然語言問題生成 SQL 查詢。如果生成的查詢不準確，可以更新情境集檔案。

如要瞭解情境組合，請參閱「情境組合總覽」。

事前準備

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

如要下載、更新及上傳情境集檔案，請確認 IAM 使用者具備專案的 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色。詳情請參閱「情境集權限」。

測試 QueryData

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

  1. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 按一下導覽選單中的「Cloud SQL Studio」。

  4. 使用 Identity and Access Management 驗證機制登入 Studio。

  5. 在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。

  6. 按一下「測試脈絡資料集」。

  7. 在查詢編輯器中，點選「生成 SQL」，開啟「幫我寫程式碼」面板。

  8. 在編輯器中輸入自然語言問題，生成 SQL 查詢，然後點選「生成」。

  9. 檢查 SQL 查詢是否正確。

下載及更新脈絡資料集

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

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

  1. 在「Explorer」窗格中，點選「查看動作」。
  2. 按一下「下載脈絡資料檔案」。
  3. 按照「使用脈絡工程代理建構脈絡資料集」一節的步驟，使用其他查詢配對更新脈絡資料。
  4. 在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。
  5. 按一下「編輯內容集」。
  6. 按一下「上傳情境集檔案」部分的「瀏覽」，然後選取更新後的情境集檔案。
  7. 按一下「儲存」即可更新內容集。

如果回覆準確度符合需求，您可以使用 QueryData 端點，將應用程式連結至情境集。

找出脈絡資料集 ID

如要將資料應用程式連結至 QueryData 代理，您需要取得脈絡資料集的 ID。

  1. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 在導覽選單中，按一下「Cloud SQL Studio」。

  4. 使用 Identity and Access Management 驗證登入工作室。

  5. 在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。

  6. 按一下「編輯內容集」。

  7. 記下「脈絡資料集 ID」中的脈絡 ID。脈絡資料集 ID 格式類似於 projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates。

將 QueryData 連結至應用程式

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

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

包含撰寫情境的 QueryData 要求範例

以下範例顯示使用 cloud_sql_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": [
      {
        "cloud_sql_reference": {
          "database_reference": {
            "engine": "POSTGRESQL"
            "project_id": "context-set-project",
            "region": "us-central1",
            "instance_id": "context-set-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/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：指定資料來源類型。
      • cloud_sql_reference：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而變更。
        • database_reference：指定與資料庫執行個體相關的資訊。
          • engine：資料庫引擎。如果是 Cloud SQL 執行個體，請設為 POSTGRESQL。
          • project_id：資料庫執行個體的專案 ID。
          • region：Cloud SQL 執行個體的區域。
          • instance_id：Cloud SQL 執行個體的執行個體 ID。
          • database_id：資料庫 ID。
        • agent_context_reference：連結至資料庫中撰寫的內容。
          • context_set_id：儲存在資料庫中的完整情境集 ID。例如：projects/context-set-project/locations/us-central1/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."
}

後續步驟