Instructions de l'outil SQL pour les agents d'IA générative

L'outil SQL dans les agents d'IA générative prend en charge Oracle Database (Base Database et Autonomous Database).

Créez les tables et chargez les données dans la base de données de votre choix. Si vous utilisez l'outil SQL pour générer des instructions de requête, puis que vous corrigez ou exécutez automatiquement les requêtes, vous devez configurer une connexion Database Tools à la base de données contenant les données de la requête et de l'exécution. Pour obtenir de l'aide sur la création d'une connexion, reportez-vous à Création d'une connexion Database Tools (directives).

Vous n'avez peut-être pas besoin de créer des tables dans la base de données si vous utilisez uniquement l'outil SQL pour générer des instructions de requête et que vous n'activez pas cet outil pour corriger ou exécuter des requêtes SQL. Toutefois, vous devez toujours fournir le schéma de table de base de données lorsque vous créez l'outil SQL dans un agent.

Un schéma de base de données valide doit être fourni lorsque vous ajoutez un outil SQL à un agent dans les agents Generative AI. La création de l'outil SQL échoue à l'étape de validation si le schéma n'est pas valide.

Un schéma valide est un modèle de base de données bien structuré qui inclut les éléments suivants :

• Tables : définissez des entités (par exemple, Customers, Orders).

• Colonnes : indiquez les attributs (par exemple, CustomerID, OrderDate)

• Clés primaires : identifiez de manière unique les lignes (par exemple, CustomerID)

• Clés étrangères : lie les tables (par exemple, CustomerID dans Orders référence Customers).

• Contraintes : appliquer des règles (par exemple, NOT NULL, UNIQUE).

Exemple de schéma valide :

CREATE TABLE Employees (
    EmployeeID INT PRIMARY KEY,
    Name VARCHAR(100) NOT NULL,
    DepartmentID INT,
    HireDate DATE NOT NULL,
    FOREIGN KEY (DepartmentID) REFERENCES Departments(DepartmentID)
);

Un schéma bien structuré garantit l'intégrité et l'efficacité des données.

Exemple de schéma non valide :

CREATE TABLE Employees (
    EmployeeID,
    Name VARCHAR(100),
    DepartmentID INT,
    HireDate DATE
);

Un schéma non valide dépourvu de structure peut entraîner des incohérences et des inefficacités de données potentielles. Dans l'exemple, le schéma n'est pas valide car :

• Des clés primaires sont manquantes dans le schéma (EmployeeID, DepartmentID).
• Un type de données pour EmployeeID est manquant.

Lorsque vous créez un outil SQL, vous pouvez choisir entre un modèle petit ou grand.

Un petit modèle offre des temps de réponse plus rapides. Vous sélectionnez un petit mode pour les requêtes simples telles que "Obtenir les ventes totales pour janvier 2025".

Un grand modèle offre plus de précision, mais au prix d'une latence plus élevée. Vous pouvez sélectionner un modèle volumineux pour les requêtes plus complexes telles que "Afficher les ventes moyennes des 5 produits les plus performants dans Q1 2023 regroupées par région".

L'outil SQL prend en charge les dialectes Oracle SQL et SQLite.

En fonction de votre dialecte préféré, l'agent peut générer des requêtes qui correspondent aux règles syntaxiques d'Oracle SQL ou de SQLite.

Exemples de différences de syntaxe entre SQLite et Oracle SQL :

Oracle: SELECT * FROM users FETCH FIRST 5 ROWS ONLY;
SQLite: SELECT * FROM users LIMIT 5;

Oracle: SELECT 'Hello' || ' World' FROM dual;
SQLite: SELECT 'Hello' || ' World';

Vérifiez que les exigences suivantes sont configurées si vous activez et utilisez l'outil SQL pour exécuter les requêtes SQL après avoir généré les instructions SQL :

• Pour obtenir la règle entrante à configurer sur le sous-réseau privé d'une base de données, reportez-vous à Exigences en matière de réseau (sans prise en charge inter-région et inter-locations).

• Un coffre dans OCI Vault est requis pour stocker la clé secrète de mot de passe de base de données. Créez le coffre dans le même compartiment que la base de données.

