Paquete DBMS_CLOUD_AI

El paquete DBMS_CLOUD_AI facilita y configura la traducción de peticiones de datos en lenguaje natural a sentencias SQL.

Resumen de los subprogramas DBMS_CLOUD_AI

En esta sección se tratan los subprogramas DBMS_CLOUD_AI que proporciona Autonomous Database.

Subprograma Descripción

Procedimiento CREATE_PROFILE

Este procedimiento permite crear un nuevo perfil de AI para traducir peticiones de datos de lenguaje natural a sentencias SQL.

Procedimiento DISABLE_PROFILE

Este procedimiento desactiva un perfil de AI en la base de datos actual.

Procedimiento DROP_PROFILE

Este procedimiento elimina un perfil AI existente.

Procedimiento ENABLE_PROFILE

Este procedimiento permite que un perfil AI se utilice en la base de datos actual.

GENERAR Función

Esta función genera una sentencia SQL mediante AI para traducir.

Función GET_PROFILE

Esta función devuelve el nombre de perfil utilizado en la sesión actual.

Procedimiento GET_PROFILE

Este procedimiento devuelve el nombre de perfil y el propietario del perfil en la sesión actual.

Procedimiento SET_ATTRIBUTE

Este procedimiento establece los atributos de perfil de AI.

Procedimiento SET_PROFILE

Este procedimiento establece el perfil de AI para la base de datos actual.

Procedimiento CREATE_PROFILE

El procedimiento crea un nuevo perfil de AI para traducir peticiones de datos de lenguaje natural a sentencias SQL.

Sintaxis

DBMS_CLOUD_AI.CREATE_PROFILE
   profile_name        IN  VARCHAR2,
   attributes          IN  CLOB      DEFAULT NULL,
   status              IN  VARCHAR2  DEFAULT NULL,
   description         IN  CLOB      DEFAULT NULL
);

Parámetros

parámetro Descripción

profile_name

Un nombre para el perfil de AI. El nombre del perfil debe seguir las reglas de nomenclatura del identificador SQL de Oracle. La longitud máxima del nombre de perfil es de 125 caracteres.

Este parámetro es obligatorio.

attributes

Atributos de perfil en formato JSON. Consulte Atributos de perfil de AI para obtener más información.

El valor por defecto es NULL.

status

Estado del perfil.

El valor por defecto es Enable.

description

Descripción del perfil de AI.

El valor por defecto es NULL.

Ejemplo

BEGIN
     DBMS_CLOUD_AI.CREATE_PROFILE(
          profile_name    => 'OpenAI',
          attributes      => JSON_OBJECT('provider' value 'openai',
                                         'credential_name' value 'openai_cred'),
          description     => 'AI profile to use OpenAI for SQL translation'
     );
END;
/

Procedimiento DROP_PROFILE

El procedimiento elimina un perfil AI existente. Si el perfil no existe, el procedimiento devuelve un error.

Sintaxis

DBMS_CLOUD_AI.DROP_PROFILE(
       profile_name        IN   VARCHAR2,
       force               IN   BOOLEAN DEFAULT FALSE
 );

Parámetros

parámetro Descripción

profile_name

Nombre del perfil de AI

force

Si es TRUE, el procedimiento ignora los errores si el perfil de AI no existe.

El valor por defecto de este parámetro es FALSE.

Ejemplo

BEGIN
     DBMS_CLOUD_AI.DROP_PROFILE(profile_name => 'OPENAI');
END;
/

Notas de Uso

Utilice force para borrar un perfil e ignorar los errores si el perfil AI no existe.

Procedimiento ENABLE_PROFILE

Este procedimiento activa el perfil AI que especifica el usuario. El procedimiento cambia el estado del perfil de AI a ENABLED.

Sintaxis

DBMS_CLOUD_AI.ENABLE_PROFILE(
     profile_name         IN   VARCHAR2
 );

Parámetros

parámetro Descripción

profile_name

Nombre del perfil de AI que activar

Este parámetro es obligatorio.

Ejemplo para activar el perfil de AI

BEGIN
     DBMS_CLOUD_AI.ENABLE_PROFILE(
         profile_name    => 'OPENAI'
     );
END;
/

Procedimiento DISABLE_PROFILE

Este procedimiento desactiva el perfil AI en la base de datos actual. El estado del perfil de AI se cambia a DISABLED mediante este procedimiento.

