Démarrage rapide de la recherche SQL (NL2SQL)
Utilisez SQL Search (NL2SQL) pour transformer une question en langage naturel en SQL validé pour les données d'entreprise dans OCI Generative AI.
NL2SQL utilise un magasin sémantique pour mapper des termes métier avec des champs, des tables et des jointures de base de données. Il génère uniquement du code SQL. Le serveur MCP du service d'outils de base de données autorise et exécute l'interrogation sur la base de données source à l'aide des autorisations de l'utilisateur final.
Avant de commencer
Avant d'utiliser NL2SQL, assurez-vous de disposer d'une base de données source et de configurer les connexions requises à la base de données.
Au minimum, vous devez :
- Source : Oracle Autonomous AI Database
- Connexion d'enrichissement du service d'outils de base de données
- Connexion d'interrogation du service d'outils de base de données
Démarrage
Les étapes suivantes fournissent un aperçu de la connexion à une base de données, préparent un magasin sémantique NL2SQL et soumettent des questions en langage naturel via un client compatible MCP.
-
Créez les connexions requises à la base de données.
Créez une connexion pour l'enrichissement et une connexion distincte avec privilèges inférieurs pour les interrogations.
-
Créer et enrichir un magasin sémantique.
Sélectionnez les deux connexions, sélectionnez les schémas approuvés et attendez la fin de l'enrichissement.
-
Configurez le serveur MCP et le jeu d'outils MCP du service d'outils du service d'outils de base de données.
Configurez le serveur et créez un jeu d'outils qui permet au client d'utiliser NL2SQL pour générer du code SQL et exécuter du code SQL approuvé sur la base de données source.
-
Connectez un client et posez une question.
Utilisez un client Oracle ou votre propre client de clavardage ou d'agent compatible MCP.
Pour obtenir des instructions sur la configuration du serveur MCP du service d'outils de base de données et l'intégration d'un client, voir Étapes de création d'un serveur MCP du service d'outils de base de données et d'intégration avec le client.
À l'exécution : Le client envoie une question au serveur MCP du service d'outils de base de données. NL2SQL génère du code SQL, et le serveur MCP autorise la demande et exécute l'interrogation à l'aide des autorisations de base de données de l'utilisateur final.
Créer un magasin sémantique
Pour utiliser NL2SQL, créez un magasin sémantique dans le service d'intelligence artificielle générative pour OCI.
Un magasin sémantique est soutenu par un magasin vectoriel avec des données structurées et comprend deux connexions au service d'outils de base de données :
- Connexion d'enrichissement
- Connexion à l'interrogation
Dans la console
Dans la console, créez un magasin de vecteurs et sélectionnez Données structurées. Dans les options de stockage sémantique, sélectionnez la connexion d'enrichissement, la connexion d'interrogation et les schémas que NL2SQL peut utiliser.
En utilisant l'API du service d'intelligence artificielle générative pour OCI
Utilisez l'opération CreateSemanticStore dans l'API du service d'intelligence artificielle générative pour OCI pour créer un magasin sémantique.
| URL de base | Chemin du point d'extrémité | Authentification |
|---|---|---|
https://generativeai.${region}.oci.oraclecloud.com/20231130 |
/semanticStores |
Session IAM uniquement |
L'opération CreateSemanticStore utilise l'authentification basée sur OCI IAM.
Connexions au service d'outils de base de données
NL2SQL utilise deux connexions de base de données à des fins différentes.
Connexion d'enrichissement
La connexion d'enrichissement est la connexion à privilèges supérieurs utilisée lors de l'enrichissement. Elle nécessite des privilèges pour :
- Exécuter des interrogations.
- Effectuez les opérations LDD (Langage de définition de données) requises.
- Accéder aux exemples de valeurs autorisés à partir de la base de données.
OCI Generative AI utilise cette connexion pour lire les informations de schéma et créer les métadonnées nécessaires pour générer SQL.
Connexion à l'interrogation
La connexion d'interrogation est la connexion avec privilèges inférieurs utilisée pour exécuter des interrogations pour le compte de l'utilisateur final.
Gardez les connexions d'enrichissement et d'interrogation séparées pour distinguer l'enrichissement de l'exécution d'interrogation et prendre en charge un contrôle d'accès plus sûr.
Enrichissement
Le processus d'enrichissement lit les métadonnées de schéma à partir de la base de données connectée. Ces métadonnées peuvent inclure des tables, des colonnes, des commentaires de base de données, des annotations et des synonymes. OCI Generative AI utilise ces informations pour mapper les termes d'une question aux objets de base de données appropriés et générer du code SQL en fonction du contexte de schéma disponible.
Sélectionnez quand exécuter l'enrichissement :
- À la création : L'enrichissement commence automatiquement après la création du magasin sémantique.
- Manuel : L'enrichissement commence plus tard au moyen d'une opération d'API distincte.
Pour démarrer l'enrichissement manuellement, appelez l'opération GenerateEnrichmentJob.
Générer SQL à partir du langage naturel
Une fois l'enrichissement terminé, appelez l'opération GenerateSqlFromNl pour convertir l'entrée en langue naturelle en SQL.
Cette opération :
- Accepte les entrées en langue naturelle
- Utilise les métadonnées sémantiques enrichies
- Retourne le code SQL généré
Exécution de l'interrogation
Le serveur MCP du service d'outils de base de données gère le flux d'exécution :
- Appelle le service NL2SQL pour générer du code SQL.
- Autorise la demande.
- Exécute l'interrogation sur la base de données source.
- Applique les garde-corps appropriés.
- Utilise l'identité de l'utilisateur final pour l'exécution.
Cela permet de maintenir l'exécution des interrogations dans la base de données source régie par les autorisations de base de données existantes.
Connecter un clavardage ou un client d'agent
Configurez un client Oracle ou un client de clavardage ou d'agent compatible MCP pour vous connecter au serveur MCP du service d'outils de base de données. Le serveur MCP appelle NL2SQL pour générer du code SQL et exécute l'interrogation après avoir autorisé la demande.
Un client peut également utiliser l'API de réponses OCI avec l'appel MCP pour se connecter au serveur MCP du service d'outils de base de données.
Note d'intégration : N'ajoutez pas NL2SQL directement en tant qu'entrée tools d'API de réponses. Pour un flux basé sur MCP, utilisez le serveur MCP du service d'outils de base de données. Pour un flux basé sur une API, appelez GenerateSqlFromNl directement.
Pour les demandes à exécution longue
Certains flux de travail peuvent prendre plus de temps qu'une demande de clavardage normale. Si le client d'API Réponses prend en charge le traitement en arrière-plan, stockez l'ID réponse retourné et vérifiez le statut jusqu'à la fin de la demande. Fournissez un moyen à l'utilisateur d'annuler la demande si nécessaire. Le traitement en arrière-plan empêche la temporisation d'un client d'être traitée en tant qu'interrogation en échec.
Essayer
Après la configuration, commencez par une courte question qui utilise une table connue. Par exemple :
Quels sont les cinq produits les plus vendus le mois dernier?
Vérifiez que le client retourne le code SQL généré et, lorsque l'exécution est activée, un résultat qui suit les autorisations de l'utilisateur sur la base de données.
Opérations d'API NL2SQL
Les opérations d'API du service d'intelligence artificielle générative pour OCI suivantes prennent en charge NL2SQL :
- Magasins sémantiques
-
CreateSemanticStoreListSemanticStoresGetSemanticStoreUpdateSemanticStoreChangeSemanticStoreCompartmentDeleteSemanticStore
- Tâches d'enrichissement
-
ListEnrichmentJobsGetEnrichmentJobGenerateEnrichmentJobCancelEnrichmentJob
- Générer SQL
GenerateSqlFromNl