En esta página, se describe cómo proporcionar contexto creado para los agentes de datos que usan fuentes de datos de bases de datos.
El contexto creado es una guía que los propietarios de agentes de datos pueden proporcionar para dar forma al comportamiento de un agente de datos y definir mejor las respuestas de la API. El contexto creado de forma eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder preguntas sobre tus fuentes de datos.
En el caso de las fuentes de datos de bases de datos, como AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL, debes proporcionar el contexto creado definiéndolo y almacenándolo primero en la base de datos y, luego, haciendo referencia a él en la referencia de la fuente de datos. En los ejemplos de esta página, se usa el método QueryData.
Proporcionar un contexto de alta precisión permite que la API genere consultas en SQL y respuestas más precisas y pertinentes.
Antes de comenzar
- Necesitarás un agente de datos con su contexto de agente subido para la base de datos que quieras consultar. Para obtener más información, consulta la documentación del agente de datos de AlloyDB, Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL. Para Spanner Graph, consulta Administra conjuntos de contexto en Spanner Studio.
- Para crear, subir y administrar conjuntos de contexto para fuentes de datos de bases de datos, habilita la API de Knowledge Catalog y otorga el rol de editor de Dataplex Catalog (
roles/dataplex.catalogEditor) o administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) al usuario de IAM o a la cuenta de servicio a nivel del proyecto. Para obtener más información, consulta El contexto establece permisos. Habilita la API de datos de Cloud SQL para tu instancia de la siguiente manera:
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_APIReemplaza
INSTANCE_IDpor el ID de tu instancia de Cloud SQL para MySQL o Cloud SQL para PostgreSQL.También debes otorgar privilegios de base de datos a un usuario o una cuenta de servicio de IAM. Para obtener más información, consulta Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales en Cloud SQL para MySQL y Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales en Cloud SQL para PostgreSQL.
Proporciona contexto con QueryData
Cuando llamas al método QueryData, proporcionas la fuente de datos y la información de contexto en el campo QueryDataRequest.context.datasourceReferences. Para las fuentes de datos de la base de datos, debes usar una de las siguientes opciones:
alloydbpara AlloyDB para PostgreSQLspanner_referencepara GoogleSQL para Spannercloud_sql_referencepara Cloud SQL para MySQL y Cloud SQL para PostgreSQL
En estas referencias, debes especificar la base de datos y las tablas con el campo databaseReference. Para incluir el contexto creado, también debes proporcionar un agentContextReference que apunte a un context_set_id.
Ejemplo de solicitud QueryData con contexto creado
En el siguiente ejemplo, se muestra una solicitud QueryData que usa alloydb. El campo agent_context_reference.context_set_id se usa para vincular al contexto creado previamente que se almacena en la base de datos.
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 para 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 } }
Spanner Graph
{ "parent": "projects/data-agents-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "data-agents-project", "instance_id": "data-agents-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL para 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 para 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 } }
El cuerpo de la solicitud contiene los siguientes campos:
prompt: Es la pregunta en lenguaje natural del usuario final.context: Contiene información sobre las fuentes de datos.datasource_references: Especifica el tipo de fuente de datos.alloydb: Es obligatorio cuando se consulta la base de datos. Este campo cambia según la base de datos que consultes.database_reference: Especifica información relacionada con tu instancia de base de datos.engine: Es el motor de base de datos o el dialecto de SQL. Opcional para AlloyDB. Para las bases de datos de Spanner, establece el valor enGOOGLE_SQL. En las instancias de Cloud SQL para MySQL, configúralo comoMYSQL. En las instancias de Cloud SQL para PostgreSQL, establece el valor enPOSTGRESQL.project_id: Es el ID del proyecto de la instancia de base de datos.region: Es la región de la instancia de base de datos.cluster_id: Es el ID del clúster de la instancia de base de datos.instance_id: Es el ID de la instancia de la base de datos.database_id: Es el ID de la base de datos.graph_ids: Es obligatorio para Spanner Graph. Es una lista de nombres de grafos de propiedades en la base de datos de Spanner que se consultará (por ejemplo,["FinGraph"]). Si omitesgraph_ids, QueryData genera consultas de GoogleSQL en las tablas subyacentes en lugar de consultas de GQL.
agent_context_reference: Vínculos al contexto creado en la base de datos.context_set_id: Es el ID de contexto del agente almacenado en la base de datos. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de AlloyDB, Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL. Para Spanner Graph, consulta Busca el ID del conjunto de contexto.
generationOptions: Configura el tipo de resultado que se generará.generate_query_result: Se establece como verdadero para generar y mostrar los resultados de la consulta.generate_natural_language_answer: Opcional Si se establece como verdadero, genera una respuesta en lenguaje natural.generate_explanation: Opcional Si se establece como verdadero, genera una explicación de la consulta en SQL.generate_disambiguation_question: Opcional Si se establece como verdadero, genera preguntas de desambiguación si la consulta es ambigua.
Ejemplo de respuesta de QueryData
Este es un ejemplo de una respuesta correcta de una llamada 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."
}