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

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

本页面介绍了如何使用 QueryData 方法为数据库数据源提供创作背景信息。对于 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 适用于 AlloyDB for PostgreSQL
spanner_reference（适用于 Spanner 的 GoogleSQL）
cloud_sql_reference 适用于 Cloud SQL 和 Cloud SQL for PostgreSQL

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

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

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

AlloyDB

{
 "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": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "cloud-db-nl2sql",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "sqlgen-magic-primary",
           "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
 }
}

适用于 Spanner 的 GoogleSQL

{
 "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
 }
}

Cloud SQL 和 Cloud SQL for PostgreSQL

{
 "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": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "cloud-db-nl2sql",
           "region": "us-central1",
           "instance_id": "sqlgen-magic-primary",
           "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：指定数据源类型。
  - 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."
}

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