Oracle Cloud Infrastructure-Dokumentation

Kurzanleitung für Enterprise AI NL2SQL

Verwenden Sie Enterprise AI NL2SQL, um eine Frage in natürlicher Sprache in validiertes SQL für Unternehmensdaten in OCI Generative AI zu verwandeln.

NL2SQL verwendet einen semantischen Speicher, um Geschäftsbegriffe Datenbankfeldern, Tabellen und Joins zuzuordnen. Es generiert nur SQL. Der MCP-Server für Datenbanktools autorisiert die Abfrage für die Quelldatenbank und führt sie mit den Berechtigungen des Endbenutzers aus.

Bevor Sie beginnen

Stellen Sie vor der Verwendung von NL2SQL sicher, dass Sie über eine Quelldatenbank verfügen, und konfigurieren Sie die erforderlichen Datenbankverbindungen.

Sie benötigen mindestens:

  • Eine Quelle für Oracle Autonomous AI Database
  • Verbindung zur Datenbanktoolserviceanreicherung
  • Abfrageverbindung zu Datenbanktools

Erste Schritte

Die folgenden Schritte bieten einen Überblick darüber, wie Sie eine Verbindung zu einer Datenbank herstellen, einen NL2SQL-Semantikspeicher vorbereiten und Fragen in natürlicher Sprache über einen MCP-kompatiblen Client weiterleiten.

  1. Erstellen Sie die erforderlichen Datenbankverbindungen.

    Erstellen Sie eine Verbindung zur Anreicherung und eine separate Verbindung mit niedrigeren Berechtigungen für Abfragen.

  2. Erstellen und anreichern Sie einen semantischen Speicher.

    Wählen Sie die beiden Verbindungen, die genehmigten Schemas und das generative KI-Modell für die Anreicherung aus. Warten Sie, bis die Anreicherung abgeschlossen ist.

  3. Konfigurieren Sie den MCP-Server und das MCP-Toolset für Datenbanktools.

    Konfigurieren Sie den Server, und erstellen Sie ein Toolset, mit dem der Client mit NL2SQL SQL generieren und genehmigte SQL-Anweisungen für die Quelldatenbank ausführen kann.

  4. Verbinden Sie einen Client und stellen Sie eine Frage.

    Verwenden Sie einen Oracle-Client oder einen eigenen MCP-kompatiblen Chat- oder Agent-Client.

Tipp

Anweisungen zum Konfigurieren des Datenbanktools-MCP-Servers und zum Integrieren eines Clients finden Sie unter Schritte zum Erstellen eines Datenbanktools-MCP-Servers und zum Integrieren mit dem Client.

Zur Laufzeit: Der Client sendet eine Frage an den MCP-Server für Datenbanktools. NL2SQL generiert SQL, und der MCP-Server autorisiert die Anforderung und führt die Abfrage mit den Datenbankberechtigungen des Endbenutzers aus.

Semantischen Speicher erstellen

Um NL2SQL zu verwenden, erstellen Sie einen semantischen Speicher in OCI Generative AI.

Ein semantischer Speicher wird von einem Vektorspeicher mit strukturierten Daten gesichert und umfasst zwei Datenbanktoolserviceverbindungen:

  • Anreicherungsverbindung
  • Abfrageverbindung

In der Konsole

Erstellen Sie in der Konsole einen Vektorspeicher, und wählen Sie Strukturierte Daten aus. Wählen Sie in den Optionen für den semantischen Speicher die Anreicherungsverbindung, die Abfrageverbindung, die Schemas, die NL2SQL verwenden kann, und das Modell für generative KI zur Anreicherung aus. Vollständige Anweisungen finden Sie unter Vektorspeicher erstellen.

Mit der OCI Generative AI-API

Verwenden Sie den Vorgang CreateSemanticStore in der OCI Generative AI-API, um einen semantischen Speicher zu erstellen.

Basis-URL Endpunktpfad Authentifizierung
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores Nur IAM-Session

Der Vorgang CreateSemanticStore verwendet die OCI-IAM-basierte Authentifizierung.

Modell für NL2SQL auswählen

Mit Enterprise AI NL2SQL können Sie ein generatives KI-Modell für die Anreicherung von Semantic Stores und für eine einzelne Anforderung "SQL generieren" auswählen. Mit der Modellauswahl können Sie ein Modell auswählen, das Ihren Workload-Anforderungen am besten entspricht.

NL2SQL verwendet generative Modelle, um Datenbankmetadaten anzureichern und SQL zu generieren. Das Einbettungsmodell wird vom Service ausgewählt und verwaltet.

Funktionsweise der Modellauswahl

  • Semantischer Speicher: Wählen Sie ein Modell aus, wenn Sie einen semantischen Speicher erstellen oder aktualisieren. NL2SQL verwendet das ausgewählte Modell zur Anreicherung. Wenn Sie das Modell ändern, erstellt NL2SQL die angereicherten Metadaten mit dem neu ausgewählten Modell neu. Der semantische Speicher bleibt während der Neuerstellung verfügbar.
  • SQL generieren: Wählen Sie optional ein Modell für eine einzelne Anforderung "SQL generieren" aus. NL2SQL verwendet das ausgewählte Modell, um relevante Tabellen zu identifizieren, SQL zu generieren und die SQL bei Bedarf zu verfeinern.