Sintaxis

DBMS_CLOUD_AI.DISABLE_PROFILE(
      profile_name  IN  VARCHAR2
);

Parámetros

parámetro Descripción

profile_name

Nombre del perfil de AI.

Este parámetro es obligatorio.

Ejemplo

BEGIN
     DBMS_CLOUD_AI.DISABLE_PROFILE(
         profile_name    => 'OPENAI'
     );
END;
/

Función GET_PROFILE

Esta función devuelve el nombre de perfil de AI definido en la sesión actual.

Sintaxis

DBMS_CLOUD_AI.GET_PROFILE(
    profile_name      IN  VARCHAR2
);

Parámetros

parámetro Descripción

profile_name

Un nombre para el perfil de AI en la sesión actual.

Este parámetro es obligatorio.

Ejemplo

En este ejemplo, se muestra cómo puede mostrar el nombre del perfil en la sesión actual.


   SELECT DBMS_CLOUD_AI.GET_PROFILE
   from DUAL;

Procedimiento GET_PROFILE

Este procedimiento devuelve el nombre del perfil AI y el propietario establecido en la sesión actual.

Sintaxis

DBMS_CLOUD_AI.GET_PROFILE(                                                      
      profile_name  OUT  VARCHAR2,                                          
      profile_owner OUT  VARCHAR2                                           
);

Parámetros

parámetro Descripción

profile_name

Un nombre para el perfil de AI en la sesión actual.

Este parámetro es obligatorio.

profile_owner Identifica al propietario del perfil AI en la sesión actual.

Ejemplo

En este ejemplo se muestra cómo puede mostrar el nombre y el propietario del perfil en la sesión actual.

DECLARE                                                              
       l_profile_name  DBMS_ID;                                           
       l_profile_owner DBMS_ID;                                           
     BEGIN                                                                
       DBMS_CLOUD_AI.GET_PROFILE(profile_name => l_profile_name,          
                                 profile_owner => l_profile_owner);       
     END;

Procedimiento SET_ATTRIBUTE

Este procedimiento le permite definir atributos de perfil de AI.

Sintaxis

DBMS_CLOUD_AI.SET_ATTRIBUTE(
      profile_name         IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);

Parámetros

Solo el propietario puede definir o modificar los atributos del perfil AI. Para ver una lista de atributos admitidos, consulte Profile Attributes.

parámetro Descripción

profile_name

Nombre del perfil de AI para el que desea definir los atributos.

Este parámetro es obligatorio.

attribute_name

Nombre del atributo de perfil de AI

Este parámetro es obligatorio.

attribute_value

Valor del atributo del perfil.

El valor por defecto es NULL.

Ejemplo

BEGIN
 DBMS_CLOUD_AI.SET_ATTRIBUTE(
   profile_name    => 'OPENAI',
   attribute_name  => 'credential_name',
   attribute_value => 'OPENAI_CRED_NEW'
 );
END;
/

Procedimiento SET_PROFILE

Este procedimiento establece el perfil de AI para la sesión actual.

Después de definir un perfil de AI para la sesión de base de datos, cualquier sentencia SQL con el prefijo SELECT AI se considera una petición de datos de lenguaje natural. Según la acción especificada con el prefijo AI, se genera una respuesta mediante AI. Para utilizar el prefijo AI, consulte Examples of Using Select AI. Opcionalmente, puede sustituir los atributos de perfil o modificar los atributos especificándolos en formato JSON. Consulte Procedimiento SET_ATTRIBUTE para definir los atributos.

El perfil AI solo se puede configurar para la sesión actual si el propietario del perfil AI es el usuario de la sesión.

Para definir un perfil de AI para todas las sesiones de un usuario de base de datos específico o todas las sesiones de usuario de la base de datos, considere el uso de un disparador de evento de base de datos para el evento AFTER LOGON en el usuario específico o en toda la base de datos. Consulte Sentencia CREATE TRIGGER para obtener más información.

Sintaxis

DBMS_CLOUD_AI.SET_PROFILE(
    profile_name      IN  VARCHAR2,
);

Parámetros

parámetro Descripción

profile_name

Un nombre para el perfil de AI en la sesión actual.

Este parámetro es obligatorio.

