Documentazione dell'infrastruttura Oracle Cloud

Guida di avvio rapido di Enterprise AI NL2SQL

Utilizza Enterprise AI NL2SQL per trasformare una domanda in linguaggio naturale in SQL convalidato per i dati aziendali in OCI Generative AI.

NL2SQL utilizza un'area di memorizzazione semantica per mappare i termini aziendali a campi di database, tabelle e join. Genera solo SQL. Il server MCP Strumenti di database autorizza ed esegue la query sul database di origine utilizzando le autorizzazioni dell'utente finale.

Prima di iniziare

Prima di utilizzare NL2SQL, assicurarsi di disporre di un database di origine e configurare le connessioni al database necessarie.

Come minimo, è necessario:

  • Oracle Autonomous AI Database di origine
  • Una connessione di arricchimento del servizio Database Tools
  • Una connessione query del servizio Database Tools

Introduzione

I passaggi seguenti forniscono una panoramica su come connettersi a un database, preparare un archivio semantico NL2SQL e inviare domande in lingua naturale tramite un client compatibile con MCP.

  1. Creare le connessioni al database necessarie.

    Creare una connessione per l'arricchimento e una connessione separata con privilegi inferiori per le query.

  2. Crea e arricchisci un negozio semantico.

    Selezionare le due connessioni, gli schemi approvati e il modello di intelligenza artificiale generativa per l'arricchimento. Aspetta che l'arricchimento finisca.

  3. Configurare il set di strumenti Server MCP e MCP degli strumenti di Database Tools.

    Configurare il server e creare un set di strumenti che consenta al client di utilizzare NL2SQL per generare SQL ed eseguire SQL approvato nel database di origine.

  4. Connetti un cliente e fai una domanda.

    Utilizzare un client Oracle o un client di chat o agente compatibile con MCP personale.

Suggerimento

Per istruzioni su come configurare il server MCP degli strumenti di database e integrare un client, vedere Passi per la creazione di un server MCP degli strumenti di database e l'integrazione con il client.

In runtime: il client invia una domanda al server MCP degli strumenti di database. NL2SQL genera SQL e MCP Server autorizza la richiesta ed esegue la query utilizzando le autorizzazioni del database dell'utente finale.

Creare un'area di memorizzazione semantica

Per utilizzare NL2SQL, creare un'area di memorizzazione semantica nell'AI generativa OCI.

Un'area di memorizzazione semantica è supportata da una area di memorizzazione vettoriale con dati strutturati e include due connessioni al servizio Strumenti di database:

  • Connessione di arricchimento
  • Connessione query

Nella console

Nella console creare una memoria di vettore e selezionare Dati strutturati. Nelle opzioni dell'area di memorizzazione semantica, selezionare la connessione di arricchimento, la connessione di query, gli schemi che NL2SQL può utilizzare e il modello di intelligenza artificiale generativa per l'arricchimento. Per istruzioni complete, vedere Creazione di una memoria di vettore.

Utilizzando l'API OCI Generative AI

Utilizzare l'operazione CreateSemanticStore nell'API OCI Generative AI per creare un'area di memorizzazione semantica.

URL di base Percorso endpoint Autenticazione
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores Solo sessione IAM

L'operazione CreateSemanticStore utilizza l'autenticazione basata su OCI IAM.

Selezionare un modello per NL2SQL

Enterprise AI NL2SQL ti consente di selezionare un modello di intelligenza artificiale generativa per l'arricchimento semantico-store e per una singola richiesta Genera SQL. La selezione dei modelli consente di scegliere un modello che soddisfi al meglio i requisiti del carico di lavoro.

NL2SQL utilizza modelli generativi per arricchire i metadati del database e generare SQL. Il modello di incorporamento viene selezionato e gestito dal servizio.