• Si la base de données autonome est activée pour l'authentification TLS mutuelle (mTLS), vous devez télécharger le portefeuille et extraire un fichier. Reportez-vous à la section Wallet Security Requirements.

Vous pouvez activer un outil SQL pour corriger automatiquement et exécuter une requête après avoir généré l'instruction SQL. Lorsque l'exécution SQL ou l'auto-correction est activée, une connexion Database Tools à la base de données contenant les données de la requête et de l'exécution est requise.

Pour obtenir de l'aide sur la création d'une connexion, reportez-vous à Création d'une connexion Database Tools (directives).

Les buckets Object Storage peuvent contenir des fichiers d'entrée dans l'outil SQL. Si l'exécution SQL est activée sur un outil SQL, les fichiers de sortie des requêtes SQL en cours d'exécution peuvent être stockés dans Object Storage.

Veillez à accorder aux utilisateurs l'accès à toutes les ressources des agents Generative AI, comme décrit dans Ajout de stratégies avant d'utiliser le service.

Consultez également les sections suivantes et effectuez les tâches dont vous avez besoin pour utiliser une fonction spécifique dans un agent avec un outil SQL (par exemple, activer l'exécution SQL).

• Object Storage
• Exécution SQL, correction automatique et stockage en sortie

Allow any-user to inspect buckets in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' }

Allow any-user to read objects in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' } 

Allow any-user to use database-tools-connections in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to read database-tools-family in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to read secret-family in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to {BUCKET_INSPECT, BUCKET_READ, OBJECT_INSPECT, OBJECT_READ, OBJECT_CREATE, OBJECT_OVERWRITE, PAR_MANAGE} in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' } 

Vous pouvez fournir un contexte sur le schéma de base de données sous la forme d'exemples de questions que les utilisateurs peuvent poser, et les requêtes SQL attendues comme exemples de réponses. Les exemples d'apprentissage en contexte sont utiles pour répondre à des requêtes utilisateur similaires.

Exemples :

Question: Show all employees who were born in CA.
Oracle SQL: SELECT * FROM Employees WHERE BIRTHSTATE = 'CA';

Question: Get the employeeid of employees who joined in 2020.
Oracle SQL: SELECT employeeID FROM Employees WHERE hireDate = '2020';

Vous pouvez fournir une ou plusieurs invites pour modifier le comportement de l'agent.

Exemple :

Always use aggregators such as COUNT, SUM, AVG, MIN, and MAX in Oracle SQL queries that contain GROUP BY.
If the Oracle SQL query contains ORDER BY, then show the ORDER BY metric in the SELECT clause as well.
If all columns must be returned, use the (*) notation.
Ensure to include all relevant WHERE filtering conditions even when the number of conditions is larger than those of in-context learning examples.

L'ajout de descriptions de table et de colonne peut améliorer la précision des requêtes, gérer l'ambiguïté et aider le modèle à mieux comprendre les requêtes complexes et les termes spécifiques. Par exemple, la description de la colonne status dans Orders en tant que Order status: pending, shipped, or delivered aide le modèle à l'interpréter correctement dans les requêtes utilisateur.

Exemple :

Description of the important tables in the schema:

Employees         Employee names and other information
Departments       Department names and other information 

Description of the important columns of the tables in the schema:

EMPLOYEES TABLE

employees.employeeID     A unique code assigned to each employee. employeeID links the data in this file with records in the other files.
employees.departmentID   A unique code that identifies the department an employee belongs to
employees.birthYear      Year employee was born
employees.birthMonth     Month employee was born
employees.birthState     State where employee was born
employees.birthCity      City where employee was born
employees.nameFirst      Employee's first name
employees.nameLast       Employee's last name
employees.nameMiddle     Employee's middle name
employees.hireDate       Year employee joined the company

---------------------------------------------------------------------
DEPARTMENTS TABLE

department.departmentID    A unique code assigned to each department
department.departmentName  Name of the department
department.locationID      Unique code that identifies the location of a department
department.managerID       Unique code that identifies the department's manager