Ejemplo


   BEGIN
        DBMS_CLOUD_AI.SET_PROFILE(
          profile_name    => 'OPENAI'
        );
   END;
   /

GENERAR Función

Esta función proporciona una traducción de AI sin estado. Con su perfil de AI existente, puede utilizar esta función para realizar las acciones admitidas, como showsql, narrate o chat. La acción por defecto es showsql.

También es posible sustituir algunos o todos los atributos de perfil mediante esta función.

Sintaxis

DBMS_CLOUD_AI.GENERATE(
    prompt          IN  CLOB,
    profile_name    IN  VARCHAR2 DEFAULT NULL,
    action          IN  VARCHAR2 DEFAULT NULL,
    attributes      IN  CLOB     DEFAULT NULL
) RETURN CLOB;

Parámetros

parámetro Descripción

prompt

Lenguaje natural para traducir con IA.

La petición de datos puede incluir SELECT AI <action> como prefijo. La acción también se puede proporcionar por separado como un parámetro de "acción". El valor action proporcionado en la petición de datos sustituye el parámetro "action". La acción por defecto es showsql.

Este parámetro es obligatorio.

profile_name

Nombre del perfil de AI. Este parámetro es opcional si ya hay un perfil de AI configurado en la sesión mediante DBMS_CLOUD_AI.SET_PROFILE.

El valor por defecto es NULL.

Se aplican las siguientes condiciones:
  • Si se establece un perfil en la sesión actual, el usuario puede omitir el argumento profile_name en la función DBMS_CLOUD_AI.GENERATE.
  • Si el argumento profile_name se proporciona en la función DBMS_CLOUD_AI.GENERATE, sustituye cualquier valor definido en la sesión mediante el procedimiento DBMS_CLOUD_AI.SET_PROFILE.
  • Si no hay ningún perfil definido en la sesión mediante el procedimiento DBMS_CLOUD_AI.SET_PROFILE, el argumento profile_name se debe proporcionar en la función DBMS_CLOUD_AI.GENERATE.
Nota

Para Database Actions, puede especificar el argumento profile_name en DBMS_CLOUD_AI.GENERATE o puede ejecutar dos pasos como script PL/SQL: DBMS_CLOUD_AI.SET_PROFILE y DBMS_CLOUD_AI.GENERATE.
EXEC DBMS_CLOUD_AI.set_profile('OPENAI');

-----------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'showsql')
FROM dual;

------------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'narrate')
FROM dual;
-------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'what is oracle autonomous database',
                              profile_name => 'OPENAI',
                              action       => 'chat')
FROM dual;
Consulte Ejecución de sentencias SQL en el editor de códigos para obtener más información.
action

Acción para traducir la petición de datos natural mediante AI. Las acciones soportadas incluyen showsql (por defecto), narrate y chat. Las descripciones de las acciones se incluyen en Use AI Keyword to Enter Prompts.

Nota

Esta función no soporta la acción runsql. Si proporciona la acción runsql, devuelve el siguiente error:
ORA-20000: runsql action is not supported by generate function ORA-06512: at "C##CLOUD$SERVICE.DBMS_CLOUD", line xxxx 
ORA-06512: at "C##CLOUD$SERVICE.DBMS_CLOUD_AI", line 2696 ORA-06512: at line x
attributes Sustituya atributos de perfil de AI específicos mediante el suministro de atributos en formato JSON. Consulte Atributos de perfil para obtener más información.

Ejemplos

Los siguientes ejemplos ilustran las acciones showsql, narrate y chat que se pueden utilizar con la función DBMS_CLOUD_AI.GENERATE.

Un ejemplo con la acción showsql es el siguiente:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'showsql')
FROM dual;

Un ejemplo con la acción narrate es el siguiente:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'narrate')
FROM dual;

Un ejemplo con la acción chat es el siguiente:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'what is oracle autonomous database',
                              profile_name => 'OPENAI',
                              action       => 'chat')
FROM dual;

Atributos de Perfil

Los atributos de un perfil de AI ayudan a gestionar y configurar el comportamiento del perfil de AI. Algunos atributos son opcionales y tienen un valor por defecto.

Atributos

Nombre de Atributo Descripción
azure_deployment_name

