Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在 Bigtable Studio 中测试 QueryData

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

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

准备工作

确保您已在 Knowledge Catalog 中创建上下文集，并将上下文集文件上传到该上下文集。如需了解详情，请参阅在 Bigtable Studio 中管理上下文集。

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

测试 QueryData

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

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

打开 Bigtable
从列表中选择一个实例。
在导航菜单中，点击 Bigtable Studio。
在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。
点击测试上下文集。
在查询编辑器中，点击使用 QueryData 生成 SQL，模型：CONTEXT_SET_NAME，打开查询生成面板。
在查询生成面板中输入自然语言问题以生成 SQL 查询，然后点击生成。
检查 SQL 查询的准确性。点击插入，将查询添加到编辑器中。

下载并更新上下文集

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

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

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

在您对回答的准确性感到满意后，您可以在应用的请求中将上下文集 ID 传递给无状态 QueryData 端点。

查找上下文集 ID

如需在从应用调用无状态 QueryData 端点时引用存储在 Knowledge Catalog 中的已编写上下文集，您需要上下文集 ID。

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

打开 Bigtable
从列表中选择一个实例。
在导航菜单中，点击 Bigtable Studio。
在“探索器”窗格中，点击您正在使用的上下文集旁边的查看操作。
点击修改上下文集。
请记下上下文集 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、Cloud SQL for MySQL、Cloud SQL for PostgreSQL、Firestore 和 Bigtable 等数据库数据源提供编写的上下文。如需了解详情，请参阅为数据库数据源定义数据智能体上下文。

测试上下文集后，您可以在无状态 QueryData 调用中引用数据库数据源和上下文集。

包含编写的上下文的 `QueryData` 请求示例

以下示例使用 bigtable_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 hotels are located in London?",
  "context": {
    "datasource_references": {
      "bigtable_reference": {
        "database_reference": {
          "project_id": "PROJECT_ID",
          "instance_id": "INSTANCE_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：Bigtable 实例的实例 ID。
CONTEXT_SET_ID：上下文集的 ID。

请求正文包含以下字段：

prompt：来自最终用户的自然语言问题。
context：包含数据源的相关信息。
- datasource_references：指定数据源类型。
  - bigtable_reference：查询数据库时必需。此字段会根据您查询的数据库而变化。
    - database_reference：指定与 Bigtable 实例相关的信息。
      - project_id：Bigtable 实例所属的项目 ID。
      - instance_id：Bigtable 实例的实例 ID。
      - table_ids：可选。要将代理限定在哪些表 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": "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.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}