Wenn Sie kein Modell auswählen, verwendet NL2SQL openai.gpt-oss-120b zur Anreicherung und zum Generieren von SQL.

Unterstützte Models

Sie können ein beliebiges generatives KI-Modell auswählen, das für On-Demand-Inferenzen in der Region verfügbar und für Ihren Mandanten zugänglich ist. Dedizierte KI-Endpunkte, Modellparameteroptimierung und vom Benutzer ausgewählte Einbettungsmodelle werden nicht unterstützt.

NL2SQL ist nur in ausgewählten Regionen verfügbar. Das ausgewählte Modell muss für On-Demand-Inferenz in der Region verfügbar sein, in der Sie NL2SQL verwenden. Siehe Generative KI-Modelle nach Region.

Hinweis

OpenAI gpt-oss-120b ist das Standardmodell und wurde speziell für NL2SQL Benchmarking durchgeführt. Andere unterstützte On-Demand-Modelle wurden für die Verwendung mit OCI Generative AI bewertet, aber ihre NL2SQL-spezifische Genauigkeit und Performance wurden nicht verglichen. Wir empfehlen, das ausgewählte Modell mit Ihrem Schema und Ihrer Workload zu bewerten, bevor es in der Produktion verwendet wird.

API verwenden

Wenn Sie einen semantischen Speicher erstellen oder aktualisieren, wählen Sie mit modelSelection ein benutzerdefiniertes Modell für die Anreicherung aus:

{
  "modelSelection": {
    "modelSelectionType": "CUSTOM",
    "modelId": "google.gemini-2.5-flash"
  }
}

Verwenden Sie für eine Anforderung "SQL generieren" modelId, um das Modell für diese Anforderung auszuwählen:

{
  "inputNaturalLanguageQuery": "Which five products had the highest sales last month?",
  "modelId": "google.gemini-2.5-flash"
}

modelId ist für die Generierung von SQL optional. Wenn Sie es weglassen, verwendet NL2SQL openai.gpt-oss-120b. Die Jobantwort "SQL generieren" enthält das verwendete Modell.

Datenbanktools - Verbindungen

NL2SQL verwendet zwei Datenbankverbindungen mit unterschiedlichen Zwecken.

Anreicherungsverbindung

Die Anreicherungsverbindung ist die Verbindung mit höheren Berechtigungen, die während der Anreicherung verwendet wird. Erfordert Berechtigungen für:

  • Abfragen ausführen.
  • Erforderliche DDL-(Data Definition Language-)Vorgänge ausführen
  • Zugriff auf zulässige Beispielwerte aus der Datenbank.

OCI Generative AI verwendet diese Verbindung, um Schemainformationen zu lesen und die zum Generieren von SQL erforderlichen Metadaten zu erstellen.

Abfrageverbindung

Die Abfrageverbindung ist die Verbindung mit niedrigeren Berechtigungen, die zum Ausführen von Abfragen im Namen des Endbenutzers verwendet wird.

Trennen Sie die Anreicherungs- und Abfrageverbindungen voneinander, um Anreicherung von Abfrageausführung zu unterscheiden und eine sicherere Zugriffskontrolle zu unterstützen.

Erweiterung

Der Anreicherungsprozess liest Schemametadaten aus der verbundenen Datenbank. Diese Metadaten können Tabellen, Spalten, Datenbankkommentare, Annotationen und Synonyme enthalten. OCI Generative AI verwendet diese Informationen, um Begriffe in einer Frage den entsprechenden Datenbankobjekten zuzuordnen und SQL basierend auf dem verfügbaren Schemakontext zu generieren.

Wählen Sie aus, wann die Anreicherung ausgeführt werden soll:

  • Kein Wert: Erstellen Sie den semantischen Speicher, ohne die Anreicherung zu starten. Sie können die Anreicherung später ausführen.
  • Beim Erstellen: Starten Sie die Anreicherung automatisch, nachdem der semantische Speicher erstellt wurde.
  • Intervall: Aktualisieren Sie die angereicherten Metadaten in einem wiederkehrenden Zeitplan. Geben Sie den Zeitplan als ISO 8601-Dauer an. Das Mindestintervall beträgt sechs Stunden. Beispiel: Verwenden Sie PT6H, um die Metadaten alle sechs Stunden zu aktualisieren, oder P1D, um sie einmal täglich zu aktualisieren. Bei jeder Aktualisierung wird das ausgewählte Modell für generative KI verwendet. Weitere Dauerformate und Beispiele finden Sie unter ISO 8601-Dauer.