Funzionamento della selezione del modello

  • Area di memorizzazione semantica: selezionare un modello quando si crea o si aggiorna un'area di memorizzazione semantica. NL2SQL utilizza il modello selezionato per l'arricchimento. Se si modifica il modello, NL2SQL ricostruisce i metadati integrati utilizzando il nuovo modello selezionato. L'archivio semantico rimane disponibile durante l'esecuzione della rigenerazione.
  • Genera SQL: facoltativamente, selezionare un modello per una singola richiesta Genera SQL. NL2SQL utilizza il modello selezionato per identificare le tabelle pertinenti, generare SQL e perfezionare l'istruzione SQL quando necessario.

Se non si seleziona un modello, NL2SQL utilizza openai.gpt-oss-120b per l'arricchimento e Genera SQL.

Modelli supportati

Puoi selezionare qualsiasi modello di intelligenza artificiale generativa disponibile per l'inferenza su richiesta nell'area e accessibile alla tua tenancy. Gli endpoint AI dedicati, l'ottimizzazione dei parametri del modello e i modelli di incorporamento selezionati dall'utente non sono supportati.

NL2SQL è disponibile solo nelle aree selezionate. Il modello selezionato deve essere disponibile per l'inferenza su richiesta nell'area in cui si utilizza NL2SQL. Vedere Modelli di intelligenza artificiale generativa per area.

Nota

OpenAI gpt-oss-120b è il modello predefinito ed è stato confrontato in modo specifico per NL2SQL. Altri modelli on-demand supportati sono stati valutati per l'uso con OCI Generative AI, ma la loro accuratezza e performance specifiche di NL2SQL non sono state sottoposte a benchmark. Si consiglia di valutare il modello selezionato con lo schema e il carico di lavoro prima di utilizzarlo in produzione.

Utilizzare l'API

Quando si crea o si aggiorna un'area di memorizzazione semantica, utilizzare modelSelection per selezionare un modello personalizzato per l'integrazione.

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

Per una richiesta Genera SQL, utilizzare modelId per selezionare il modello per la richiesta:

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

modelId è facoltativo per Genera SQL. Se si omette, NL2SQL utilizza openai.gpt-oss-120b. La risposta del job Genera SQL include il modello utilizzato.

Connessioni strumenti database

NL2SQL utilizza due connessioni al database con scopi diversi.

Connessione di arricchimento

La connessione di integrazione è la connessione con privilegi più elevati utilizzata durante l'integrazione. Richiede privilegi per:

  • Eseguire le query.
  • Eseguire le operazioni DDL (Data Definition Language) necessarie.
  • Accedere ai valori di esempio consentiti dal database.

OCI Generative AI utilizza questa connessione per leggere le informazioni sullo schema e creare i metadati necessari per generare SQL.

Connessione query

La connessione query è la connessione con privilegi inferiori utilizzata per eseguire le query per conto dell'utente finale.

Mantieni separate le connessioni di arricchimento e query per distinguere l'arricchimento dall'esecuzione delle query e supportare un controllo dell'accesso più sicuro.

Arricchimento

Il processo di arricchimento legge i metadati dello schema dal database connesso. Questi metadati possono includere tabelle, colonne, commenti del database, annotazioni e sinonimi. OCI Generative AI utilizza queste informazioni per mappare i termini di una domanda agli oggetti di database appropriati e generare SQL in base al contesto dello schema disponibile.

Selezionare quando eseguire l'arricchimento:

  • Nessuno: crea l'area di memorizzazione semantica senza avviare l'arricchimento. È possibile eseguire l'integrazione in un secondo momento.
  • Al momento della creazione: avvia automaticamente l'arricchimento dopo la creazione dell'area di memorizzazione semantica.
  • Intervallo: aggiorna i metadati integrati in una schedulazione ricorrente. Specificare la pianificazione come durata ISO 8601. L'intervallo minimo è di sei ore. Ad esempio, utilizzare PT6H per aggiornare i metadati ogni sei ore o P1D per aggiornarli una volta al giorno. Ogni aggiornamento utilizza il modello AI generativa selezionato. Per ulteriori formati di durata ed esempi, vedere Durata di ISO 8601.

