Linee guida degli strumenti SQL per gli agenti AI generativi
Impostare uno strumento SQL (Structured Query Language) in un agente per generare istruzioni di query SQL da query in linguaggio naturale e, facoltativamente, eseguire le query.
Vengono generate ed eseguite solo query SQL SELECT
che includono join, più condizioni e aggregazione.
Aggiungendo uno strumento SQL a un agente, puoi eseguire query su un database senza una conoscenza approfondita di SQL e delle tecniche di ottimizzazione delle query.
Per consentire a un revisore umano di intervenire e modificare una query generata prima di inviarla all'utente, selezionare la funzione facoltativa Abilita umano nel loop nell'endpoint dell'agente.
Questo argomento descrive le informazioni di supporto, i task dei prerequisiti e le linee guida per l'aggiunta e l'utilizzo degli strumenti SQL negli agenti AI generativi.
Database
Lo strumento SQL negli agenti AI generativi supporta Oracle Database (Base Database e Autonomous Database).
Creare le tabelle e caricare i dati nel database preferito. Se si utilizza lo strumento SQL per generare istruzioni di query e quindi correggere automaticamente o eseguire le query, è necessario impostare una connessione degli strumenti di database al database che contiene dati per la query e l'esecuzione. Per informazioni sulla creazione di una connessione, vedere Crea connessione agli strumenti di database (linee guida).
Potrebbe non essere necessario creare tabelle nel database se si utilizza solo lo strumento SQL per generare istruzioni di query e non si sta abilitando lo strumento per correggere automaticamente o eseguire query SQL. Tuttavia, quando si crea lo strumento SQL in un agente, è comunque necessario fornire lo schema della tabella di database.
Schema di database
Quando si aggiunge uno strumento SQL a un agente in Agenti AI generativi, è necessario fornire uno schema di database valido. Creazione dello strumento SQL non riuscita nel passo di convalida se lo schema non è valido.
Uno schema valido è un progetto di database ben strutturato che include quanto segue:
-
Tabelle: definire le entità (ad esempio,
Customers
,Orders
) -
Colonne: specificare gli attributi (ad esempio,
CustomerID
,OrderDate
) -
Chiavi primarie: identificare in modo univoco le righe (ad esempio,
CustomerID
) -
Chiavi esterne: le tabelle dei collegamenti (ad esempio,
CustomerID
inOrders
fa riferimento aCustomers
). -
Vincoli: applica le regole (ad esempio,
NOT NULL
,UNIQUE
).
Esempio di schema valido:
CREATE TABLE Employees (
EmployeeID INT PRIMARY KEY,
Name VARCHAR(100) NOT NULL,
DepartmentID INT,
HireDate DATE NOT NULL,
FOREIGN KEY (DepartmentID) REFERENCES Departments(DepartmentID)
);
Uno schema ben strutturato garantisce l'integrità e l'efficienza dei dati.
Esempio di schema non valido:
CREATE TABLE Employees (
EmployeeID,
Name VARCHAR(100),
DepartmentID INT,
HireDate DATE
);
Uno schema non valido privo di struttura potrebbe causare potenziali incoerenze e inefficienze dei dati. Nell'esempio lo schema non è valido perché:
- Nello schema mancano le chiavi primarie (
EmployeeID
,DepartmentID
). - Manca un tipo di dati per
EmployeeID
.
Personalizzazione del modello
Quando si crea uno strumento SQL, è possibile scegliere tra l'utilizzo di un modello piccolo o grande.
Un modello di piccole dimensioni offre tempi di risposta più rapidi. Selezionare una piccola modalità per query semplici come "Ottieni vendite totali per gennaio 2025".
Un modello di grandi dimensioni offre maggiore precisione, ma al costo di una latenza più elevata. Selezionare un modello di grandi dimensioni per query più complesse, ad esempio "Mostra le vendite medie dei primi 5 prodotti con le migliori prestazioni in Q1 2023 raggruppati per area".
Diagramma del database
Lo strumento SQL supporta i dialetti Oracle SQL e SQLite.
In base al dialetto preferito, l'agente può generare query in linea con le regole sintattiche di Oracle SQL o SQLite.
Esempi di differenze di sintassi tra SQLite e 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';
Requisiti di rete e sicurezza
Assicurarsi di aver impostato i seguenti requisiti se si sta abilitando e utilizzando lo strumento SQL per eseguire le query SQL dopo aver generato le istruzioni SQL:
-
Affinché la regola di entrata venga configurata nella subnet privata di un database, vedere Requisiti di rete (senza supporto per più aree e più tenancy).
-
Per memorizzare il segreto password del database, è necessario un vault nel vault OCI Vault. Creare il vault nello stesso compartimento del database.
-
Se il database autonomo è abilitato per l'autenticazione MTLS (Mutual TLS), è necessario scaricare il wallet ed estrarre un file. Vedere Requisiti di sicurezza wallet.
Connessioni strumenti database
È possibile abilitare uno strumento SQL per correggere automaticamente ed eseguire una query dopo aver generato l'istruzione SQL. Quando l'esecuzione SQL o la correzione automatica è abilitata, è necessaria una connessione degli strumenti di database al database che contiene i dati per la query e l'esecuzione.
Per informazioni sulla creazione di una connessione, vedere Crea connessione agli strumenti di database (linee guida).
Storage degli oggetti per input e output
I bucket di storage degli oggetti possono essere utilizzati per contenere file di input nello strumento SQL. Se l'esecuzione SQL è abilitata su uno strumento SQL, i file di output delle query SQL in esecuzione possono essere memorizzati nello storage degli oggetti.
Input
Quando si aggiunge uno strumento SQL in un agente, è possibile immettere manualmente i dettagli o selezionare un file caricato in un bucket di storage degli oggetti per fornire l'input seguente:
- Schema di database
- Esempi di apprendimento contestuale
- Descrizione di tabelle e colonne
Per utilizzare i file caricati nello storage degli oggetti come input, assicurarsi di utilizzare il formato e l'estensione file appropriati per il tipo di input:
- Per lo schema di database: creare il file di schema e salvarlo con l'estensione file
.sql
. Ad esempio:hrcreate.sql
- Per esempi di apprendimento contestuale: aggiungere esempi in un file di testo utilizzando l'estensione file
.txt
. Ad esempio:hr-icl.txt
- Per la descrizione di tabelle e colonne: aggiungere descrizioni di tabelle e colonne in un file di testo utilizzando l'estensione file
.txt
. Ad esempio:hr-describe.txt
Output
Se l'esecuzione SQL è abilitata in uno strumento SQL, è inoltre possibile abilitare l'endpoint agente per memorizzare il risultato dell'output durante una sessione di chat. Se si abilita l'endpoint dell'agente per salvare i risultati dell'output di esecuzione SQL, assicurarsi di disporre di un bucket di storage degli oggetti nel compartimento preferito. È possibile impostare una regola dei criteri del ciclo di vita negli oggetti del bucket per specificare l'azione da eseguire, ad esempio l'eliminazione o l'archiviazione, quando la durata degli oggetti supera un numero di giorni specificato. È inoltre possibile utilizzare i filtri dei nomi oggetto per specificare a quali oggetti si applica la regola del ciclo di vita. Se hai bisogno di assistenza per la creazione della regola dei criteri e del filtro nello storage degli oggetti, consulta la sezione relativa alla creazione del criterio del ciclo di vita degli oggetti nello storage degli oggetti.
Per abilitare lo storage dei risultati di output in un endpoint dell'agente e specificare un bucket da utilizzare, vedere Creazione di un endpoint negli agenti AI generativi.
Quando lo storage dei risultati di output è abilitato, gli agenti AI generativi memorizzano l'output in un file .csv
nel bucket di storage degli oggetti specificato solo se il risultato contiene più di 100 righe durante la sessione di chat. Gli agenti AI generativi non memorizzano il risultato dell'output se sono presenti meno di 100 righe.
Criteri IAM
Assicurarsi di concedere agli utenti l'accesso a tutte le risorse degli agenti AI generativi, come descritto in Aggiunta di criteri prima di poter utilizzare il servizio.
Rivedere anche le sezioni riportate di seguito e completare i task necessari per utilizzare una funzione specifica in un agente con uno strumento SQL (ad esempio, abilitare l'esecuzione SQL).
Storage degli oggetti
Quando si imposta uno strumento SQL in un agente, è necessario fornire uno schema di database e, facoltativamente, esempi di apprendimento contestuale e descrizione di tabelle e colonne.
Se stai utilizzando i file di un bucket di storage degli oggetti per fornire l'input, concedi l'autorizzazione per leggere gli oggetti nello storage degli oggetti in un compartimento.
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' }
Esecuzione SQL, correzione automatica e storage di output
Se si abilita lo strumento SQL per eseguire la query SQL in una sessione di chat, è necessario disporre di una connessione Strumenti di database al database contenente i dati per la query e l'esecuzione. Per connettersi al database, scrivere il criterio riportato di seguito per concedere le autorizzazioni appropriate per accedere ai segreti del vault e al servizio Strumenti di database. Il criterio è obbligatorio anche se si abilita lo strumento SQL per eseguire l'autocorrezione in una sessione di chat dopo la convalida di un'istruzione di query SQL.
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'
Se l'esecuzione SQL è abilitata in uno strumento SQL, è inoltre possibile abilitare l'endpoint agente per memorizzare il risultato dell'output durante una sessione di chat se il risultato contiene più di 100 righe. Se si abilita il risultato dell'output, impostare il criterio seguente per concedere l'autorizzazione:
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' }
Esempi di apprendimento contestuale (facoltativo)
È possibile fornire il contesto dello schema di database sotto forma di domande di esempio che gli utenti potrebbero porre e le query SQL previste come risposte di esempio. Gli esempi di apprendimento contestuale sono utili per rispondere a query utente simili.
Esempi:
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';
Istruzioni personalizzate (facoltativo)
È possibile fornire una o più richieste per modificare il funzionamento dell'agente.
Ad esempio:
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.
Descrizione di tabelle e colonne (facoltativo)
L'aggiunta di descrizioni di tabelle e colonne può migliorare l'accuratezza delle query, gestire l'ambiguità e aiutare il modello a comprendere meglio query complesse e termini specifici. Ad esempio, la descrizione della colonna status
in Orders
come Order status: pending, shipped, or delivered
consente al modello di interpretarla correttamente nelle query utente.
Ad esempio:
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