此页面由 Cloud Translation API 翻译。

检查和调用数据代理

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

如需了解数据代理，请参阅数据代理概览。

准备工作

确保已创建数据代理，并且已将代理上下文上传到数据代理。如需了解详情，请参阅在 Spanner Studio 中管理数据代理。

检查数据智能体

如需检查数据代理，请执行以下步骤：

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

前往 Spanner
从列表中选择一个实例，然后选择一个数据库。
在导航菜单中，点击 Spanner Studio。
在探索器窗格中，点击数据代理旁边的查看操作。
点击检查代理。
在查询编辑器中，点击生成 SQL 以打开帮我写代码面板。
输入自然语言问题以生成 SQL 查询，然后点击生成。
检查 SQL 查询是否准确无误。

下载并更新数据智能体的上下文

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

如需下载和更新数据代理的上下文，请执行以下步骤：

在探索器窗格中，点击数据代理旁边的查看操作。
点击下载代理上下文文件。
按照使用 Gemini CLI 构建上下文中的步骤，使用其他查询对更新上下文。
在“探索器”窗格中，点击数据代理旁边的查看操作。
点击修改代理。
在上传代理上下文文件部分中，点击浏览，然后选择更新后的代理上下文文件。
点击保存以更新代理上下文。

对回答的准确性感到满意后，您可以使用 QueryData 端点将应用连接到数据代理。

查找代理上下文 ID

如需将数据应用连接到数据代理，您需要代理的情境 ID。

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

前往 Spanner
从列表中选择一个实例，然后选择一个数据库。
在导航菜单中，点击 Spanner Studio。
在探索器窗格中，点击数据代理旁边的查看操作。
点击修改代理。
记下代理上下文 ID 中的上下文 ID。代理上下文 ID 的格式类似于 projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates。

将数据代理连接到应用

在 QueryData 方法调用中设置代理上下文 ID，以便为 AlloyDB、Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 等数据库数据源提供已创作的上下文。如需了解详情，请参阅为数据库数据源定义数据代理上下文

检查数据代理后，您可以在 QueryData 调用中引用数据库数据源。

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

以下示例展示了使用 spanner_reference 数据库数据源的 QueryData 请求。agent_context_reference.context_set_id 字段用于链接到存储在数据库中的预先撰写的内容。

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

请求正文包含以下字段：

prompt：最终用户的自然语言问题。
context：包含有关数据源的信息。
- datasource_references：指定数据源类型。
  - spanner_reference：查询数据库时需要。此字段会根据您查询的数据库而变化。
    - database_reference：指定与数据库实例相关的信息。
      - engine：数据库的 SQL 方言。对于 Spanner 数据库，应设置为 GOOGLE_SQL。
      - project_id：数据库实例的项目 ID。
      - region：Spanner 实例的区域。
      - instance_id：Spanner 实例的实例 ID。
      - database_id：数据库的 ID。
    - agent_context_reference：指向数据库中已创作内容的链接。
      - context_set_id：存储在数据库中的上下文的完整代理上下文 ID。例如 projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates。
generationOptions：配置要生成的输出类型。
- generate_query_result：设置为 true 可生成并返回查询结果。
- generate_natural_language_answer：可选。如果设置为 true，则生成自然语言回答。
- generate_explanation：可选。如果设置为 true，则生成 SQL 查询的说明。
- generate_disambiguation_question：可选。如果设置为 true，则在查询存在歧义时生成消歧问题。

示例 `QueryData` 回答

以下是 QueryData 调用的成功响应示例：

{
  "generated_query": "-- 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",
  "intent_explanation": "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.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}