Documentation sur Oracle Cloud Infrastructure

Guide de démarrage rapide Enterprise AI NL2SQL

Utilisez Enterprise AI 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.

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

  2. Créer et enrichir un magasin sémantique.

    Sélectionnez les deux connexions, les schémas approuvés et le modèle d'intelligence artificielle générative pour l'enrichissement. Attendez la fin de l'enrichissement.

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

  4. Connectez un client et posez une question.

    Utilisez un client Oracle ou votre propre client de clavardage ou d'agent compatible MCP.

Conseil

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 du magasin sémantique, sélectionnez la connexion d'enrichissement, la connexion d'interrogation, les schémas que NL2SQL peut utiliser et le modèle d'IA générative pour l'enrichissement. Pour obtenir des instructions complètes, voir Création d'un magasin de vecteurs.

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.

Sélectionner un modèle pour NL2SQL

Enterprise AI NL2SQL vous permet de sélectionner un modèle d'IA générative pour l'enrichissement du magasin sémantique et pour une demande individuelle Générer SQL. La sélection de modèles vous aide à choisir un modèle qui répond le mieux à vos besoins en matière de charge de travail.

NL2SQL utilise des modèles génératifs pour enrichir les métadonnées de base de données et générer du code SQL. Le modèle d'intégration est sélectionné et géré par le service.

Fonctionnement de la sélection de modèle

  • Magasin sémantique : Sélectionnez un modèle lorsque vous créez ou mettez à jour un magasin sémantique. NL2SQL utilise le modèle sélectionné pour l'enrichissement. Si vous modifiez le modèle, NL2SQL recrée les métadonnées enrichies à l'aide du nouveau modèle sélectionné. Le magasin sémantique reste disponible pendant l'exécution de la reconstruction.
  • Générer SQL : Facultativement, sélectionnez un modèle pour une demande de génération SQL individuelle. NL2SQL utilise le modèle sélectionné pour identifier les tables pertinentes, générer du code SQL et affiner le code SQL au besoin.

Si vous ne sélectionnez pas de modèle, NL2SQL utilise openai.gpt-oss-120b pour l'enrichissement et Générer SQL.

Modèles pris en charge

Vous pouvez sélectionner n'importe quel modèle d'IA générative disponible pour l'inférence sur demande dans la région et accessible à votre location. Les points d'extrémité dédiés à l'IA, le réglage des paramètres du modèle et les modèles d'intégration sélectionnés par l'utilisateur ne sont pas pris en charge.

NL2SQL est disponible uniquement dans les régions sélectionnées. Le modèle sélectionné doit être disponible pour l'inférence sur demande dans la région où vous utilisez NL2SQL. Voir Modèles d'IA générative par région.

Note

OpenAI gpt-oss-120b est le modèle par défaut et a été évalué spécifiquement pour NL2SQL. D'autres modèles sur demande pris en charge ont été évalués pour une utilisation avec l'IA générative d'OCI, mais leur précision et leur performance propres à NL2SQL n'ont pas été évaluées. Nous vous recommandons d'évaluer le modèle sélectionné avec votre schéma et votre charge de travail avant de l'utiliser en production.

Utiliser l'API

Lorsque vous créez ou mettez à jour un magasin sémantique, utilisez modelSelection pour sélectionner un modèle personnalisé pour l'enrichissement :

{
  "modelSelection": {
    "modelSelectionType": "CUSTOM",
    "modelId": "google.gemini-2.5-flash"
  }
}

Pour une demande de génération SQL, utilisez modelId pour sélectionner le modèle pour cette demande :

{
  "inputNaturalLanguageQuery": "Which five products had the highest sales last month?",
  "modelId": "google.gemini-2.5-flash"
}

modelId est facultatif pour Générer SQL. Si vous l'omettez, NL2SQL utilise openai.gpt-oss-120b. La réponse de la tâche Générer SQL inclut le modèle utilisé.

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 :

  • Aucun : Créez le magasin sémantique sans démarrer l'enrichissement. Vous pouvez exécuter l'enrichissement plus tard.
  • À la création : Démarrez l'enrichissement automatiquement après la création du magasin sémantique.
  • Intervalle : Actualisez les métadonnées enrichies selon un programme récurrent. Spécifiez la programmation comme durée ISO 8601. L'intervalle minimal est de six heures. Par exemple, utilisez PT6H pour actualiser les métadonnées toutes les six heures ou P1D pour les actualiser une fois par jour. Chaque actualisation utilise le modèle d'intelligence artificielle générative sélectionné. Pour plus de formats de durée et d'exemples, voir Durée ISO 8601.

Pour utiliser l'option Intervalle au moyen de l'API, appelez l'opération GenerateEnrichmentJob et réglez enrichmentJobConfiguration à DeltaRefreshEnrichmentJobConfiguration. L'API utilise le terme actualisation delta, car chaque actualisation met à jour uniquement les objets de base de données qui ont été modifiés depuis l'enrichissement le plus récent au lieu de recréer toutes les métadonnées enrichies. La configuration identifie le schéma de base de données à actualiser.

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é
Important

L'opération GenerateSqlFromNl n'exécute pas le SQL sur la base de données.

Exécuter la génération SQL en arrière-plan

Utilisez le mode en arrière-plan lorsqu'une demande de génération SQL peut prendre plus de temps que la temporisation normale de la demande du client. Le mode en arrière-plan est disponible au moyen de l'API, des trousses SDK et de l'interface de ligne de commande. Il n'est pas disponible dans la console.

Réglez completionMode à BACKGROUND_JOB lors de l'appel de GenerateSqlFromNl. Le service accepte la demande et retourne une tâche que vous pouvez surveiller à l'aide de GetGenerateSqlFromNlJob. Lorsque la tâche réussit, extrayez l'énoncé SQL généré à partir de jobOutput. Si vous omettez completionMode, l'opération utilise WAIT_FOR_COMPLETION et attend la fin de la demande dans la temporisation définie par le service.

GetGenerateSqlFromNlJob est la source de vérité pour le statut et le résultat de la tâche finale.

Exécution de l'interrogation

Le serveur MCP du service d'outils de base de données gère le flux d'exécution :

  1. Appelle le service NL2SQL pour générer du code SQL.
  2. Autorise la demande.
  3. Exécute l'interrogation sur la base de données source.
  4. Applique les garde-corps appropriés.
  5. 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

Si un client de clavardage ou d'agent appelle NL2SQL au moyen du serveur MCP du service d'outils de base de données à l'aide de l'API des réponses OCI, le client peut utiliser le mode en arrière-plan de l'API des réponses pour un flux de travail de longue durée. Stockez l'ID réponse retourné et vérifiez le statut de la réponse jusqu'à la fin du traitement. Fournissez un moyen à l'utilisateur d'annuler la réponse si nécessaire.

Le mode en arrière-plan de l'API de réponses est distinct de la tâche en arrière-plan créée lorsqu'une application appelle GenerateSqlFromNl directement. L'API Réponses retourne un ID réponse, alors que GenerateSqlFromNl retourne un ID tâche. Pour les appels d'API directs, voir Exécuter la génération SQL en arrière-plan.

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
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Tâches d'enrichissement
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
Générer SQL
GenerateSqlFromNl