在 Spanner Studio 中测试 QueryData

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

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

准备工作

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

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

测试 QueryData

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

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

    前往 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

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

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

  5. 点击测试上下文集。

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

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

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

下载并更新上下文集

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

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

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

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

查找上下文集 ID

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

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

    前往 Spanner

  2. 从列表中选择一个实例，然后选择一个数据库。

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

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

  5. 点击修改上下文集。

  6. 请记下上下文集 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 请求示例

以下示例使用 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
  }
}

后续步骤