SQL-Toolrichtlinien für generative KI-Agents
Richten Sie ein SQL-Tool (Structured Query Language) in einem Agent ein, um SQL-Abfrageanweisungen aus Abfragen in natürlicher Sprache zu generieren, und führen Sie optional die Abfragen aus.
Nur SQL-SELECT
-Abfragen wie Join, mehrere Bedingungen und Aggregation werden generiert und ausgeführt.
Wenn Sie einem Agent ein SQL-Tool hinzufügen, können Sie eine Datenbank abfragen, ohne sich mit SQL- und Abfrageoptimierungstechniken auskennen zu müssen.
Um eine generierte Abfrage eingreifen und bearbeiten zu lassen, bevor sie an den Benutzer gesendet wird, wählen Sie das optionale Feature Mensch in der Schleife aktivieren im Agent-Endpunkt aus.
In diesem Thema werden Supportinformationen, erforderliche Aufgaben und Richtlinien zum Hinzufügen und Verwenden von SQL-Tools in generativen KI-Agents beschrieben.
Datenbanken
Das SQL-Tool in generativen KI-Agents unterstützt Oracle Database (Base Database und Autonomous Database).
Erstellen Sie die Tabellen, und laden Sie Daten in die bevorzugte Datenbank. Wenn Sie Abfrageanweisungen mit dem SQL-Tool generieren und die Abfragen dann selbst korrigieren oder ausführen, müssen Sie eine Verbindung mit den Datenbanktools zur Datenbank einrichten, die Daten für die Abfrage und Ausführung enthält. Hilfe zum Erstellen einer Verbindung finden Sie unter Verbindung zu Datenbanktools erstellen (Richtlinien).
Sie müssen möglicherweise keine Tabellen in der Datenbank erstellen, wenn Sie das SQL-Tool nur zum Generieren von Abfrageanweisungen verwenden und das Tool keine Selbstkorrektur oder Ausführung von SQL-Abfragen ermöglicht. Sie müssen jedoch weiterhin das Datenbanktabellenschema angeben, wenn Sie das SQL-Tool in einem Agent erstellen.
Datenbankschema
Wenn Sie einem Agent in generativen KI-Agents ein SQL-Tool hinzufügen, muss ein gültiges Datenbankschema angegeben werden. Die Erstellung des SQL-Tools ist im Validierungsschritt nicht erfolgreich, wenn das Schema ungültig ist.
Ein gültiges Schema ist ein gut strukturierter Datenbank-Blueprint, der Folgendes enthält:
-
Tabellen: Definieren Sie Entitys (Beispiel:
Customers
,Orders
) -
Spalten: Geben Sie Attribute an (Beispiel:
CustomerID
,OrderDate
) -
Primärschlüssel: Eindeutige Identifizierung von Zeilen (Beispiel:
CustomerID
) -
Fremdschlüssel: Linktabellen (Beispiel:
CustomerID
inOrders
referenziertCustomers
). -
Constraints: Setzen Sie Regeln durch (Beispiel:
NOT NULL
,UNIQUE
).
Beispiel für ein gültiges Schema:
CREATE TABLE Employees (
EmployeeID INT PRIMARY KEY,
Name VARCHAR(100) NOT NULL,
DepartmentID INT,
HireDate DATE NOT NULL,
FOREIGN KEY (DepartmentID) REFERENCES Departments(DepartmentID)
);
Ein gut strukturiertes Schema sorgt für Datenintegrität und -effizienz.
Beispiel für ein ungültiges Schema:
CREATE TABLE Employees (
EmployeeID,
Name VARCHAR(100),
DepartmentID INT,
HireDate DATE
);
Ein ungültiges Schema ohne Struktur kann zu potenziellen Dateninkonsistenzen und Ineffizienzen führen. Im Beispiel ist das Schema ungültig. Grund:
- Dem Schema fehlen Primärschlüssel (
EmployeeID
,DepartmentID
). - Ein Datentyp für
EmployeeID
fehlt.
Modellanpassung
Beim Erstellen eines SQL-Tools können Sie zwischen einem kleinen oder einem großen Modell wählen.
Ein kleines Modell bietet schnellere Reaktionszeiten. Sie würden einen kleinen Modus für einfache Abfragen wie "Gesamtumsatz für Januar 2025 abrufen" auswählen.
Ein großes Modell bietet mehr Genauigkeit, aber auf Kosten einer höheren Latenz. Sie würden ein großes Modell für komplexere Abfragen auswählen, z.B. "Zeigen Sie den durchschnittlichen Umsatz der 5 leistungsstärksten Produkte in Q1 2023 gruppiert nach Region an."
Datenbankdialekt
Das SQL-Tool unterstützt die Dialekte Oracle SQL und SQLite.
Basierend auf Ihrem bevorzugten Dialekt kann der Agent Abfragen generieren, die mit den syntaktischen Regeln von Oracle SQL oder SQLite übereinstimmen.
Beispiele für Syntaxunterschiede zwischen SQLite und 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';
Netzwerk- und Sicherheitsanforderungen
Stellen Sie sicher, dass die folgenden Anforderungen eingerichtet sind, wenn Sie das SQL-Tool aktivieren und verwenden, um die SQL-Abfragen nach dem Generieren der SQL-Anweisungen auszuführen:
-
Informationen zur Konfiguration der Ingress-Regel im privaten Subnetz einer Datenbank finden Sie unter Netzwerkanforderungen (ohne regionsübergreifende und mandantenübergreifende Unterstützung).
-
Ein Vault in OCI Vault ist erforderlich, um das Datenbankkennwort-Secret zu speichern. Erstellen Sie den Vault in demselben Compartment wie die Datenbank.
-
Wenn die autonome Datenbank für die gegenseitige TLS-(mTLS-)Authentifizierung aktiviert ist, müssen Sie das Wallet herunterladen und eine Datei extrahieren. Siehe Wallet-Sicherheitsanforderungen.
Datenbanktools - Verbindung
Sie können ein SQL-Tool nach dem Generieren der SQL-Anweisung aktivieren, um sich selbst zu korrigieren und eine Abfrage auszuführen. Wenn entweder die SQL-Ausführung oder die Selbstkorrektur aktiviert ist, ist eine Verbindung der Datenbanktools zur Datenbank erforderlich, die Daten für die Abfrage und Ausführung enthält.
Hilfe zum Erstellen einer Verbindung finden Sie unter Verbindung zu Datenbanktools erstellen (Richtlinien).
Object Storage für Ein- und Ausgabe
Object Storage-Buckets können verwendet werden, um Eingabedateien für das SQL-Tool zu enthalten. Wenn die SQL-Ausführung für ein SQL-Tool aktiviert ist, können Ausgabedateien aus ausgeführten SQL-Abfragen in Object Storage gespeichert werden.
Eingabe
Wenn Sie ein SQL-Tool in einem Agent hinzufügen, können Sie manuell Details eingeben oder eine Datei auswählen, die in einen Objektspeicher-Bucket hochgeladen wurde, um die folgende Eingabe anzugeben:
- Datenbankschema
- Kontextbezogene Lernbeispiele
- Beschreibung von Tabellen und Spalten
Um hochgeladene Dateien in Object Storage als Eingabe zu verwenden, stellen Sie sicher, dass Sie das entsprechende Dateiformat und die entsprechende Erweiterung für den Eingabetyp verwenden:
- Für Datenbankschema: Erstellen Sie die Schemadatei, und speichern Sie sie mit der Dateierweiterung
.sql
. Beispiel:hrcreate.sql
- Für kontextbezogene Lernbeispiele: Fügen Sie Beispiele mit der Dateierweiterung
.txt
in eine Textdatei ein. Beispiel:hr-icl.txt
- Zur Beschreibung von Tabellen und Spalten: Fügen Sie Tabellen- und Spaltenbeschreibungen in einer Textdatei mit der Dateierweiterung
.txt
hinzu. Beispiel:hr-describe.txt
Ausgeben
Wenn die SQL-Ausführung für ein SQL-Tool aktiviert ist, können Sie dem Agent-Endpunkt auch ermöglichen, das Ausgabeergebnis während einer Chatsession zu speichern. Wenn Sie den Agent-Endpunkt zum Speichern der Ergebnisse der SQL-Ausführungsausgabe aktivieren, stellen Sie sicher, dass sich in Ihrem bevorzugten Compartment ein Objektspeicher-Bucket befindet. Sie können eine Lebenszyklus-Policy-Regel für die Objekte des Buckets einrichten, um die auszuführende Aktion (z.B. Löschen oder Archivieren) anzugeben, wenn das Alter der Objekte eine bestimmte Anzahl von Tagen überschreitet. Sie können auch Objektnamenfilter verwenden, um anzugeben, für welche Objekte die Lebenszyklusregel gelten soll. Wenn Sie Hilfe beim Erstellen der Policy-Regel und des Filters in Object Storage benötigen, finden Sie weitere Informationen unter Object Lifecycle Policy in Object Storage erstellen.
Informationen zum Aktivieren von Ausgabeergebnisspeicher auf einem Agent-Endpunkt und zum Angeben eines zu verwendenden Buckets finden Sie unter Endpunkt in generativen AI-Agents erstellen.
Wenn der Speicher für Ausgabeergebnisse aktiviert ist, speichern generative AI-Agents die Ausgabe nur dann in einer .csv
-Datei im angegebenen Objektspeicher-Bucket, wenn während der Chatsession mehr als 100 Zeilen in einem Ergebnis vorhanden sind. Generative AI-Agents speichern das Ausgabeergebnis nicht, wenn weniger als 100 Zeilen vorhanden sind.
IAM-Policys
Stellen Sie sicher, dass Sie Benutzern Zugriff auf alle Ressourcen von Generative AI-Agents erteilen, wie unter Policys hinzufügen, bevor Sie den Service verwenden können beschrieben.
Prüfen Sie auch die folgenden Abschnitte, und führen Sie die Aufgaben aus, die Sie zur Verwendung einer bestimmten Funktion in einem Agent mit einem SQL-Tool benötigen (z.B. SQL-Ausführung aktivieren).
Object Storage
Wenn Sie ein SQL-Tool in einem Agent einrichten, müssen Sie ein Datenbankschema sowie optional kontextbezogene Lernbeispiele und Beschreibungen von Tabellen und Spalten angeben.
Wenn Sie Dateien aus einem Objektspeicher-Bucket zum Bereitstellen der Eingabe verwenden, erteilen Sie die Berechtigung zum Lesen von Objekten in Object Storage in einem Compartment.
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' }
SQL-Ausführung, Selbstkorrektur und Ausgabespeicher
Wenn Sie das SQL-Tool aktivieren, um die SQL-Abfrage in einer Chatsession auszuführen, benötigen Sie eine Verbindung zu den Datenbanktools zur Datenbank, die Daten für die Abfrage und Ausführung enthält. Um eine Verbindung zur Datenbank herzustellen, schreiben Sie die folgende Policy, um die entsprechenden Berechtigungen für den Zugriff auf Vault Secrets und den Datenbanktoolservice zu erteilen. Die Policy ist auch erforderlich, wenn Sie das SQL-Tool nach der Validierung einer SQL-Abfrageanweisung zur Selbstkorrektur in einer Chatsession aktivieren.
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'
Wenn die SQL-Ausführung für ein SQL-Tool aktiviert ist, können Sie dem Agent-Endpunkt auch ermöglichen, das Ausgabeergebnis während einer Chatsession zu speichern, wenn das Ergebnis mehr als 100 Zeilen enthält. Wenn Sie Ausgabeergebnisse aktivieren, richten Sie die folgende Policy ein, um Berechtigungen zu erteilen:
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' }
Beispiele für kontextbezogene Lernaktivitäten (optional)
Sie können Kontext zum Datenbankschema in Form von Beispielfragen, die Benutzer stellen können, und den erwarteten SQL-Abfragen als Beispielantworten angeben. Kontextbezogene Lernbeispiele sind bei der Beantwortung ähnlicher Benutzeranfragen hilfreich.
Beispiele:
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';
Benutzerdefinierte Anweisungen (optional)
Sie können eine oder mehrere Prompts angeben, um das Verhalten des Agent zu ändern.
Beispiel:
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.
Beschreibung von Tabellen und Spalten (optional)
Das Hinzufügen von Tabellen- und Spaltenbeschreibungen kann die Abfragegenauigkeit verbessern, Mehrdeutigkeit verarbeiten und dem Modell helfen, komplexe Abfragen und bestimmte Begriffe besser zu verstehen. Beispiel: Wenn Sie die Spalte status
in Orders
als Order status: pending, shipped, or delivered
beschreiben, kann das Modell sie in Benutzerabfragen korrekt interpretieren.
Beispiel:
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