Define el contexto del agente de datos para las fuentes de datos de bases de datos

Versión preliminar : Agentes de datos

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio y las Condiciones Adicionales para Productos de IA Generativa en Versión Preliminar. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para obtener más información sobre el acceso a esta versión, consulta la página de solicitud de acceso.

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 con el método QueryData.

El contexto creado es una guía que los propietarios de los agentes de datos pueden proporcionar para dar forma al comportamiento de un agente de datos y para refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder preguntas sobre tus fuentes de datos.

Para las fuentes de datos de bases de datos, como AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL, debes proporcionar contexto creado. Para ello, primero define y almacena el contexto en la base de datos y, luego, haz referencia a él en tu llamada QueryData.

Proporcionar contexto de alta precisión permite que la API genere respuestas y consultas en SQL más exactas y pertinentes.

Antes de comenzar

Necesitarás un agente de datos con su contexto de agente subido para la base de datos que deseas consultar. Para obtener más información, consulta Agentes de datos para AlloyDB, Agentes de datos para GoogleSQL para Spanner, Agentes de datos para Cloud SQL y Agentes de datos para Cloud SQL para PostgreSQL.
Habilita la API de Cloud SQL Data para tu instancia de la siguiente manera:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Reemplaza INSTANCE_ID por el ID de tu instancia de Cloud SQL 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 Cómo otorgar privilegios de base de datos a un usuario o una cuenta de servicio de IAM en Cloud SQL y Cómo otorgar privilegios de base de datos a un usuario o una cuenta de servicio de IAM en Cloud SQL para PostgreSQL.

Cómo proporcionar 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 bases de datos, debes usar una de las siguientes opciones:

alloydb para AlloyDB para PostgreSQL
spanner_reference para GoogleSQL para Spanner
cloud_sql_reference para Cloud SQL para MySQL y Cloud SQL para PostgreSQL

Dentro de estas referencias, debes especificar la base de datos y las tablas con el campo databaseReference. Para incluir 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 con alloydb. El campo agent_context_reference.context_set_id se usa para vincular al contexto creado previamente almacenado 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
 }
}

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 consultas.
    - 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. Es opcional para AlloyDB. Para las bases de datos de Spanner, se establece en GOOGLE_SQL. Para las instancias de Cloud SQL para MySQL, se establece en MYSQL. Para las instancias de Cloud SQL para PostgreSQL, se establece en POSTGRESQL.
      - 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.
    - agent_context_reference: Se vincula al contexto creado en la base de datos.
      - context_set_id: Es el ID del 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 Cómo encontrar el ID del contexto del agente en AlloyDB, Cómo encontrar el ID del contexto del agente en GoogleSQL para Spanner, Cómo encontrar el ID del contexto del agente en Cloud SQL y Cómo encontrar el ID del contexto del agente en Cloud SQL para PostgreSQL.
generationOptions: Configura el tipo de resultado que se generará.
- generate_query_result: Se establece en verdadero para generar y mostrar los resultados de la consulta.
- generate_natural_language_answer: Es opcional. Si se establece en verdadero, genera una respuesta en lenguaje natural.
- generate_explanation: Es opcional. Si se establece en verdadero, genera una explicación de la consulta en SQL.
- generate_disambiguation_question: Es opcional. Si se establece en verdadero, genera preguntas de desambiguación si la consulta es ambigua.

Ejemplo de respuesta `QueryData`

A continuación, se muestra un ejemplo de 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."
}

Define el contexto del agente de datos para las fuentes de datos de bases de datos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.