Per utilizzare l'opzione Intervallo tramite l'API, chiamare l'operazione GenateEnrichmentJob e impostare enrichmentJobConfiguration su DeltaRefreshEnrichmentJobConfiguration. L'API utilizza il termine aggiornamento delta perché ogni aggiornamento aggiorna solo gli oggetti di database modificati dopo l'arricchimento più recente invece di ricreare tutti i metadati integrati. La configurazione identifica lo schema di database da aggiornare.

Genera SQL da linguaggio naturale

Al termine dell'integrazione, chiamare l'operazione GenerateSqlFromNl per convertire l'input in linguaggio naturale in SQL.

Questa operazione:

  • Accetta input in linguaggio naturale
  • Utilizza i metadati semantici arricchiti
  • Restituisce SQL generato
Importante

L'operazione GenerateSqlFromNl non esegue l'istruzione SQL nel database.

Esegui generazione SQL in background

Utilizzare la modalità in background quando una richiesta di generazione SQL potrebbe richiedere più tempo del normale timeout della richiesta del client. La modalità in background è disponibile tramite API, SDK e CLI. Non è disponibile nella console.

Impostare completionMode su BACKGROUND_JOB quando si chiama GenerateSqlFromNl. Il servizio accetta la richiesta e restituisce un job che è possibile monitorare utilizzando GetGenerateSqlFromNlJob. Quando il job riesce, recuperare l'istruzione SQL generata da jobOutput. Se si omette completionMode, l'operazione utilizza WAIT_FOR_COMPLETION e attende il completamento della richiesta entro il timeout definito dal servizio.

GetGenerateSqlFromNlJob è l'origine delle informazioni relative allo stato e al risultato finale del job.

Esecuzione query

Database Tools MCP Server gestisce il flusso di esecuzione:

  1. Chiama il servizio NL2SQL per generare SQL.
  2. Autorizza la richiesta.
  3. Esegue la query sul database di origine.
  4. Applica i guardrail appropriati.
  5. Utilizza l'identità dell'utente finale per l'esecuzione.

Ciò consente di mantenere l'esecuzione delle query nel database di origine regolata dalle autorizzazioni del database esistenti.

Connettere un client chat o agente

Configurare un client Oracle o un client chat o agente compatibile con MCP per la connessione al server MCP degli strumenti di database. Il server MCP chiama NL2SQL per generare SQL ed esegue la query dopo aver autorizzato la richiesta.

Un client può anche utilizzare l'API Risposte OCI con Chiamata MCP per connettersi al server MCP Strumenti database.

Nota di integrazione: non aggiungere NL2SQL direttamente come voce tools dell'API delle risposte. Per un flusso basato su MCP, utilizzare Database Tools MCP Server. Per un flusso basato su API, chiamare direttamente GenerateSqlFromNl.

Per richieste con tempi diesecuzione lunghi

Se un client chat o agente richiama NL2SQL tramite il server MCP degli strumenti di database utilizzando l'API Risposte OCI, il client può utilizzare la modalità in background dell'API delle risposte per un workflow con tempi di esecuzione lunghi. Memorizzare l'ID risposta restituito e controllare lo stato della risposta fino al termine dell'elaborazione. Fornire all'utente un modo per annullare la risposta quando necessario.

La modalità di background dell'API Risposte è separata dal job in background creato quando un'applicazione chiama direttamente GenerateSqlFromNl. L'API Risposte restituisce un ID risposta, mentre GenerateSqlFromNl restituisce un ID job. Per le chiamate API dirette, vedere Esegui generazione SQL in background.

Provalo

Dopo l'impostazione, iniziare con una breve domanda che utilizza una tabella nota. Ad esempio:

Quali cinque prodotti hanno avuto le vendite più alte il mese scorso?

Verificare che il client restituisca l'istruzione SQL generata e, quando l'esecuzione è abilitata, un risultato che segue le autorizzazioni del database dell'utente.

Operazioni API NL2SQL

Le seguenti operazioni API OCI Generative AI supportano NL2SQL:

Aree di memorizzazione semantiche
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Job di integrazione
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
Genera SQL
GenerateSqlFromNl