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 contexte est une collection 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. L'ensemble de contexte 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 acceptées :

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

Que sont les ensembles de contexte ?

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 contexte.

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 la CLI Gemini. Vous importez ensuite le fichier de contexte dans un ensemble de contextes que vous créez dans la console Google Cloud. 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 ressemble à ceci :

{
  "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": "employee.\"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": "employee.\"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

Le fichier d'ensemble de contexte se compose d'un ensemble organisé de modèles et de facettes au format JSON. Il guide les outils tels que QueryData pour traduire les questions en langage naturel en requêtes pour une base de données spécifique. Définir le contexte permet de générer des requêtes SQL très précises pour les modèles de requêtes courants.

Pour maximiser la précision, assurez-vous que le contexte défini est exact et couvre de manière exhaustive les requêtes d'application attendues.

Les ensembles de contexte 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. Elles incluent également des explications pour fournir une justification déclarative de la génération du langage naturel en 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"
      }
    }
  ]
},
...

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

• nl_query : exemple de requête en langage naturel traitée par des outils tels que QueryData.
• sql : requête SQL pour la requête en langage naturel.
• intent : objectif ou but 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 : formulaire de l'intention, généré automatiquement et basé sur un modèle, avec des valeurs d'entité remplacées par des paramètres.
• parameterized_sql : formulaire de requête SQL basé sur un modèle et généré automatiquement, 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ête d'effectuer des recherches à facettes.

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

{
...
"facets": [
    {
      "sql_snippet": "employee.\"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": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

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

• sql_snippet : extrait SQL. Pour éviter toute ambiguïté, qualifiez les noms de colonnes avec les noms de tables (par exemple, table_name.column_name).
• intent : explication du prédicat SQL.
• manifest : forme généralisée et générée automatiquement de l'intention.
• parameterized_intent : formulaire de l'intention, généré automatiquement et basé sur un modèle, avec des valeurs d'entité remplacées par des paramètres.
• parameterized_sql_snippet : formulaire de sql_snippet basé sur un modèle et généré automatiquement, qui correspond à l'intention paramétrée.

Requêtes de recherche de valeurs

Les requêtes de recherche de valeurs sont des requêtes définies par les développeurs 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 contenant 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 des conversions.

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 de Heathrow ?", la base de données peut stocker le nom de l'aéroport sous la forme "Londres 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 qu'il mappe "Heathrow" à la valeur de base de données correcte "London Heathrow" et à son emplacement de schéma (airports.name), ce qui garantit l'exactitude du code SQL généré.

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

{
  ...
  "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"
    }
  ]
}

Voici les principaux composants de l'objet JSON de recherche de valeurs :

• query : instruction SQL paramétrée qui définit la logique permettant de faire correspondre une expression de valeur aux 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é permet d'associer des valeurs et, à terme, d'aider les outils tels que l'API QueryData à comprendre le rôle de l'expression de valeur dans le schéma. Elle 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 apparaît l'expression de la valeur.
• description : description de la logique de recherche.

Limites

Les ensembles de contexte présentent les limites suivantes :

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

Avertissement : Tous les contextes d'agent associés à une base de données sont visibles par tous les utilisateurs ayant un accès en lecture à cette base de données. Dans les cas où les utilisateurs disposent d'un accès plus limité à 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.

Étapes suivantes

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