Présentation des ensembles de contextes

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service, et aux Conditions supplémentaires pour les produits d'IA générative en version preview. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

**Remarque sur l'interface PostgreSQL** : Les exemples de cette rubrique concernent les bases de données utilisant le dialecte GoogleSQL. Cette fonctionnalité n'est pas compatible avec l'interface PostgreSQL.

Un ensemble de contextes est un ensemble d'informations spécifiques à une base de données qui permet à des outils tels que QueryData de générer des requêtes avec une grande précision. Il inclut des modèles, des facettes et des recherches de valeurs qui aident QueryData à comprendre le schéma de votre base de données et la logique métier de vos applications.

Les bases de données suivantes sont compatibles :

• AlloyDB pour PostgreSQL
• Cloud SQL pour MySQL
• Cloud SQL pour PostgreSQL
• Spanner

Que sont les ensembles de contextes ?

Pour créer des applications agentiques efficaces, des outils tels que QueryData doivent comprendre l'organisation de vos données et votre logique métier. Vous fournissez ces informations sous la forme d'un ensemble de contextes.

Vous définissez le contexte dans des fichiers contenant des objets JSON pour chaque type de contexte. Vous créez ces fichiers de contexte à l'aide de Gemini CLI. Vous importez ensuite le fichier de contexte dans un ensemble de contextes que vous créez dans la Google Cloud console. Ce processus permet à des outils tels que QueryData d'apprendre le schéma spécifique de la base de données et la logique métier de l'application.

Le fichier de contexte se présente comme suit :

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Format du fichier d'ensemble de contextes

Un fichier d'ensemble de contextes est constitué d'un ensemble organisé de modèles et de facettes au format JSON qui guident des outils tels que QueryData dans la traduction de questions en langage naturel en requêtes pour une base de données spécifique. La définition du contexte garantit une génération SQL très précise pour les modèles de requêtes courants.

Assurez-vous que l'ensemble de contextes est précis et complet dans sa couverture des requêtes d'application attendues afin de maximiser la précision.

Les ensembles de contextes peuvent être créés dans les régions us-central1, us-east1, europe-west4 et asia-southeast1.

Modèles de requêtes

Les modèles de requêtes sont un ensemble organisé de questions représentatives en langage naturel avec les requêtes SQL correspondantes. Ils incluent également des explications pour fournir une justification déclarative de la génération du langage naturel vers SQL.

Un objet de modèle de requête se présente comme suit :

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

Les principaux composants de l'objet JSON du modèle de requête sont les suivants :

• nl_query: exemple de requête en langage naturel gérée par des outils tels que QueryData.
• sql : requête SQL pour la requête en langage naturel.
• intent : objectif ou finalité de la requête en langage naturel. Si elle n'est pas définie, cette valeur est définie par défaut sur la requête en langage naturel.
• manifest : forme généralisée et générée automatiquement de l'intention.
• parameterized_intent: forme modélisée et générée automatiquement de l'intention, avec des valeurs d'entité remplacées par des paramètres.
• parameterized_sql: forme modélisée et générée automatiquement de la requête SQL qui correspond à l'intention paramétrée.

Facettes de requête

Les facettes de requête sont un ensemble organisé de conditions représentatives en langage naturel avec les prédicats SQL correspondants. Les facettes gèrent le filtrage et les conditions, ce qui permet aux modèles de requêtes d'effectuer des recherches à facettes.

Un objet de facette de requête se présente comme suit :

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Les principaux composants de l'objet JSON de la facette sont les suivants :

• sql_snippet : extrait SQL.
• intent : explication du prédicat SQL.
• manifest : forme généralisée et générée automatiquement de l'intention.
• parameterized_intent: forme modélisée et générée automatiquement de l'intention, avec des valeurs d'entité remplacées par des paramètres.
• parameterized_sql_snippet: forme modélisée et générée automatiquement de l'extrait SQL qui correspond à l'intention paramétrée.

Requêtes de recherche de valeurs

Les [requêtes de recherche de valeurs](/spanner/docs/build-context-gemini-cli#generate-value-searches) sont des requêtes définies par le développeur qui utilisent des fonctions de correspondance pour trouver des valeurs et leur contexte dans une base de données. L'association de valeurs utilise les résultats de ces requêtes pour identifier les tables et les colonnes qui contiennent une valeur correspondante, comprendre le type de concept de la valeur et corriger les fautes d'orthographe.

L'API QueryData utilise l'association de valeurs pour convertir plus précisément le langage naturel en SQL. En utilisant des requêtes de recherche de valeurs, l'API peut corriger les fautes d'orthographe et résoudre les types de valeurs en fonction des valeurs de la base de données, ce qui améliore la précision de la conversion.

L'association de valeurs améliore la précision de la conversion du langage naturel en SQL. Par exemple, si un utilisateur demande "Y a-t-il des vols au départ d'Heathrow ?", la base de données peut stocker le nom de l'aéroport sous la forme "London Heathrow". Sans association de valeurs, le code SQL généré peut filtrer par WHERE name = 'Heathrow' et ne renvoyer aucun résultat. Les requêtes de recherche de valeurs guident l'agent pour mapper "Heathrow" à la valeur de base de données correcte "London Heathrow" et à son emplacement de schéma (airports.name), ce qui garantit la précision du code SQL généré.

Voici un exemple de requête de recherche de valeurs :

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Les principaux composants de l'objet JSON de recherche de valeurs sont les suivants :

• query : instruction SQL paramétrée qui définit la logique de correspondance d'une expression de valeur avec les valeurs stockées dans une colonne d'une table d'une base de données. L'ensemble de résultats projette généralement la valeur correspondante, l'emplacement du schéma, le type de concept et une métrique de distance normalisée (entre 0 et 1).
• concept_type : libellé sémantique attribué à la valeur, par exemple district ou loan_status. Ce libellé aide l'association de valeurs et, à terme, les outils tels que l'API QueryData à comprendre le rôle de l'expression de valeur dans le schéma. Il permet également de générer une instruction SQL qui cible le concept de la valeur, ainsi que la table et la colonne dans lesquelles l'expression de valeur apparaît.
• description : description de la logique de recherche.

Limites

Les ensembles de contextes sont soumis aux limites suivantes :

• Les ensembles de contextes pour les bases de données ne sont compatibles qu'avec les modèles, les facettes et les recherches de valeurs.
• Les ensembles de contextes pour les bases de données ne sont utilisés que par le point de terminaison QueryData de l'API Conversational Analytics.

Avertissement : Tous les contextes d'agent associés à une base de données sont visibles par tous les utilisateurs disposant d'un accès en lecture à cette base de données. Dans les cas où les utilisateurs disposent d'un accès plus restreint à la base de données, comme le contrôle précis des accès Spanner, ils peuvent potentiellement découvrir d'autres champs et tables à partir du contexte de l'agent.

Étape suivante

• Découvrez comment créer ou supprimer un ensemble de contextes dans Spanner Studio.