Nombre del modelo desplegado del servicio OpenAI de Azure. El nombre solo puede incluir caracteres alfanuméricos, caracteres de subrayado (_) y guiones (-). El nombre no puede terminar con un guión bajo (_) o un guión (-). Para obtener información sobre cómo obtener azure_deployment_name, consulte Creación y despliegue de un recurso de servicio OpenAI de Azure.

azure_resource_name

Nombre del recurso de servicio OpenAI de Azure. El nombre del recurso solo puede incluir caracteres alfanuméricos y guiones, y no puede empezar ni terminar con un guion. Para obtener información sobre cómo obtener azure_resource_name, consulte Creación y despliegue de un recurso de servicio OpenAI de Azure.

comments

Incluya comentarios de columna en los metadatos utilizados para traducir peticiones de datos en lenguaje natural mediante AI. El tipo de dato BOOLEAN está soportado. Los valores válidos son TRUE o FALSE para una cadena con el tipo de dato VARCHAR2.

Nota

Los valores booleanos no se aplican en el procedimiento DBMS_CLOUD_AI.SET_ATTRIBUTE al definir un único atributo porque el parámetro attribute_value es del tipo de dato CLOB.

conversation

Atributo VARCHAR2 que indica si el historial de conversaciones está activado para un perfil. Solo OpenAI y Azure OpenAI Service soportan el historial de conversaciones. Los valores válidos son true o false. El valor por defecto es false. Los valores no son sensibles a mayúsculas/minúsculas.

credential_name

Nombre de la credencial para acceder a las API del proveedor de AI.

La credencial que utiliza tokens de portador se puede crear mediante el nombre del proveedor como nombre de usuario y el token de portador como contraseña.

También están soportadas las credenciales de secreto de almacén.

También se admite la autenticación de principios, por ejemplo, el principio de servicio de Azure. Para obtener más información sobre cómo configurarlo, consulte Uso de una entidad de servicio de Azure para acceder a los recursos de Azure.

Es un atributo obligatorio. Consulte Procedimiento CREATE_CREDENTIAL.

max_tokens

Indica el número de tokens que se deben predecir por generación. El valor por defecto es 1024. Consulte Tokens de BPE para obtener más información.

model

Nombre del modelo de AI que se utiliza para generar la traducción.

Modelos Soportados:

  • Para OpenAI: gpt-4, gpt-4-0613, gpt-4-32k, gpt-4-32k-0613, gpt-3.5-turbo (valor por defecto), gpt-3.5-turbo-0613, gpt-3.5-turbo-16k, gpt-3.5-turbo-16k-0613
  • Para Cohere: comando (predeterminado), comando-noche (experimental), comando-luz y comando-luz-noche (experimental). Los modelos más pequeños y "ligeros" son más rápidos, mientras que los modelos más grandes tendrán un mejor rendimiento.Los modelos personalizados también se pueden proporcionar con su ID completo.
  • Para OCI Generative AI: cohere.command (valor por defecto). Los modelos preentrenados para OCI Generative AI están soportados por Select AI. Los modelos personalizados también se pueden proporcionar con sus OCID completos.

    Para obtener más información sobre los modelos soportados en OCI Generative AI, consulte Modelos básicos preentrenados en Generative AI.

Nota

Este parámetro no se utiliza para Azure, ya que el modelo se determina al crear el despliegue en el portal Azure OpenAI Service.

object_list

Matriz de objetos JSON que especifica el propietario y los nombres de objeto que son elegibles para la traducción de lenguaje natural a SQL. Para incluir todos los objetos de un usuario determinado, omita el "nombre" y especifique solo la clave "propietario" en el objeto JSON.

Para la traducción del lenguaje natural a SQL, el nombre del objeto, el propietario del objeto, las columnas del objeto y los comentarios se envían al proveedor de AI mediante solicitudes HTTPS. Evite especificar objetos con nombre de objeto confidencial, nombres de columna o comentarios en la lista de objetos.

Los proveedores de AI pueden tener un límite en el tamaño de metadatos permitido en las solicitudes de traducción. Considere limitar la lista de objetos adecuados para las peticiones de datos de lenguaje natural de los usuarios de la aplicación.

