Directives relatives aux outils SQL pour les agents d'IA générative

L'outil SQL des agents d'IA générative prend en charge Oracle Database (Base de données de base 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 énoncés d'interrogation, puis que vous corrigez automatiquement ou exécutez les interrogations, vous devez configurer une connexion d'outils de base de données à la base de données qui contient des données pour l'interrogation et l'exécution. Pour obtenir de l'aide sur la création d'une connexion, voir Créer une connexion au service d'outils de base de données (directives).

Il se peut que vous n'ayez pas à créer des tables dans la base de données si vous utilisez uniquement l'outil SQL pour générer des énoncés d'interrogation et que vous n'activez pas l'outil pour corriger ou exécuter des interrogations SQL. Toutefois, vous devez toujours fournir le schéma de la 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 d'intelligence artificielle générative. 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 comprend les éléments suivants :

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

• Colonnes : Spécifiez des attributs (par exemple, CustomerID, OrderDate)

• Clés primaires : Identifiez de manière unique les rangées (par exemple, CustomerID)

• Clés étrangères : Les tables de liens (par exemple, CustomerID dans Orders font référence à Customers).

• Contraintes : Imposer 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é assure 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 qui manque 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 :

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

Lors de la création d'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 le total des ventes pour janvier 2025".

Un grand modèle offre plus de précision, mais au prix d'une latence plus élevée. Vous sélectionnez un modèle volumineux pour les interrogations plus complexes telles que "Afficher les ventes moyennes des 5 produits les plus performants dans Q1 2023 regroupés 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 interrogations qui s'alignent sur les 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';

Assurez-vous que les exigences suivantes sont configurées si vous activez et utilisez l'outil SQL pour exécuter les interrogations SQL après avoir généré les instructions SQL :

• Pour configurer la règle de trafic entrant sur le sous-réseau privé d'une base de données, voir Exigences relatives au réseau (sans prise en charge inter-région et interlocation).

• Une chambre forte dans le service de chambre forte OCI est requise pour stocker la clé secrète du mot de passe de la base de données. Créez la chambre forte 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. Voir Exigences de sécurité de portefeuille.

Vous pouvez activer un outil SQL pour vous corriger et exécuter une interrogation après avoir généré l'énoncé SQL. Lorsque l'exécution SQL ou l'auto-correction est activée, une connexion du service d'outils de base de données à la base de données contenant des données pour l'interrogation et l'exécution est requise.

Pour obtenir de l'aide sur la création d'une connexion, voir Créer une connexion au service d'outils de base de données (directives).

Les seaux de stockage d'objets peuvent être utilisés pour 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 interrogations SQL en cours d'exécution peuvent être stockés dans le stockage d'objets.

Assurez-vous d'accorder aux utilisateurs l'accès à toutes les ressources des agents d'IA générative, comme décrit sous Ajout de politiques avant de pouvoir 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 à l'aide d'un outil SQL (par exemple, activer l'exécution SQL).

• Stockage d'objets
• Exécution SQL, correction automatique et stockage de 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 d'exemples de réponses aux interrogations SQL attendues. Des exemples d'apprentissage en contexte sont utiles pour répondre à des interrogations d'utilisateurs 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 interrogations, gérer l'ambiguïté et aider le modèle à mieux comprendre les interrogations 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 interrogations d'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