Documentazione dell'infrastruttura Oracle Cloud

Avvio rapido di SQL Search (NL2SQL)

Utilizza SQL Search (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, selezionare gli schemi approvati e attendere il completamento dell'arricchimento.

  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 e gli schemi che NL2SQL può utilizzare.

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.

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:

  • Al momento della creazione: l'arricchimento viene avviato automaticamente dopo la creazione dell'area di memorizzazione semantica.
  • Manuale: l'integrazione inizia in un secondo momento tramite un'operazione API separata.

Per avviare manualmente l'arricchimento, chiamare l'operazione GenerateEnrichmentJob.

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.

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

Alcuni flussi di lavoro possono richiedere più tempo di una normale richiesta di chat. Se il client API Risposte supporta l'elaborazione in background, memorizzare l'ID risposta restituito e controllare lo stato fino al termine della richiesta. Fornire all'utente un modo per annullare la richiesta quando necessario. L'elaborazione in background impedisce che un timeout del client venga considerato come una query non riuscita.

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