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

Vista previa — Data agents

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Serviciosy a los Términos Adicionales para Productos de IA Generativa en Versión Preliminar. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Para saber cómo conseguir acceso a esta versión, visita la página de solicitud de acceso.

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 para refinar las respuestas de la API. El contexto creado eficaz proporciona a los agentes de datos de la API Conversational Analytics información útil para responder a preguntas sobre tus fuentes de datos.

En esta página se describe cómo proporcionar contexto creado para fuentes de datos de bases de datos mediante el método QueryData. En el caso de las fuentes de datos de bases de datos, como AlloyDB, GoogleSQL para Spanner, Cloud SQL y Cloud SQL para PostgreSQL, debes proporcionar el contexto creado definiéndolo y almacenándolo primero en la base de datos y, a continuación, haciendo referencia a él en tu llamada QueryData.

Si proporcionas un contexto de alta precisión, la API podrá generar consultas y respuestas SQL más precisas y relevantes.

Antes de empezar

Necesitarás un agente de datos con su contexto de agente subido a la base de datos que quieras 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 Data de Cloud SQL en tu instancia de la siguiente manera:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Sustituye INSTANCE_ID por el ID de tu instancia de Cloud SQL o Cloud SQL para PostgreSQL.

También debes conceder privilegios de base de datos a un usuario o una cuenta de servicio de IAM. Para obtener más información, consulta Conceder privilegios de base de datos a un usuario o una cuenta de servicio de gestión de identidades y accesos en Cloud SQL y Conceder privilegios de base de datos a un usuario o una cuenta de servicio de gestión de identidades y accesos en Cloud SQL para PostgreSQL.

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. En el caso de las fuentes de bases de datos, debe usar una de las siguientes opciones:

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

En estas referencias, se especifican la base de datos y las tablas mediante 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 utiliza alloydb. El campo agent_context_reference.context_set_id se usa para vincular a un contexto predefinido almacenado en la base de datos.

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

GoogleSQL para Spanner

{
 "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 y Cloud SQL para 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
 }
}

El cuerpo de la solicitud contiene los siguientes campos:

prompt: 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 al consultar la base de datos. Este campo cambia en función de la base de datos que estés consultando.
    - database_reference: especifica información relacionada con tu instancia de base de datos.
      - engine: el motor de la base de datos o el dialecto de SQL. Opcional para AlloyDB. En el caso de las bases de datos de Spanner, el valor debe ser GOOGLE_SQL. En el caso de las instancias de Cloud SQL, el valor debe ser MYSQL. En las instancias de Cloud SQL para PostgreSQL, selecciona POSTGRESQL.
      - project_id: el ID de proyecto de la instancia de la base de datos.
      - region: la región de la instancia de base de datos.
      - cluster_id: ID de clúster de la instancia de base de datos.
      - instance_id: ID de instancia de la base de datos.
      - database_id: ID de la base de datos.
    - agent_context_reference: enlaces al contexto creado en la base de datos.
      - context_set_id: 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 Buscar el ID del contexto del agente en AlloyDB, Buscar el ID del contexto del agente en GoogleSQL para Spanner, Buscar el ID del contexto del agente en Cloud SQL y Buscar el ID del contexto del agente en Cloud SQL para PostgreSQL.
generationOptions: configura el tipo de salida que se va a generar.
- generate_query_result: se define como true para generar y devolver los resultados de la consulta.
- generate_natural_language_answer: opcional. Si se le asigna el valor "true", genera una respuesta en lenguaje natural.
- generate_explanation: opcional. Si se le asigna el valor true, genera una explicación de la consulta de SQL.
- generate_disambiguation_question: opcional. Si se le asigna el valor "true", 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 a 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."
}

Definir el contexto del agente de datos para las fuentes de datos de bases de datos Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.