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.

Le contexte créé correspond aux 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 rédigé 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 référence de source de données. Les exemples de cette page utilisent la méthode QueryData.

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

Avant de commencer

Fournir du contexte avec QueryData

Lorsque vous appelez la méthode QueryData, vous fournissez la source de données et les informations contextuelles dans le champ QueryDataRequest.context.datasourceReferences. Pour les sources de données 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 rédigé, vous devez également fournir un 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 qui utilise alloydb. Le champ agent_context_reference.context_set_id permet d'associer un contexte pré-rédigé 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
 }
}

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 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 cette 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 du 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.
          • graph_ids : obligatoire pour Spanner Graph. Liste des noms de graphes de propriétés dans la base de données Spanner à interroger (par exemple, ["FinGraph"]). Si vous omettez graph_ids, QueryData génère des requêtes GoogleSQL sur les tables sous-jacentes au lieu de requêtes GQL.
        • agent_context_reference : liens vers le contexte créé dans la base de données.
  • generationOptions : configure le type de sortie à générer.
    • generate_query_result : définissez cette option 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", génère une réponse en langage naturel.
    • generate_explanation : facultatif. Si la valeur est définie sur "true", génère une explication de la requête SQL.
    • generate_disambiguation_question : facultatif. Si la valeur est "true", des questions de désambiguïsation 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 de la méthode 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."
}