Documentação do Oracle Cloud Infrastructure

Início Rápido da Pesquisa SQL (NL2SQL)

Use o SQL Search (NL2SQL) para transformar uma pergunta em linguagem natural em SQL validado para dados corporativos na OCI Generative AI.

O NL2SQL usa um armazenamento semântico para mapear termos de negócios para campos de banco de dados, tabelas e junções. Ele gera apenas SQL. O Servidor MCP do Database Tools autoriza e executa a consulta no banco de dados de origem usando as permissões do usuário final.

Antes de Começar

Antes de usar o NL2SQL, verifique se você tem um banco de dados de origem e configure as conexões de banco de dados necessárias.

No mínimo, você precisa de:

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

Conceitos Básicos

As etapas a seguir fornecem uma visão geral de como estabelecer conexão com um banco de dados, preparar um armazenamento semântico NL2SQL e submeter perguntas de linguagem natural por meio de um cliente compatível com MCP.

  1. Crie as conexões de banco de dados necessárias.

    Crie uma conexão para enriquecimento e uma conexão separada e de menor privilégio para consultas.

  2. Crie e enriqueça uma loja semântica.

    Selecione as duas conexões, selecione os esquemas aprovados e aguarde a conclusão do enriquecimento.

  3. Configure o servidor MCP das ferramentas de banco de dados e o conjunto de ferramentas MCP.

    Configure o servidor e crie um conjunto de ferramentas que permita ao cliente usar NL2SQL para gerar SQL e executar SQL aprovado no banco de dados de origem.

  4. Conecte um cliente e faça uma pergunta.

    Use um cliente Oracle ou seu próprio cliente de chat ou agente compatível com MCP.

Dica

Para obter instruções sobre como configurar o Servidor MCP do Database Tools e integrar um cliente, consulte Etapas para Criar um Servidor MCP do Database Tools e Integrar com o Cliente.

No runtime: O cliente envia uma pergunta ao Servidor MCP do serviço Database Tools. O NL2SQL gera SQL e o Servidor MCP autoriza a solicitação e executa a consulta usando as permissões do banco de dados do usuário final.

Criar um Armazenamento Semântico

Para usar o NL2SQL, crie um armazenamento semântico no OCI Generative AI.

Um armazenamento semântico é suportado por um armazenamento de vetores com dados estruturados e inclui duas conexões do serviço Database Tools:

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

Na Console

Na Console, crie um armazenamento de vetores e selecione Dados estruturados. Nas opções de armazenamento semântico, selecione a conexão de enriquecimento, a conexão de consulta e os esquemas que o NL2SQL pode usar.

Usando a API do OCI Generative AI

Use a operação CreateSemanticStore na API do OCI Generative AI para criar um armazenamento semântico.

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

A operação CreateSemanticStore usa autenticação baseada no OCI IAM.

Conexões do Serviço Database Tools

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 requer privilégios para:

  • Executar consultas.
  • Executar operações DDL (Data Definition Language) necessárias.
  • Acesse os valores de exemplo permitidos 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 gerar 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 final.

Mantenha as conexões de enriquecimento e consulta separadas para distinguir o enriquecimento da execução de consultas e oferecer suporte a controle de acesso mais seguro.

Refinamento

O processo de enriquecimento lê metadados de esquema do banco de dados conectado. Esses metadados podem incluir tabelas, colunas, comentários do banco de dados, anotações e sinônimos. A OCI Generative AI usa essas informações para mapear termos em uma pergunta para os objetos de banco de dados apropriados e gerar SQL com base no contexto do esquema disponível.

Selecione quando executar o enriquecimento:

  • Na criação: O enriquecimento é iniciado automaticamente após a criação do armazenamento semântico.
  • Manual: O enriquecimento começa posteriormente por meio de uma operação de API separada.

Para iniciar o enriquecimento manualmente, chame a operação GenerateEnrichmentJob.

Gerar SQL com Linguagem Natural

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

Esta operação:

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

A operação GenerateSqlFromNl não executa o SQL no banco de dados.

Execução da Consulta

O Servidor MCP do Database Tools gerencia o fluxo de execução:

  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 mantém a execução da consulta no banco de dados de origem governado por permissões de banco de dados existentes.

Conectar um Cliente de Chat ou Agente

Configure um cliente Oracle ou um cliente de chat ou agente compatível com MCP para estabelecer conexão com o Servidor MCP do Database Tools. O Servidor MCP chama NL2SQL para gerar SQL e executa a consulta após autorizar a solicitação.

Um cliente também pode usar a API de Respostas do OCI com Chamada MCP para estabelecer conexão com o Servidor MCP do Serviço Database Tools.

Observação de integração: Não adicione NL2SQL diretamente como entrada tools da API de Respostas. Para um fluxo baseado em MCP, use o Servidor MCP do Database Tools. Para um fluxo baseado em API, chame GenerateSqlFromNl diretamente.

Para Solicitações de Longa Execução

Alguns fluxos de trabalho podem levar mais tempo do que uma solicitação de chat normal. Se o cliente da API de Respostas suportar processamento em segundo plano, armazene o ID de resposta retornado e verifique o status até que a solicitação seja finalizada. Forneça uma forma para o usuário cancelar a solicitação quando necessário. O processamento em segundo plano impede que um tempo limite do cliente seja tratado como uma consulta com falha.

Experimente

Após a configuração, comece com uma pergunta curta que use uma tabela conhecida. Por exemplo:

Quais cinco produtos tiveram as maiores vendas no mês passado?

Confirme se o cliente retorna a SQL gerada e, quando a execução é ativada, um resultado que segue as permissões do banco de dados do usuário.

Operações de API NL2SQL

As seguintes operações da API do OCI Generative AI suportam NL2SQL:

Armazenamentos semânticos
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Cargos de Enriquecimento
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
Gerar SQL
GenerateSqlFromNl