本页介绍了如何为使用数据库数据源的数据代理提供创作的上下文。
编写的上下文是数据代理所有者可以提供的指导，用于引导数据代理的行为并优化 API 的回答。有效的编写上下文可为 Conversational Analytics API 数据代理提供有用的上下文，以便回答有关数据源的问题。
对于 AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 等数据库数据源，您可以通过以下方式提供已撰写的上下文：首先在数据库中定义并存储上下文，然后在数据源引用中引用该上下文。本页面的示例使用 QueryData 方法。
提供高准确度的上下文可让 API 生成更准确、更相关的 SQL 查询和答案。
准备工作
- 您需要一个数据代理，并已上传要查询的数据库的代理上下文。如需了解详情，请参阅 AlloyDB、Spanner、Cloud SQL for MySQL 和 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 for MySQL 或 Cloud SQL for PostgreSQL 实例的 ID。您还必须向 IAM 用户或服务账号授予数据库权限。如需了解详情，请参阅 Cloud SQL for MySQL 中向单个 IAM 用户或服务账号授予数据库权限和 Cloud SQL for PostgreSQL 中向单个 IAM 用户或服务账号授予数据库权限。
使用 QueryData 提供背景信息
调用 QueryData 方法时，您需要在 QueryDataRequest.context.datasourceReferences 字段中提供数据源和上下文信息。对于数据库数据源，您必须使用以下选项之一：
alloydb适用于 AlloyDB for PostgreSQLspanner_reference（适用于 Spanner 的 GoogleSQL）cloud_sql_reference（适用于 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL）
在这些引用中，您可以使用 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 } }
适用于 Spanner 的 GoogleSQL
{ "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 for MySQL
{ "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 } }
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": "POSTGRES" "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 for MySQL 实例，请设置为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、Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 的文档。
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."
}