Directrices de herramientas SQL para agentes de IA generativa

La herramienta SQL en los agentes de IA generativa soporta Oracle Database (base de datos base y Autonomous Database).

Cree las tablas y cargue los datos en la base de datos preferida. Si utiliza la herramienta SQL para generar sentencias de consulta y, a continuación, corrige automáticamente o ejecuta las consultas, debe configurar una conexión de herramientas de base de datos a la base de datos que contenga datos para la consulta y la ejecución. Para obtener ayuda con la creación de una conexión, consulte Creación de conexión a Database Tools (directrices).

Es posible que no tenga que crear tablas en la base de datos si solo está utilizando la herramienta SQL para generar sentencias de consulta y no está activando la herramienta para autocorregir o ejecutar consultas SQL. Sin embargo, aún tendría que proporcionar el esquema de tabla de base de datos al crear la herramienta SQL en un agente.

Se debe proporcionar un esquema de base de datos válido al agregar una herramienta SQL a un agente en los agentes de IA generativa. La creación de la herramienta SQL falla en el paso de validación si el esquema no es válido.

Un esquema válido es un plano de base de datos bien estructurado que incluye lo siguiente:

• Tablas: Definir entidades (por ejemplo, Customers, Orders)

• Columnas: especifique atributos (por ejemplo, CustomerID, OrderDate)

• Claves primarias: identifique filas de forma única (por ejemplo, CustomerID)

• Claves ajenas: tablas de enlaces (por ejemplo, CustomerID en Orders hace referencia a Customers).

• Restricciones: aplique reglas (por ejemplo, NOT NULL, UNIQUE).

Ejemplo de un esquema válido:

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 esquema bien estructurado garantiza la integridad y eficiencia de los datos.

Ejemplo de un esquema no válido:

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

Un esquema no válido que carece de estructura puede dar lugar a posibles inconsistencias e ineficiencias de datos. En el ejemplo, el esquema no es válido porque:

• Faltan claves primarias en el esquema (EmployeeID, DepartmentID).
• Falta un tipo de dato para EmployeeID.

Al crear una herramienta SQL, puede seleccionar entre utilizar un modelo pequeño o grande.

Un modelo pequeño proporciona tiempos de respuesta más rápidos. Debe seleccionar un modo pequeño para consultas simples como "Obtener ventas totales para enero de 2025".

Un modelo grande proporciona más precisión, pero a costa de una mayor latencia. Debe seleccionar un modelo grande para consultas más complejas, como "Mostrar el promedio de ventas de los 5 productos con mejor rendimiento en Q1 2023 agrupados por región".

La herramienta SQL soporta los dialectos Oracle SQL y SQLite.

Según su dialecto preferido, el agente puede generar consultas que se alineen con las reglas sintácticas de Oracle SQL o SQLite.

Ejemplos de diferencias de sintaxis entre SQLite y 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';

Asegúrese de que tiene configurados los siguientes requisitos si está activando y utilizando la herramienta SQL para ejecutar las consultas SQL después de generar las sentencias SQL:

• Para que la regla de entrada se configure en la subred privada de una base de datos, consulte Requisitos de red (sin soporte entre regiones y entre arrendamientos).

• Se necesita un almacén en OCI Vault para almacenar el secreto de contraseña de la base de datos. Cree el almacén en el mismo compartimento que la base de datos.

• Si la base de datos autónoma está activada para la autenticación TLS mutua (mTLS), debe descargar la cartera y extraer un archivo. Consulte Requisitos de seguridad de cartera.

Puede activar una herramienta SQL para autocorregir y ejecutar una consulta después de generar la sentencia SQL. Cuando se activa la ejecución de SQL o la autocorrección, se necesita una conexión de Database Tools a la base de datos que contiene datos para la consulta y la ejecución.

Para obtener ayuda con la creación de una conexión, consulte Creación de conexión a Database Tools (directrices).

Los cubos de Object Storage se pueden utilizar para contener archivos de entrada en la herramienta SQL. Si la ejecución de SQL está activada en una herramienta SQL, los archivos de salida de la ejecución de consultas SQL se pueden almacenar en Object Storage.

Asegúrese de otorgar a los usuarios acceso a todos los recursos de agentes de IA generativa, como se describe en Adding Policies Before You Can Use the Service.

Revise también las siguientes secciones y complete las tareas que necesita para utilizar una función específica en un agente con una herramienta SQL (por ejemplo, activar la ejecución SQL).

• Almacenamiento de objetos
• Ejecución de SQL, Autocorrección y Almacenamiento de Salida

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' } 

Puede proporcionar contexto sobre el esquema de base de datos en forma de preguntas de ejemplo que los usuarios pueden hacer y las consultas SQL esperadas como respuestas de ejemplo. Los ejemplos de aprendizaje en contexto son útiles para responder consultas de usuarios similares.

Ejemplos:

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';

Puede proporcionar una o más peticiones de datos para modificar el comportamiento del agente.

Por ejemplo:

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.

La adición de descripciones de tablas y columnas puede mejorar la precisión de las consultas, manejar la ambigüedad y ayudar al modelo a comprender mejor las consultas complejas y los términos específicos. Por ejemplo, describir la columna status en Orders como Order status: pending, shipped, or delivered ayuda al modelo a interpretarla correctamente en las consultas de usuario.

Por ejemplo:

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