在 Spanner Studio 中測試 QueryData

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

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

事前準備

請確認您已在 Knowledge Catalog 建立脈絡資料集，並將脈絡資料集檔案上傳至該資料集。詳情請參閱「在 Spanner Studio 中管理情境集」。

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

測試 QueryData

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

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

    前往「Spanner」頁面

  2. 從清單中選取執行個體，然後選取資料庫。

  3. 在導覽選單中，點選「Spanner Studio」。

  4. 在「Explorer」窗格中，點選所用情境集旁邊的「查看動作」。

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

  6. 在查詢編輯器中，點選「Generate SQL using QueryData with: CONTEXT_SET_NAME」(使用 QueryData 生成 SQL，搭配：)，開啟查詢生成面板。

  7. 在查詢生成面板中，輸入自然語言問題來生成 SQL 查詢，然後點選「生成」。

  8. 檢查 SQL 查詢是否正確。按一下「Insert」(插入)，將查詢新增至編輯器。

下載及更新脈絡資料集

如果對自然語言問題生成的 SQL 查詢不滿意，請下載現有的背景資訊集檔案。接著，您可以查看及更新查詢範本，並將更新後的內容集檔案上傳至 Knowledge Catalog 中的內容集。

如要下載及更新情境組合，請按照下列步驟操作：

  1. 在「Explorer」窗格中，點選所用情境集旁邊的「查看動作」。
  2. 按一下「下載脈絡資料檔案」。
  3. 按照「使用脈絡工程代理建構脈絡資料集」一節的步驟，使用其他查詢組合更新脈絡資料。
  4. 在「Explorer」窗格中，點選所用情境集旁邊的「查看動作」。
  5. 按一下「編輯情境組合」。
  6. 在「Upload context file」(上傳內容檔案) 區段中，按一下「Browse」(瀏覽)，然後選取更新後的內容集檔案。
  7. 按一下「儲存」，更新情境集。

如果對回覆的準確度感到滿意，您可以在應用程式的要求中，將情境集 ID 傳遞至無狀態 QueryData 端點。

找出脈絡資料集 ID

從應用程式呼叫無狀態 QueryData 端點時，如要參照儲存在 Knowledge Catalog 的自編脈絡資料集，您需要脈絡資料集 ID。

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

    前往「Spanner」頁面

  2. 從清單中選取執行個體，然後選取資料庫。

  3. 在導覽選單中，點選「Spanner Studio」。

  4. 在「Explorer」窗格中，點選所用情境集旁邊的「查看動作」。

  5. 按一下「編輯情境組合」。

  6. 記下「Context set ID」(脈絡資料集 ID) 中的脈絡資料集資源名稱。QueryData 端點支援 Knowledge Catalog 中的下列兩種脈絡資料集資源名稱格式：

    • 6 區段格式：projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID，例如 projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • 8 區段格式：projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (例如 @v1)

將 QueryData 連結至應用程式

在 QueryData 方法呼叫中設定情境集 ID，即可從 Knowledge Catalog 提供資料庫資料來源 (例如 AlloyDB、Spanner、MySQL 適用的 Cloud SQL、PostgreSQL 適用的 Cloud SQL、Firestore 和 Bigtable) 的編寫情境。詳情請參閱「定義資料庫資料來源的資料代理背景資訊」。

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

包含編寫內容的 QueryData 要求範例

下列範例使用 spanner_reference 資料庫資料來源，傳送無狀態 QueryData 要求。agent_context_reference.context_set_id 欄位會將要求連結至預先編寫的情境集，該情境集儲存在 Knowledge Catalog，而非資料庫：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "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": "PROJECT_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

更改下列內容：

  • PROJECT_ID：用於要求的 Google Cloud 雲端專案 ID。
  • LOCATION：要求的區域，例如 us-central1。
  • INSTANCE_ID：Spanner 執行個體的 ID。
  • DATABASE_ID：資料庫 ID。
  • CONTEXT_SET_ID：情境集的 ID。

要求主體包含下列欄位：

  • prompt：使用者提出的自然語言問題。
  • context：包含資料來源的相關資訊。
    • datasource_references：指定資料來源類型。
      • spanner_reference：：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而變更。
        • database_reference：指定資料庫執行個體的相關資訊。
          • engine：資料庫的 SQL 方言。如果是 Spanner 資料庫，請設為 GOOGLE_SQL。
          • project_id：資料庫執行個體的專案 ID。
          • instance_id：Spanner 執行個體的 ID。
          • database_id：資料庫 ID。
        • agent_context_reference：將無狀態 QueryData 要求連結至儲存在 Knowledge Catalog (而非資料庫) 的自編情境集。
          • context_set_id：儲存在 Knowledge Catalog 的情境集完整資源名稱。您可以指定 6 區段格式 projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID 或 8 區段格式 projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (例如 @v1)。
  • generation_options：設定要生成的輸出類型。
    • generate_query_result：設為 true 即可產生並傳回查詢結果。
    • generate_natural_language_answer：選用。如果設為 true，系統會生成自然語言答案。
    • generate_explanation：選用。如果設為 true，系統會生成 SQL 查詢的說明。
    • generate_disambiguation_question：選用。如果設為 true，系統會在查詢不明確時生成釐清問題。

QueryData 回應範例

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

{
  "generatedQuery": "-- 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",
  "intentExplanation": "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.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

後續步驟