Définir le contexte de l'agent de données pour les sources de données de base de données

Cette page explique comment fournir un contexte créé pour les agents de données qui utilisent des sources de données de base de données à l'aide de la QueryData méthode.

Le contexte créé est un ensemble de consignes que les propriétaires d'agents de données peuvent fournir pour façonner le comportement d'un agent de données et affiner les réponses de l'API. Un contexte créé efficace fournit à vos agents de données de l'API Conversational Analytics un contexte utile pour répondre aux questions sur vos sources de données.

Pour les sources de données de base de données telles qu'AlloyDB, GoogleSQL pour Spanner, Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL, vous fournissez un contexte créé en définissant et en stockant d'abord le contexte dans la base de données, puis en le référençant dans votre appel QueryData.

Fournir un contexte très précis permet à l'API de générer des requêtes et des réponses SQL plus précises et pertinentes.

Avant de commencer

Vous aurez besoin d'un agent de données dont le contexte d'agent est importé pour la base de données que vous souhaitez interroger. Pour en savoir plus, consultez Agents de données pour AlloyDB, Agents de données pour GoogleSQL pour Spanner, Agents de données pour Cloud SQL et Agents de données pour Cloud SQL pour PostgreSQL.
Activez l'API Cloud SQL Data pour votre instance comme suit :
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Remplacez INSTANCE_ID par l'ID de votre instance Cloud SQL ou Cloud SQL pour PostgreSQL.

Vous devez également accorder des droits sur la base de données à un utilisateur ou à un compte de service IAM. Pour en savoir plus, consultez Accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM individuel dans Cloud SQL et Accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM individuel dans Cloud SQL pour PostgreSQL.

Fournir un contexte avec `QueryData`

Lorsque vous appelez la méthode QueryData, vous fournissez la source de données et les informations de contexte dans le champ QueryDataRequest.context.datasourceReferences. Pour les sources de base de données, vous devez utiliser l'une des options suivantes :

alloydb pour AlloyDB pour PostgreSQL
spanner_reference pour GoogleSQL pour Spanner
cloud_sql_reference pour Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL

Dans ces références, vous spécifiez la base de données et les tables à l'aide du champ databaseReference. Pour inclure un contexte créé, vous devez également fournir une agentContextReference qui pointe vers un context_set_id.

Exemple de requête `QueryData` avec un contexte créé

L'exemple suivant montre une requête QueryData utilisant alloydb. Le champ agent_context_reference.context_set_id est utilisé pour établir un lien vers un contexte pré-créé stocké dans la base de données.

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

Le corps de la requête contient les champs suivants :

prompt : question en langage naturel de l'utilisateur final.
context : contient des informations sur les sources de données.
- datasource_references : spécifie le type de source de données.
  - alloydb : obligatoire lors de l'interrogation de la base de données. Ce champ change en fonction de la base de données que vous interrogez.
    - database_reference : spécifie les informations liées à votre instance de base de données.
      - engine : moteur de base de données ou dialecte SQL. Facultatif pour AlloyDB. Pour les bases de données Spanner, définissez la valeur sur GOOGLE_SQL. Pour les instances Cloud SQL pour MySQL, définissez la valeur sur MYSQL. Pour les instances Cloud SQL pour PostgreSQL, définissez la valeur sur POSTGRESQL.
      - project_id : ID de projet de l'instance de base de données.
      - region : région de l'instance de base de données.
      - cluster_id : ID de cluster de l'instance de base de données.
      - instance_id : ID d'instance de la base de données.
      - database_id : ID de la base de données.
    - agent_context_reference : établit un lien vers un contexte créé dans la base de données.
      - context_set_id : ID de contexte d'agent stocké dans la base de données. Pour en savoir plus sur la façon de trouver l'ID de l'ensemble de contexte, consultez Rechercher l'ID de contexte d'agent dans AlloyDB, Rechercher l'ID de contexte d'agent dans GoogleSQL pour Spanner, Rechercher l'ID de contexte d'agent dans Cloud SQL, et Rechercher l'ID de contexte d'agent dans Cloud SQL pour PostgreSQL.
generationOptions : configure le type de sortie à générer.
- generate_query_result : définissez la valeur sur "true" pour générer et renvoyer les résultats de la requête.
- generate_natural_language_answer : facultatif. Si la valeur est "true", une réponse en langage naturel est générée.
- generate_explanation : facultatif. Si la valeur est "true", une explication de la requête SQL est générée.
- generate_disambiguation_question : facultatif. Si la valeur est "true", des questions de clarification sont générées si la requête est ambiguë.

Exemple de réponse `QueryData`

Voici un exemple de réponse réussie à un appel 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."
}

Définir le contexte de l'agent de données pour les sources de données de base de données Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.