Formato:
[
  {"owner": "SH", "name": "SALES",
  {"owner": "TEST_USER"}
]

Las tablas externas creadas mediante la sincronización de OCI Data Catalog o AWS Glue también se pueden utilizar en la lista de objetos. Esto ayuda a gestionar metadatos en catálogos de datos centrales y a utilizar los metadatos directamente para traducir peticiones de datos en lenguaje natural mediante AI.

oci_compartment_id

Especifica el OCID del compartimento al que tiene permiso para acceder al llamar al servicio OCI Generative AI. El ID de compartimento puede contener caracteres alfanuméricos, guiones y puntos.

El valor por defecto es el ID de compartimento de la PDB.

oci_endpoint_id

Este atributo indica el OCID de punto final del cluster de alojamiento de AI dedicado de Oracle. El ID de punto final puede contener caracteres alfanuméricos, guiones y puntos. Para buscar el OCID de punto final, consulte Obtención de detalles de un punto final en IA generativa.

Cuando desee utilizar el cluster de AI dedicado de Oracle, debe proporcionar el OCID de punto final del cluster de alojamiento.

Por defecto, el ID de punto final está vacío y el modelo está bajo demanda en una infraestructura compartida.

oci_runtimetype

Este atributo indica el tipo de tiempo de ejecución del modelo proporcionado. Este atributo es necesario cuando se especifica el atributo model.

Todos los valores permitidos se pueden encontrar en OCI Generative AI runtimeType. Consulte Referencia de LlmInferenceRequest.

El valor por defecto es COHERE, ya que el modelo por defecto para OCI Generative AI es cohere.command. Esta opción se aplica a todas las acciones de Seleccionar AI.

Seleccione LLAMA si utiliza el modelo meta.llama-2-70b-chat. Tenga en cuenta que este modelo es adecuado solo para la acción chat de Seleccionar AI.

provider

Proveedor de AI para el perfil de AI.

Proveedores soportados:

  • openai
  • cohere
  • azul celeste
  • oci

Es un atributo obligatorio.

region

Este atributo indica la ubicación del cluster de AI generativo que desea utilizar. La región puede contener caracteres alfanuméricos y caracteres de guion.
Nota

El cluster de IA generativa de Oracle solo está disponible en la región de Chicago.
La región por defecto es us-chicago-1.

stop_tokens

El texto generado finalizará al principio de la secuencia de parada más temprana. La secuencia se incorporará al texto. El valor de atributo debe ser una matriz válida de valores de cadena en formato JSON. stop_tokens toma una matriz JSON como entrada. Para obtener más información sobre los tokens de parada o las secuencias de parada, consulte la documentación OpenAI o Aquí.

temperature

El muestreo de modelos de generación incorpora aleatoriedad, de modo que la misma petición de datos puede producir diferentes salidas cada vez que se pulsa "generar". La temperatura es un número flotante no negativo que se utiliza para ajustar el grado de aleatoriedad. Las temperaturas más bajas significan menos generaciones aleatorias. Consulte Temperatura para obtener más información. Este parámetro se aplica a todos los proveedores de servicios admitidos.

El siguiente ejemplo utiliza Cohere como proveedor y muestra atributos de perfil personalizados:
BEGIN
  DBMS_CLOUD_AI.CREATE_PROFILE(
     profile_name => 'COHERE',
     attributes =>
      '{"provider": "cohere",
        "credential_name": "COHERE_CRED",
        "object_list": [{"owner": "ADMIN"}],
        "max_tokens":512,
        "stop_tokens": [";"],
        "model": "command-nightly",
        "temperature": 0.5,
        "comments": true
       }');
END;
/

En el siguiente ejemplo se muestran los atributos de perfil personalizados mediante OCI Generative AI:

BEGIN                                                                        
  DBMS_CLOUD_AI.CREATE_PROFILE(                                              
      'GENAI',                                                             
      '{"provider": "oci",                                                                   
        "credential_name": "GENAI_CRED",                                     
        "object_list": [{"owner": "SH", "name": "customers"},                
                        {"owner": "SH", "name": "countries"},                
                        {"owner": "SH", "name": "supplementary_demographics"},
                        {"owner": "SH", "name": "profits"},                  
                        {"owner": "SH", "name": "promotions"},               
                        {"owner": "SH", "name": "products"}],
        "oci_compartment_id": "ocid1.compartment.oc1...",
	"oci_endpoint_id": "ocid1.generativeaiendpoint.oc1.us-chicago-1....",
	"region": "us-chicago-1",
	"model": "cohere.command-light",
	"oci_runtimetype": "COHERE"            
       }');                                                                  
END;                                                                         
/