Documentação do Oracle Cloud Infrastructure

Guia de Início Rápido do Enterprise AI NL2SQL

Use o Enterprise AI 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, os esquemas aprovados e o modelo de IA Generativa para enriquecimento. Então, espere o enriquecimento terminar.

  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, os esquemas que o NL2SQL pode usar e o modelo de IA Generativa para enriquecimento. Para obter instruções completas, consulte Criando um Armazenamento de Vetores.

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.

Selecione um Modelo para NL2SQL

O Enterprise AI NL2SQL permite selecionar um modelo de IA generativa para enriquecimento de armazenamento semântico e para uma solicitação Gerar SQL individual. A seleção do modelo ajuda você a escolher um modelo que melhor atenda aos seus requisitos de carga de trabalho.

O NL2SQL usa modelos generativos para enriquecer metadados de banco de dados e gerar SQL. O modelo de incorporação é selecionado e gerenciado pelo serviço.

Como Funciona a Seleção de Modelo

  • Armazenamento semântico: Selecione um modelo ao criar ou atualizar um armazenamento semântico. O NL2SQL usa o modelo selecionado para enriquecimento. Se você alterar o modelo, o NL2SQL reconstruirá os metadados aprimorados usando o modelo recém-selecionado. O armazenamento semântico permanece disponível durante a execução da reconstrução.
  • Gerar SQL: Opcionalmente, selecione um modelo para uma solicitação Gerar SQL individual. O NL2SQL usa o modelo selecionado para identificar tabelas relevantes, gerar SQL e refinar o SQL quando necessário.

Se você não selecionar um modelo, o NL2SQL usará openai.gpt-oss-120b para enriquecimento e Gerar SQL.

Modelos Suportados

Você pode selecionar qualquer modelo de IA Generativa disponível para inferência sob demanda na região e acessível à sua tenancy. Não há suporte para endpoints de IA dedicados, ajuste de parâmetros de modelo e modelos de incorporação selecionados pelo usuário.

O NL2SQL só está disponível em regiões selecionadas. O modelo selecionado deve estar disponível para inferência sob demanda na região em que você usa NL2SQL. Consulte Modelos de IA Generativa por Região.

Observação

OpenAI gpt-oss-120b é o modelo padrão e foi avaliado especificamente para NL2SQL. Outros modelos sob demanda suportados foram avaliados para uso com a OCI Generative AI, mas sua precisão e desempenho específicos do NL2SQL não foram comparados. Recomendamos avaliar o modelo selecionado com seu esquema e carga de trabalho antes de usá-lo na produção.

Usar a API

Quando você criar ou atualizar um armazenamento semântico, use modelSelection para selecionar um modelo personalizado para enriquecimento:

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

Para uma solicitação Gerar SQL, use modelId para selecionar o modelo para essa solicitação:

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

modelId é opcional para Gerar SQL. Se você o omitir, o NL2SQL usará openai.gpt-oss-120b. A resposta do job Gerar SQL inclui o modelo usado.

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:

  • Nenhum: Crie o armazenamento semântico sem iniciar o enriquecimento. Você pode executar o enriquecimento posteriormente.
  • Na criação: Inicie o enriquecimento automaticamente após a criação do armazenamento semântico.
  • Intervalo: Atualize os metadados aprimorados em uma programação recorrente. Especifique a programação como uma duração ISO 8601. O intervalo mínimo é de seis horas. Por exemplo, use PT6H para atualizar os metadados a cada seis horas ou P1D para atualizá-los uma vez por dia. Cada atualização usa o modelo de IA Generativa selecionado. Para obter mais formatos e exemplos de duração, consulte Durações do ISO 8601.

Para usar a opção Intervalo por meio da API, chame a operação GenerateEnrichmentJob e defina enrichmentJobConfiguration como DeltaRefreshEnrichmentJobConfiguration. A API usa o termo atualização delta porque cada atualização atualiza somente os objetos de banco de dados que foram alterados desde o enriquecimento mais recente, em vez de recriar todos os metadados enriquecidos. A configuração identifica o esquema do banco de dados a ser atualizado.

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.

Executar Geração de SQL em Segundo Plano

Use o modo em segundo plano quando uma solicitação de geração de SQL pode demorar mais do que o timeout de solicitação normal do cliente. O modo em segundo plano está disponível por meio da API, SDKs e CLI. Não está disponível na Console.

Defina completionMode como BACKGROUND_JOB ao chamar GenerateSqlFromNl. O serviço aceita a solicitação e retorna um job que você pode monitorar usando GetGenerateSqlFromNlJob. Quando o job for bem-sucedido, recupere a SQL gerada de jobOutput. Se você omitir completionMode, a operação usará WAIT_FOR_COMPLETION e aguardará a conclusão da solicitação dentro do timeout definido pelo serviço.

GetGenerateSqlFromNlJob é a fonte da verdade para o status e o resultado do cargo final.

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

Se um cliente de chat ou agente chamar o NL2SQL por meio do Servidor MCP do Database Tools usando a API de Respostas do OCI, o cliente poderá usar o modo de segundo plano da API de Respostas para um workflow de longa execução. Armazene o ID de resposta retornado e verifique o status da resposta até que o processamento seja concluído. Forneça uma maneira para o usuário cancelar a resposta quando necessário.

O modo de segundo plano da API de respostas é separado do job em segundo plano criado quando um aplicativo chama o GenerateSqlFromNl diretamente. A API de Respostas retorna um ID de resposta, enquanto GenerateSqlFromNl retorna um ID de job. Para chamadas diretas de API, consulte Executar Geração de SQL em Segundo Plano.

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