Présentation des ensembles de contextes

Les ensembles de contextes vous permettent d'interagir avec les données de votre base de données à l'aide d'un langage conversationnel. Ils sont utilisés par des outils tels que QueryData pour créer des agents conversationnels. Vous pouvez créer des ensembles de contextes en définissant un contexte pour un ensemble de tables dans votre base de données. Ce contexte permet à QueryData de traduire les questions en langage naturel en requêtes précises pour vos cas d'utilisation cibles.

Un ensemble de contextes est une collection d'informations spécifiques à une base de données qui permet à 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

Quand utiliser des ensembles de contextes

Vous pouvez utiliser des ensembles de contextes pour créer des applications de données conversationnelles idéales pour des cas d'utilisation tels que les suivants :

  • Automatisation du service client : gérez un volume élevé de demandes telles que "Où en est ma commande ?" ou "Quel est mon solde actuel ?".
  • Assistants d'achat pour le e-commerce : aidez les utilisateurs à parcourir de grands catalogues de produits à l'aide de requêtes en langage naturel telles que « Montre-moi des chaussures de course à moins de 100 € ».
  • Outils pour les opérations sur le terrain : permettez aux employés mobiles d'interroger en temps réel les niveaux de stock , la disponibilité des pièces ou les détails des tickets d'assistance.

Fonctionnement des ensembles de contextes

Pour créer des applications agentiques efficaces, QueryData doit 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 à 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"
    }
   ]
}

Lorsqu'un utilisateur final pose une question en langage naturel, QueryData donne la priorité à la mise en correspondance de la question avec les modèles et les facettes qui ont été audités par le développeur qui gère le contexte. Une fois que QueryData a identifié une correspondance, il utilise le modèle de requête et les facettes sélectionnés pour synthétiser une requête de base de données. La logique de l'ensemble de contextes exécute ensuite cette requête sur la base de données pour renvoyer des résultats précis.

Il est recommandé de définir des recherches de valeurs dans votre contexte. Les recherches de valeurs permettent à l'agent de mapper des expressions de valeurs à des valeurs spécifiques stockées dans les colonnes de votre base de données. Cela ancre le LLM dans vos données réelles, ce qui l'aide à résoudre les ambiguïtés, par exemple si un terme fait référence à un nom de District ou à une City.

Si l'agent ne parvient pas à trouver de modèle correspondant, il utilise des recherches de valeurs pour mapper des expressions en langage naturel à des valeurs spécifiques stockées dans les colonnes de votre base de données. Cela ancre le LLM dans vos données réelles, ce qui l'aide à résoudre les ambiguïtés, par exemple si un terme fait référence à un District, un Name ou une City.

Le point de terminaison QueryData de l'API Conversational Analytics est un outil agentique qui permet une intégration programmatique à vos applications pour activer la génération de requêtes SQL à partir de questions en langage naturel. Dans une application conversationnelle, le point de terminaison QueryData doit être utilisé dans le framework qui gère l'historique et le contexte de la conversation.Pour appliquer la résolution d'entités tout en maintenant une sécurité stricte au niveau des lignes, vous pouvez utiliser des vues sécurisées paramétrées (PSV). Pour en savoir plus, consultez Sécuriser et contrôler l'accès aux données d'application à l'aide de vues sécurisées paramétrées

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 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 pour 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 QueryData.
  • sql : requête SQL pour la requête en langage naturel.
  • intent : objectif ou finalité de la requête en langage naturel. Si cette valeur n'est pas définie, elle 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 sql_snippet 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 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 de 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"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

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

  • query : instruction SQL paramétrée qui définit la logique de mise en 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, 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 :

  • Cloud SQL pour SQL Server n'est pas compatible.
  • 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.

Étape suivante