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, los esquemas aprobados y el modelo de IA generativa para el enriquecimiento. Luego, espera a que termine 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 de almacén semántico, seleccione la conexión de enriquecimiento, la conexión de consulta, los esquemas que puede utilizar NL2SQL y el modelo de IA generativa para el enriquecimiento. Para obtener instrucciones completas, consulte Creación de un almacén de vector.

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.

Selección de un Modelo para NL2SQL

Enterprise AI NL2SQL le permite seleccionar un modelo de IA generativa para el enriquecimiento de almacenes semánticos y para una solicitud de generación de SQL individual. La selección de modelos le ayuda a elegir el modelo que mejor se adapte a sus requisitos de carga de trabajo.

NL2SQL utiliza modelos generativos para enriquecer los metadatos de la base de datos y generar SQL. El servicio selecciona y gestiona el modelo de embebido.

Funcionamiento de la selección de modelos

  • Almacén semántico: seleccione un modelo al crear o actualizar un almacén semántico. NL2SQL utiliza el modelo seleccionado para el enriquecimiento. Si cambia el modelo, NL2SQL reconstruye los metadatos enriquecidos mediante el modelo recién seleccionado. El almacén semántico permanece disponible mientras se ejecuta la reconstrucción.
  • Generar SQL: si lo desea, seleccione un modelo para una solicitud de generación de SQL individual. NL2SQL utiliza el modelo seleccionado para identificar las tablas relevantes, generar SQL y acotar el SQL cuando sea necesario.

Si no selecciona un modelo, NL2SQL utiliza openai.gpt-oss-120b para el enriquecimiento y la generación de SQL.

Modelos soportados

Puede seleccionar cualquier modelo de IA generativa que esté disponible para la inferencia bajo demanda en la región y accesible para su arrendamiento. No se admiten los puntos finales de IA dedicados, el ajuste de parámetros de modelo y los modelos de incrustación seleccionados por el usuario.

NL2SQL solo está disponible en las regiones seleccionadas. El modelo seleccionado debe estar disponible para la inferencia bajo demanda en la región en la que utilice NL2SQL. Consulte Modelos de IA generativa por región.

Nota

OpenAI gpt-oss-120b es el modelo por defecto y se ha realizado una referencia específica para NL2SQL. Se han evaluado otros modelos a demanda compatibles para su uso con OCI Generative AI, pero su precisión y rendimiento específicos de NL2SQL no se han comparado. Se recomienda evaluar el modelo seleccionado con el esquema y la carga de trabajo antes de utilizarlo en producción.

Uso de la API

Al crear o actualizar un almacén semántico, utilice modelSelection para seleccionar un modelo personalizado para el enriquecimiento:

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

Para una solicitud Generate SQL, utilice modelId para seleccionar el modelo para esa solicitud:

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

modelId es opcional para Generar SQL. Si lo omite, NL2SQL utiliza openai.gpt-oss-120b. La respuesta del trabajo Generar SQL incluye el modelo utilizado.

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:

  • Ninguno: cree el almacén semántico sin iniciar el enriquecimiento. Puede ejecutar el enriquecimiento más tarde.
  • Al crear: inicia el enriquecimiento automáticamente después de crear el almacén semántico.
  • Intervalo: refresque los metadatos enriquecidos en un programa recurrente. Especifique el programa como una duración de ISO 8601. El intervalo mínimo es de seis horas. Por ejemplo, utilice PT6H para refrescar los metadatos cada seis horas o P1D para refrescarlos una vez al día. Cada refrescamiento utiliza el modelo de IA generativa seleccionado. Para obtener más ejemplos y formatos de duración, consulte Duraciones de ISO 8601.

Para utilizar la opción Intervalo a través de la API, llame a la operación GenerateEnrichmentJob y defina enrichmentJobConfiguration en DeltaRefreshEnrichmentJobConfiguration. La API utiliza el término refrescamiento delta porque cada refrescamiento actualiza solo los objetos de base de datos que han cambiado desde el enriquecimiento más reciente en lugar de volver a generar todos los metadatos enriquecidos. La configuración identifica el esquema de base de datos que se va a refrescar.

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.

Ejecutar generación SQL en segundo plano

Utilice el modo en segundo plano cuando una solicitud de generación SQL pueda tardar más tiempo que el timeout de solicitud normal del cliente. El modo en segundo plano está disponible mediante la API, los SDK y la CLI. No está disponible en la consola.

Defina completionMode en BACKGROUND_JOB al llamar a GenerateSqlFromNl. El servicio acepta la solicitud y devuelve un trabajo que puede supervisar mediante GetGenerateSqlFromNlJob. Cuando el trabajo se realice correctamente, recupere el SQL generado de jobOutput. Si omite completionMode, la operación utiliza WAIT_FOR_COMPLETION y espera a que la solicitud finalice dentro del timeout definido por el servicio.

GetGenerateSqlFromNlJob es la fuente de datos para el estado y el resultado del trabajo final.

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

Si un cliente de chat o agente llama a NL2SQL a través del servidor MCP de Database Tools mediante la API de respuestas de OCI, el cliente puede utilizar el modo en segundo plano de la API de respuestas para un flujo de trabajo de larga ejecución. Almacene el ID de respuesta devuelto y compruebe el estado de la respuesta hasta que finalice el procesamiento. Proporcione una forma para que el usuario cancele la respuesta cuando sea necesario.

El modo en segundo plano de la API de respuestas es independiente del trabajo en segundo plano creado cuando una aplicación llama directamente a GenerateSqlFromNl. La API Responses devuelve un ID de respuesta, mientras que GenerateSqlFromNl devuelve un ID de trabajo. Para llamadas de API directas, consulte Ejecución de la generación SQL en segundo plano.

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