Um die Option Intervall über die API zu verwenden, rufen Sie den Vorgang GenerateEnrichmentJob auf, und setzen Sie enrichmentJobConfiguration auf DeltaRefreshEnrichmentJobConfiguration. Die API verwendet den Begriff Deltaaktualisierung, da bei jeder Aktualisierung nur die Datenbankobjekte aktualisiert werden, die seit der letzten Anreicherung geändert wurden, anstatt alle angereicherten Metadaten neu zu erstellen. Die Konfiguration identifiziert das zu aktualisierende Datenbankschema.

SQL aus natürlicher Sprache generieren

Rufen Sie nach Abschluss der Anreicherung den Vorgang GenerateSqlFromNl auf, um die Eingabe in natürlicher Sprache in SQL zu konvertieren.

Dieser Vorgang:

  • Akzeptiert Eingabe in natürlicher Sprache
  • Verwendet die angereicherten semantischen Metadaten
  • Gibt generierte SQL zurück
Wichtig

Der Vorgang GenerateSqlFromNl führt die SQL nicht für die Datenbank aus.

SQL-Generierung im Hintergrund ausführen

Verwenden Sie den Hintergrundmodus, wenn eine Anforderung zur SQL-Generierung länger dauern kann als der normale Anforderungstimeout des Clients. Der Hintergrundmodus ist über die API, SDKs und die CLI verfügbar. Sie ist in der Konsole nicht verfügbar.

Setzen Sie completionMode auf BACKGROUND_JOB, wenn Sie GenerateSqlFromNl aufrufen. Der Service akzeptiert die Anforderung und gibt einen Job zurück, den Sie mit GetGenerateSqlFromNlJob überwachen können. Wenn der Job erfolgreich ist, rufen Sie die generierte SQL aus jobOutput ab. Wenn Sie completionMode weglassen, verwendet der Vorgang WAIT_FOR_COMPLETION und wartet, bis die Anforderung innerhalb des servicedefinierten Timeout abgeschlossen ist.

GetGenerateSqlFromNlJob ist die Informationsquelle für den endgültigen Jobstatus und das Ergebnis.

Abfrageausführung

Der Database Tools MCP-Server verwaltet den Ausführungsablauf:

  1. Ruft den NL2SQL-Service auf, um SQL zu generieren.
  2. Autorisiert die Anforderung.
  3. Führt die Abfrage für die Quelldatenbank aus.
  4. Wendet die entsprechenden Leitschienen an.
  5. Verwendet die Identität des Endbenutzers zur Ausführung.

Dadurch wird die Abfrageausführung in der Quelldatenbank durch vorhandene Datenbankberechtigungen gesteuert.

Chat- oder Agent-Client verbinden

Konfigurieren Sie einen Oracle-Client oder einen MCP-kompatiblen Chat- oder Agent-Client, um eine Verbindung zum Database Tools MCP-Server herzustellen. Der MCP-Server ruft NL2SQL auf, um SQL zu generieren, und führt die Abfrage aus, nachdem er die Anforderung autorisiert hat.

Ein Client kann auch die OCI-Antworten-API mit MCP-Aufrufen verwenden, um eine Verbindung zum Datenbanktools-MCP-Server herzustellen.

Integrationshinweis: Fügen Sie NL2SQL nicht direkt als tools-Eintrag der Responses-API hinzu. Verwenden Sie für einen MCP-basierten Ablauf den Datenbanktools-MCP-Server. Bei einem API-basierten Ablauf rufen Sie GenerateSqlFromNl direkt auf.

Für Anforderungen mit langer Ausführungsdauer

Wenn ein Chat- oder Agent-Client NL2SQL über den Datenbanktools-MCP-Server mit der OCI-Responses-API aufruft, kann der Client den Responses-API-Hintergrundmodus für einen Workflow mit langer Ausführungszeit verwenden. Speichern Sie die zurückgegebene Antwort-ID, und prüfen Sie den Antwortstatus, bis die Verarbeitung abgeschlossen ist. Geben Sie dem Benutzer die Möglichkeit, die Antwort bei Bedarf abzubrechen.

Der Hintergrundmodus der Antwort-API ist vom Hintergrundjob getrennt, der erstellt wird, wenn eine Anwendung GenerateSqlFromNl direkt aufruft. Die Antwort-API gibt eine Antwort-ID zurück, während GenerateSqlFromNl eine Job-ID zurückgibt. Direkte API-Aufrufe finden Sie unter SQL-Generierung im Hintergrund ausführen.

Probieren

Beginnen Sie nach dem Setup mit einer kurzen Frage, die eine bekannte Tabelle verwendet. Beispiel:

Welche fünf Produkte hatten im vergangenen Monat den höchsten Umsatz?

Vergewissern Sie sich, dass der Client generiertes SQL zurückgibt. Wenn die Ausführung aktiviert ist, wird ein Ergebnis zurückgegeben, das den Datenbankberechtigungen des Benutzers entspricht.

NL2SQL-API-Vorgänge

Die folgenden OCI Generative AI-API-Vorgänge unterstützen NL2SQL:

Semantische Speicher
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Anreicherungsjobs
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
SQL generieren
GenerateSqlFromNl