在 Bigtable Studio 中测试 QueryData

本文档介绍了如何测试 QueryData 并更新上下文集文件。您可以测试 QueryData 根据自然语言问题生成 SQL 查询的能力。如果生成的查询不准确，您可以更新上下文集文件。

如需了解上下文集，请参阅上下文集概览。

准备工作

确保已创建上下文集，并且上下文集文件已上传到 QueryData 智能体。如需了解详情，请参阅在 Bigtable Studio 中管理上下文集。

如需下载、更新和上传上下文集文件，请确保 IAM 用户对项目拥有 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情，请参阅上下文集权限。

测试 QueryData

如需测试 QueryData，请执行以下步骤：

  1. 在 Google Cloud 控制台中，前往 Bigtable 页面。

    打开 Bigtable

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击 Bigtable Studio。

  4. 在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。

  5. 点击测试上下文集。

  6. 在查询编辑器中，点击使用 QueryData 生成 SQL，模型：CONTEXT_SET_NAME，以打开帮我编码面板。

  7. 在编辑器中输入自然语言问题以生成 SQL 查询，然后点击生成。

  8. 检查 SQL 查询的准确性。点击插入，将查询添加到编辑器中。

下载并更新上下文集

如果您对针对自然语言问题生成的 SQL 查询不满意，请下载现有的上下文集文件。然后，您可以查看和更新查询模板，并将更新后的上下文文件重新上传到代理。

如需下载和更新上下文集，请执行以下步骤：

  1. 在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。
  2. 点击下载上下文文件。
  3. 按照使用上下文工程智能体构建上下文集中的步骤，使用其他查询对更新上下文。
  4. 在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。
  5. 点击修改上下文集。
  6. 点击上传上下文文件部分中的浏览，然后选择更新后的上下文集文件。
  7. 点击保存以更新上下文集。

如果您对回答的准确性感到满意，可以使用 QueryData 端点将应用连接到上下文集。

查找上下文集 ID

如需将数据应用连接到 QueryData 智能体，您需要上下文集的 ID。

  1. 在 Google Cloud 控制台中，前往 Bigtable 页面。

    打开 Bigtable

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击 Bigtable Studio。

  4. 在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。

  5. 点击修改上下文集。

  6. 记下上下文集 ID 中的上下文 ID。上下文集 ID 格式类似于 projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@v1。

将 QueryData 连接到应用

在 QueryData 方法调用中设置上下文集 ID，以便为 AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL、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."
}

后续步骤