为数据库数据源定义数据代理上下文

本页面介绍如何使用 QueryData 方法为使用数据库数据源的数据智能体提供编写的上下文。

编写的上下文是数据代理所有者可以提供的指导，用于引导数据代理的行为并优化 API 的回答。有效的编写上下文可为对话式分析 API 数据代理提供有用的上下文，以便回答有关数据源的问题。

对于 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 等数据库数据源，您需要先在数据库中定义和存储上下文，然后在 QueryData 调用中引用该上下文，才能提供编写的上下文。

提供高准确度的上下文可让 API 生成更准确、更相关的 SQL 查询和回答。

准备工作

您需要一个数据智能体，并且已为要查询的数据库上传其智能体上下文。如需了解详情，请参阅 AlloyDB 的数据智能体、GoogleSQL for Spanner 的数据智能体、Cloud SQL 的数据智能体和 Cloud SQL for PostgreSQL 的数据智能体。
为您的实例启用 Cloud SQL Data API，具体方法如下：
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
将 INSTANCE_ID 替换为 Cloud SQL 或 Cloud SQL for PostgreSQL 实例的 ID。

您还必须向 IAM 用户或服务帐号授予数据库权限。如需了解详情，请参阅 Cloud SQL 中向单个 IAM 用户或服务帐号授予数据库权限和 Cloud SQL for PostgreSQL 中向单个 IAM 用户或服务帐号授予数据库权限。

使用 `QueryData` 提供上下文

调用 QueryData 方法时，您需要在 QueryDataRequest.context.datasourceReferences 字段中提供数据源和上下文信息。对于数据库源，您必须使用以下其中一项：

AlloyDB for PostgreSQL 的 alloydb
GoogleSQL for Spanner 的 spanner_reference
Cloud SQL 和 Cloud SQL for PostgreSQL 的 cloud_sql_reference

在这些引用中，您可以使用 databaseReference 字段指定数据库和表。如需添加编写的上下文，您还必须提供指向 context_set_id 的 agentContextReference。

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

以下示例展示了使用 alloydb 的 QueryData 请求。agent_context_reference.context_set_id 字段用于链接到数据库中预先编写的上下文。

AlloyDB

{
 "parent": "projects/data-agents-project/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": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "data-agents-project",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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
 }
}

GoogleSQL for Spanner

{
 "parent": "projects/data-agents-project/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": "data-agents-project"
           "instance_id": "evalbench"
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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
 }
}

Cloud SQL 和 Cloud SQL for PostgreSQL

{
 "parent": "projects/data-agents-project/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": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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：指定数据源类型。
  - alloydb：查询数据库时是必需的。此字段会根据您查询的数据库而变化。
    - database_reference：指定与数据库实例相关的信息。
      - engine：数据库引擎或 SQL 方言。对于 AlloyDB，此字段是可选的。对于 Spanner 数据库，请设置为 GOOGLE_SQL。对于 Cloud SQL 实例，请设置为 MYSQL。对于 Cloud SQL for PostgreSQL 实例，请设置为 POSTGRESQL。
      - project_id：数据库实例的项目 ID。
      - region：数据库实例的区域。
      - cluster_id：数据库实例的集群 ID。
      - instance_id：数据库的实例 ID。
      - database_id：数据库的 ID。
    - agent_context_reference：链接到数据库中编写的上下文。
      - context_set_id：存储在数据库中的智能体上下文 ID。如需详细了解如何查找上下文集 ID，请参阅在 AlloyDB 中查找智能体上下文 ID、在 GoogleSQL for Spanner 中查找智能体上下文 ID、在 Cloud SQL 中查找智能体上下文 ID 和在 Cloud SQL for PostgreSQL 中查找智能体上下文 ID。
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."
}

为数据库数据源定义数据代理上下文 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。