Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

在 Bigtable Studio 測試 QueryData

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

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

事前準備

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

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

測試 QueryData

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

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

前往 Bigtable
從清單中選取執行個體。
在導覽選單中，點選「Bigtable Studio」。
在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。
按一下「測試脈絡資料集」。
在查詢編輯器中，點選「Generate SQL using QueryData with: CONTEXT_SET_NAME」(使用 QueryData 生成 SQL，搭配：)，開啟「幫我寫程式碼」面板。
在編輯器中輸入自然語言問題，生成 SQL 查詢，然後點選「生成」。
檢查 SQL 查詢是否正確。按一下「Insert」(插入)，將查詢新增至編輯器。

下載及更新脈絡資料集

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

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

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

如果對回覆的準確度感到滿意，可以使用 QueryData 端點，將應用程式連結至情境集。

找出脈絡資料集 ID

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

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

前往 Bigtable
從清單中選取執行個體。
在導覽選單中，點選「Bigtable Studio」。
在「Explorer」窗格中，找到您使用的情境集，然後點選旁邊的「查看動作」。
按一下「編輯情境組合」。
記下「脈絡資料集 ID」中的脈絡 ID。脈絡資料集 ID 格式類似於 projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@v1。

將 QueryData 連結至應用程式

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

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

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

以下範例顯示使用 bigtable_reference 資料庫資料來源的 QueryData 要求。agent_context_reference.context_set_id 欄位用於連結至包含您編寫情境的情境集。

POST https://geminidataanalytics.googleapis.com/v1beta/projects/context-set-project/locations/us-central1:queryData

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "List the names and ratings of all hotels located in London.",
  "context": {
    "datasource_references": {
      "bigtable_reference": {
        "database_reference": {
          "project_id": "context-set-project",
          "instance_id": "evalbench"
        },
        "agent_context_reference": {
          "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/hotels_bigtable_all_templates"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

要求主體包含下列欄位：

prompt：使用者提出的自然語言問題。
context：包含資料來源的相關資訊。
- datasource_references：指定資料來源類型。
  - bigtable_reference：：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而變更。
    - database_reference：指定 Bigtable 執行個體的相關資訊。
      - project_id：Bigtable 執行個體所屬的專案 ID。
      - instance_id：Bigtable 執行個體的執行個體 ID。
      - table_ids：選用。代理的範圍資料表 ID。如未設定，則會納入執行個體中的所有資料表。
    - agent_context_reference：連結至編寫的內容。
      - context_set_id：脈絡資料集的完整 ID，其中包含您編寫的脈絡。例如：projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@v1。
generation_options：設定要生成的輸出類型。
- generate_query_result：設為 true 即可產生並傳回查詢結果。
- generate_natural_language_answer：選用。如果設為 true，系統會生成自然語言答案。
- generate_explanation：選用。如果設為 true，系統會生成 SQL 查詢的說明。
- generate_disambiguation_question：選用。如果設為 true，系統會在查詢不明確時生成釐清問題。

`QueryData` 回應範例

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

{
  "generatedQuery": "SELECT COUNT(*) FROM `hotels` WHERE CAST(cf['location'] AS STRING) = 'London'",
  "intentExplanation": "count of hotels in London",
  "queryResult": {
    "columns": [
      {
        "name": "$col1",
        "type": "int64_type:{}"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "Based on the data, there are 2 hotels located in London."
}