Documentação do Oracle Cloud Infrastructure

Pesquisa SQL (NL2SQL)

Use a Pesquisa SQL (NL2SQL) para converter solicitações de linguagem natural em SQL validada para dados empresariais na OCI Generative AI.

O NL2SQL ajuda os Enterprise AI Agents a trabalhar com dados corporativos federados sem mover ou copiar os dados subjacentes. Ele usa uma camada de enriquecimento semântico para mapear termos de negócios para campos de banco de dados, tabelas e junções e, em seguida, gera SQL com base na entrada de linguagem natural.

O NL2SQL gera somente SQL. Ele não executa a consulta.

Antes de Começar

Antes de usar o NL2SQL, crie um banco de dados e configure as conexões de banco de dados necessárias.

No mínimo, você precisa de:

  • Um Oracle Autonomous Database de origem
  • Uma conexão de enriquecimento do serviço Database Tools
  • Uma conexão de consulta do serviço Database Tools

Criar um Armazenamento Semântico

Para usar o NL2SQL, crie um recurso de Armazenamento Semântico do OCI.

Um Armazenamento Semântico é suportado por um armazenamento de vetores com dados estruturados e inclui duas conexões do DBTools:

  • Conexão de Aprimoramento
  • Conexão de Consulta

Na Console

Na Console, crie um armazenamento de vetores e selecione Dados estruturados. Quando você seleciona Dados estruturados, as opções de configuração do Armazenamento Semântico são exibidas, incluindo as definições de enriquecimento e os detalhes da conexão do banco de dados.

Usando a API do OCI Generative AI

Na API do OCI Generative AI, crie um Armazenamento Semântico usando a operação CreateSemanticStore.

URL Base Caminho do Ponto Final Autenticação
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores Somente sessão do IAM

A API CreateSemanticStore faz parte da API do serviço OCI Generative AI e usa autenticação baseada no OCI IAM.

Conexões DBTools

O NL2SQL usa duas conexões de banco de dados com finalidades diferentes.

Conexão de Aprimoramento

A Conexão de Aprimoramento é a conexão com privilégios mais altos usada durante o aprimoramento. Ela precisa de privilégios para:

  • Executar consultas
  • Executar operações DDL
  • Acessar valores de exemplo do banco de dados

A OCI Generative AI usa essa conexão para ler informações do esquema e criar os metadados necessários para a geração de SQL.

Conexão de Consulta

A Conexão de Consulta é a conexão de menor privilégio usada para executar consultas em nome do usuário que está consultando.

Essa separação ajuda a manter as responsabilidades de geração e execução distintas e oferece suporte a controle de acesso mais seguro.

Refinamento

O processo de enriquecimento lê metadados de esquema, como tabelas e colunas, do banco de dados conectado. A OCI Generative AI usa esses metadados para gerar uma SQL melhor.

Você pode selecionar quando o enriquecimento for executado:

  • Na criação: O enriquecimento é iniciado automaticamente após a criação do Armazenamento Semântico
  • Manual: O enriquecimento é executado posteriormente por meio de uma chamada de API separada

Para acionar o enriquecimento manualmente, chame a API GenerateEnrichmentJob.

Gerar SQL com Linguagem Natural

Após a conclusão do enriquecimento, chame a API GenerateSqlFromNl para converter entrada de linguagem natural em SQL.

Esta API:

  • Aceita entrada de idioma natural
  • Usa os metadados semânticos aprimorados
  • Retorna SQL gerado

Essa API não executa o SQL no banco de dados.

Execução da Consulta

O Servidor MCP do DBTools orquestra o fluxo de execução completo:

  1. Chama o serviço NL2SQL para gerar SQL.
  2. Autoriza a solicitação.
  3. Executa a consulta no banco de dados de origem.
  4. Aplica os guardrails apropriados.
  5. Usa a identidade do usuário final para execução.

Isso permite que os agentes trabalhem com dados empresariais enquanto mantêm a execução no sistema de origem sob as permissões existentes.

Usar NL2SQL em um Workflow Agêntico

O NL2SQL pode fazer parte de um fluxo de trabalho agentic mais amplo.

Um cliente pode:

  1. Envie uma solicitação à API de Respostas para iniciar o planejamento do agente e solicitar a validação
  2. Chame GenerateSqlFromNl para converter a solicitação de linguagem natural em SQL
  3. Use o Servidor DBTools MCP para executar a consulta, se necessário
  4. Informe o SQL gerado ou os resultados da consulta novamente na API de Respostas para a próxima etapa do workflow

Isso permite combinar o acesso a dados estruturados com um raciocínio e uma orquestração mais amplos do agente.

Como o NL2SQL se adapta aos agentes

O NL2SQL é um recurso de dados empresariais na OCI Generative AI. Ele é útil quando seu agente precisa trabalhar com dados empresariais estruturados, traduzindo solicitações de linguagem de negócios em SQL.

Diferentemente de Pesquisa de Arquivo, Interpretador de Código, Chamada de Função e Chamada MCP, o NL2SQL não está configurado como uma entrada tools da API de Respostas. Ele usa seu próprio fluxo de API e recursos de suporte, centrados em:

  • Armazenamento Semântico
  • Conexões DBTools
  • Refinamento
  • GerarSqlFromNl

API NL2SQL

Você pode usar a seguinte API para a ferramenta NL2SQL:

Lojas Semânticas
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Cargos de Enriquecimento
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
  • GenerateSqlFromNl
Gerar SQL
GenerateSqlFromNl