Documentación de Oracle Cloud Infrastructure

Guía de inicio rápido de Enterprise AI NL2SQL

Utiliza Enterprise AI NL2SQL para convertir una pregunta en lenguaje natural en SQL validado para datos empresariales en OCI Generative AI.

NL2SQL utiliza un almacén semántico para asignar términos de negocio a campos, tablas y uniones de base de datos. Solo genera SQL. El servidor MCP de Database Tools autoriza y ejecuta la consulta en la base de datos de origen mediante los permisos del usuario final.

Antes de empezar

Antes de utilizar NL2SQL, asegúrese de que tiene una base de datos de origen y configure las conexiones de base de datos necesarias.

Como mínimo, necesita:

  • Oracle Autonomous AI Database de origen
  • Una conexión de enriquecimiento de servicio de Database Tools
  • Una conexión de consulta de servicio de Database Tools

Introducción

Los siguientes pasos proporcionan una visión general de cómo conectarse a una base de datos, preparar un almacén semántico NL2SQL y enviar preguntas en lenguaje natural a través de un cliente compatible con MCP.

  1. Cree las conexiones de base de datos necesarias.

    Cree una conexión para el enriquecimiento y una conexión independiente con menos privilegios para las consultas.

  2. Cree y enriquezca un almacén semántico.

    Seleccione las dos conexiones, seleccione los esquemas aprobados y espere a que finalice el enriquecimiento.

  3. Configure el conjunto de herramientas MCP Server y MCP de Database Tools.

    Configurar el servidor y crear un conjunto de herramientas que permita al cliente utilizar NL2SQL para generar SQL y ejecutar SQL aprobado en la base de datos origen.

  4. Conecta a un cliente y haz una pregunta.

    Utilice un cliente de Oracle o su propio chat o cliente de agente compatible con MCP.

Consejo

Para obtener instrucciones sobre cómo configurar el servidor MCP de Database Tools e integrar un cliente, consulte Pasos para crear un servidor MCP de Database Tools e integrarlo con el cliente.

En tiempo de ejecución: el cliente envía una pregunta al servidor MCP de Database Tools. NL2SQL genera SQL y MCP Server autoriza la solicitud y ejecuta la consulta mediante los permisos de la base de datos del usuario final.

Creación de una tienda semántica

Para utilizar NL2SQL, cree un almacén semántico en OCI Generative AI.

Un almacén semántico está respaldado por un almacén de vectores con datos estructurados e incluye dos conexiones de servicio de Database Tools:

  • Conexión de enriquecimiento
  • Conexión de consulta

En la consola

En la consola, cree un almacén de vectores y seleccione Datos estructurados. En las opciones del almacén semántico, seleccione la conexión de enriquecimiento, la conexión de consulta y los esquemas que puede utilizar NL2SQL.

Mediante el uso de OCI Generative AI API

Utilice la operación CreateSemanticStore en la API de IA generativa de OCI para crear un almacén semántico.

URL Base Ruta de punto final Autenticación
https://generativeai.${region}.oci.oraclecloud.com/20231130 /semanticStores Solo sesión de IAM

La operación CreateSemanticStore utiliza la autenticación basada en OCI IAM.

Conexiones de Herramientas de Base de Datos

NL2SQL utiliza dos conexiones de base de datos con fines diferentes.

Conexión de enriquecimiento

La conexión de enriquecimiento es la conexión con privilegios superiores que se utiliza durante el enriquecimiento. Necesita privilegios para:

  • Ejecutar consultas.
  • Realizar las operaciones de lenguaje de definición de datos (DDL) necesarias.
  • Acceda a los valores de ejemplo permitidos desde la base de datos.

OCI Generative AI utiliza esta conexión para leer la información del esquema y crear los metadatos necesarios para generar SQL.

Conexión de consulta

La conexión de consultas es la conexión con menos privilegios que se utiliza para ejecutar consultas en nombre del usuario final.

Mantenga las conexiones de enriquecimiento y consulta separadas para distinguir el enriquecimiento de la ejecución de consultas y admitir un control de acceso más seguro.

Enriquecimiento

El proceso de enriquecimiento lee los metadatos del esquema de la base de datos conectada. Estos metadatos pueden incluir tablas, columnas, comentarios de base de datos, anotaciones y sinónimos. OCI Generative AI utiliza esta información para asignar términos de una pregunta a los objetos de base de datos adecuados y generar SQL basado en el contexto de esquema disponible.

Seleccione cuándo se debe ejecutar el enriquecimiento:

  • Al crear: el enriquecimiento se inicia automáticamente después de crear el almacén semántico.
  • Manual: el enriquecimiento se inicia más tarde mediante una operación de API independiente.

Para iniciar el enriquecimiento manualmente, llame a la operación GenerateEnrichmentJob.

Generar SQL a partir de lenguaje natural

Una vez completado el enriquecimiento, llame a la operación GenerateSqlFromNl para convertir la entrada de lenguaje natural en SQL.

Esta operación:

  • Acepta la entrada de lenguaje natural
  • Utiliza los metadatos semánticos enriquecidos
  • Devuelve SQL generado
Importante

La operación GenerateSqlFromNl no ejecuta el SQL en la base de datos.

Ejecución de Consulta

El servidor MCP de Database Tools gestiona el flujo de ejecución:

  1. Llama al servicio NL2SQL para generar SQL.
  2. Autoriza la solicitud.
  3. Ejecuta la consulta en la base de datos origen.
  4. Aplica las barandillas adecuadas.
  5. Utiliza la identidad del usuario final para la ejecución.

Esto mantiene la ejecución de consultas en la base de datos de origen regida por los permisos de base de datos existentes.

Conexión de un chat o cliente de agente

Configure un cliente de Oracle o un cliente de agente o chat compatible con MCP para conectarse al servidor MCP de Database Tools. El servidor MCP llama a NL2SQL para generar SQL y ejecuta la consulta después de autorizar la solicitud.

Un cliente también puede utilizar la API de respuestas de OCI con llamadas MCP para conectarse al servidor MCP de Database Tools.

Nota de integración: no agregue NL2SQL directamente como entrada tools de la API de respuestas. Para un flujo basado en MCP, utilice el servidor MCP de Database Tools. Para un flujo basado en API, llame directamente a GenerateSqlFromNl.

Para solicitudes de larga ejecución

Algunos flujos de trabajo pueden tardar más que una solicitud de chat normal. Si el cliente de API de respuestas soporta el procesamiento en segundo plano, almacene el ID de respuesta devuelto y compruebe el estado hasta que finalice la solicitud. Proporcione una forma para que el usuario cancele la solicitud cuando sea necesario. El procesamiento en segundo plano evita que el timeout de un cliente se trate como una consulta fallida.

Probar

Después de la configuración, comience con una pregunta corta que utilice una tabla conocida. Por ejemplo:

¿Qué cinco productos tuvieron las mayores ventas el mes pasado?

Confirme que el cliente devuelve el SQL generado y, cuando la ejecución está activada, un resultado que sigue los permisos de la base de datos del usuario.

Operaciones de API de NL2SQL

Las siguientes operaciones de API de OCI Generative AI admiten NL2SQL:

Almacenes semánticos
  • CreateSemanticStore
  • ListSemanticStores
  • GetSemanticStore
  • UpdateSemanticStore
  • ChangeSemanticStoreCompartment
  • DeleteSemanticStore
Trabajos de enriquecimiento
  • ListEnrichmentJobs
  • GetEnrichmentJob
  • GenerateEnrichmentJob
  • CancelEnrichmentJob
Generar SQL
GenerateSqlFromNl