Seleccionar IA para Java

Select AI for Java es un SDK de Java que proporciona una API nativa de Java para configurar y utilizar Select AI con Oracle Autonomous AI Database. El SDK proporciona capacidades Select AI que incluyen perfiles de IA, credenciales, conversaciones, índices vectoriales, SQL en lenguaje natural, resumen, traducción, comentarios y generación de datos sintéticos a través de clases, interfaces y métodos Java.

El SDK utiliza JDBC para comunicarse con la base de datos y utiliza las API de base de datos subyacentes necesarias para las operaciones Select AI. Soporta conexiones JDBC gestionadas por SDK y conexiones DataSource gestionadas por aplicaciones.

Esta documentación proporciona orientación orientada a tareas para instalar, configurar y utilizar el SDK. Para obtener más información sobre la clase, el método, los parámetros y las excepciones, consulte la sección sobre selección de AI para la referencia de API de Java.

Para constructores, métodos, clases de solicitud y respuesta, atributos, parámetros, ejemplos y excepciones soportados, consulte Select AI for Java API Reference (Javadoc).

Entornos soportados

La selección de AI para Java se ha validado con:

• Oracle Autonomous AI Database 26ai
• Oracle Autonomous AI Database 19c

Nota

Nota: DBMS_CLOUD_AI_AGENT está fuera del ámbito de Select AI for Java versión 1.0.0.

El SDK utiliza el controlador JDBC Thin de Oracle para la conectividad de la base de datos. Puede utilizar el SDK con despliegues de base de datos Oracle soportados que proporcionan los privilegios y paquetes de base de datos Select AI necesarios. Confirme la configuración del proveedor de AI de las versiones de controlador JDBC y base de datos soportadas y los privilegios necesarios antes de desplegar una aplicación. Consulte Matriz de capacidades de Oracle AI Database Select AI para conocer las capacidades admitidas junto con sus versiones de base de datos.

Descarga del SDK

Seleccione AI para Java, la versión 1.0.0 se publica en Maven Central.

Para las aplicaciones Maven y Gradle, declare el SDK como una dependencia. Maven o Gradle resuelven el SDK y sus dependencias de tiempo de ejecución desde Maven Central.

Utilice la página de artefacto central de Maven para descargar: Seleccionar AI para Java 1.0.0 en Maven Central

Para obtener descripciones, clases, métodos, parámetros e información de uso de la API, consulte Select AI for Java API Reference (Javadoc).

Agregar AI Select para Java a la aplicación

Select AI for Java está empaquetado como un JAR de Java estándar. El SDK JAR no incluye sus dependencias de tiempo de ejecución de terceros. Maven o Gradle resuelven esas dependencias desde el POM publicado.

Seleccione AI para Java versión 1.0.0 necesita JDK 17 o posterior.

Utilice la dependencia de Maven publicada para el desarrollo normal de aplicaciones. Consulte Descarga del SDK para obtener más información.

Adición del SDK a una aplicación de Maven

Agregue la siguiente dependencia a pom.xml de la aplicación:

<dependency>
    <groupId>com.oracle.database.selectai</groupId>
    <artifactId>select-ai</artifactId>
    <version>1.0.0</version>
</dependency>

Maven resuelve el SDK y sus dependencias de tiempo de ejecución transitivas desde el POM publicado.

Adición del SDK a una aplicación Gradle

Para las aplicaciones Gradle que utilizan el DSL de Groovy, agregue la siguiente configuración al archivo build.gradle: por ejemplo:

repositories {
    mavenLocal()
}

dependencies {
    implementation 'com.oracle.database.selectai:select-ai:1.0.0'
}

Nota

Nota: la configuración de Gradle utiliza el artefacto central de Maven. No indica una distribución de Gradle separada.

Dependencias en tiempo de ejecución

El JAR de SDK no agrupa dependencias de terceros. Cuando se utiliza el SDK como dependencia de Maven o Gradle, la herramienta de gestión de dependencias resuelve las dependencias directas y transitivas necesarias desde el POM publicado.

El SDK utiliza estas dependencias de tiempo de ejecución principales:

El SDK depende de la API de SLF4J pero no incluye un proveedor de registro de SLF4J. Configure un proveedor de registro de SLF4J 2.x adecuado para la aplicación. Los ejemplos de SDK independientes utilizan slf4j-simple.

Si utiliza el JAR de SDK directamente en lugar de un sistema de gestión de dependencias, también debe hacer que sus dependencias de tiempo de ejecución estén disponibles en la classpath de la aplicación. Utilice las dependencias resueltas desde el SDK pom.xml para asegurarse de que incluye las dependencias directas y transitivas necesarias.

Para copiar dependencias de tiempo de ejecución para el uso directo de JAR, ejecute:

mvn clean install
mvn -DincludeScope=runtime \
    -DoutputDirectory=target/dependency \
    dependency:copy-dependencies

Utilice el SDK JAR y las dependencias copiadas en la classpath de la aplicación:

java -cp "target/select-ai-1.0.0.jar:target/dependency/*" \
    com.example.Application

En Windows PowerShell, utilice un punto y coma (;) en lugar de dos puntos (:) en la classpath:

java -cp "target/select-ai-1.0.0.jar;target/dependency/*" `
    com.example.Application

Conexión a Autonomous AI Database

Seleccione AI para Java que utilice conexiones JDBC para comunicarse con Autonomous AI Database. Puede proporcionar información de conexión directamente o proporcionar un JDBC DataSource.

Gestionar conexiones JDBC

Seleccione un enfoque de gestión de conexiones antes de crear objetos Select AI. Utilice un enfoque consistente en toda una aplicación o documente claramente la propiedad cuando varios componentes compartan los mismos recursos de base de datos.

El SDK soporta estos modos de conexión:

• DbConnectionConfig: configuración de conexión que el SDK utiliza para obtener y gestionar conexiones JDBC.
• DataSource: DataSource proporcionado por la aplicación.

DbConnection es una API de propietario de conexión independiente independiente.

Cuando la aplicación proporcione una conexión, asegúrese de que la conexión esté abierta y configurada para el usuario de base de datos deseado. Cuando el SDK obtenga conexiones de una configuración o DataSource, siga las reglas de ciclo de vida documentadas en Seleccionar AI para referencia de API de Java (Javadoc).

Seleccione el modo que coincida con el modelo de gestión de conexiones que utiliza la aplicación. Las aplicaciones que ya utilizan un pool de conexiones pueden proporcionar su DataSource. Las aplicaciones que gestionan las propiedades de conexión directamente pueden utilizar la configuración de conexión SDK.

Configuración de conexión de base de datos

Utilice DbConnectionConfig para definir las propiedades de conexión a la base de datos y las opciones relacionadas con la conexión. En el modo DbConnectionConfig, el SDK crea y posee una única conexión JDBC para el cliente SelectAI. El SDK reutiliza esta conexión para las operaciones realizadas por ese cliente. El SDK cierra la conexión JDBC al llamar a SelectAI.close(). Puesto que el cliente utiliza una conexión JDBC retenida, trate un cliente SelectAI basado en DbConnectionConfig como de thread único, a menos que la aplicación sincronice el acceso de forma externa.

Utilice DbConnectionConfig para aplicaciones simples, programas de línea de comandos, ejemplos y aplicaciones que utilizan una conexión de base de datos para un cliente SelectAI. La configuración puede incluir la URL de la base de datos, la información de autenticación, los valores de seguridad o cartera y los valores de tiempo de ejecución opcionales.

Mantener la información y los secretos de conexión fuera del código fuente de la aplicación. Utilice las funciones de credenciales y gestión de secretos recomendadas para su despliegue.

Para obtener una lista completa de las propiedades, constructores, reglas de validación y opciones de autenticación admitidas, consulte Select AI for Java API Reference (Javadoc).

Origen de Datos

Utilice DataSource cuando la aplicación o el servidor de aplicaciones sean propietarios de la creación y el pool de conexiones. En el modo DataSource, la aplicación posee DataSource. El SDK toma prestada una conexión JDBC de DataSource para cada operación y cierra la conexión prestada una vez finalizada la operación. Cuando DataSource utiliza un pool de conexiones, el cierre de la conexión prestada normalmente la devuelve al pool. Al llamar a SelectAI.close(), no se cierra el DataSource propiedad de la aplicación.

Utilice el modo DataSource para servidores de aplicaciones, aplicaciones de Spring o Jakarta, servicios multithread y aplicaciones que gestionan pools de conexiones JDBC. Un DataSource puede integrar Select AI for Java con la infraestructura JDBC existente y los pools de conexiones empresariales.

La aplicación sigue siendo responsable de configurar DataSource, la capacidad del pool, la validación y la seguridad. El SDK utiliza el DataSource proporcionado por la aplicación para las operaciones de base de datos.

Ciclo de vida de conexión

Cierre las conexiones y otros recursos JDBC según el modelo de propiedad utilizado por la aplicación. Libere recursos cuando finalice una operación y no retenga conexiones de corta duración más tiempo del necesario.

Cuando una aplicación utiliza un pool de conexiones, devuelva las conexiones al pool en lugar de cerrar el recurso gestionado por el pool directamente.

El SDK gestiona el ciclo de vida de la conexión JDBC según el modo de conexión seleccionado:

Los objetos de recursos, como Profile, Conversation y VectorIndex, utilizan el ciclo de vida de conexión de su cliente SelectAI asociado. No crean ni poseen una conexión JDBC independiente.

Comportamiento de thread

Seleccione AI para Java soporta diferentes comportamientos de thread según el modo de conexión y cómo las aplicaciones utilizan los objetos de recursos SDK. El SDK no ofrece una garantía global de seguridad de threads para todos los objetos públicos.

Para el modo DataSource, puede compartir un cliente SelectAI entre threads para operaciones independientes porque cada operación obtiene su propia conexión JDBC.

Para el modo DbConnectionConfig, trate el cliente SelectAI como de thread único, a menos que la aplicación sincronice el acceso a la conexión JDBC retenida.

Atención: varios threads pueden utilizar instancias de recursos independientes para operaciones independientes. Si varios threads utilizan la misma instancia de recurso, no modifique ese recurso simultáneamente a menos que la aplicación sincronice el acceso. Por ejemplo, no utilice varios threads al mismo tiempo para modificar los mismos recursos, como la instancia Profile, Credential, Conversation o VectorIndex. No cree, actualice, active, desactive ni borre simultáneamente el mismo recurso. Si la aplicación necesita acceso simultáneo a la misma instancia de recurso, sincronice el acceso en la aplicación.

Comportamiento de la transacción

La selección de AI para Java utiliza el comportamiento de transacción JDBC. El comportamiento de la transacción depende de la configuración de la conexión y de las API de Oracle AI Database que utilice el SDK. Configure los límites de transacción y confirmación automática según los requisitos de la aplicación y la operación de la base de datos. La selección de AI para Java no confirma ni realiza un rollback explícito de las transacciones y no cambia la configuración autoCommit de la conexión JDBC.

En el modo DbConnectionConfig, el SDK reutiliza su conexión JDBC propiedad del SDK entre operaciones. Si autoCommit está desactivado, las operaciones de SDK y las sentencias JDBC personalizadas que utilizan la misma conexión participan en la transacción de la conexión según la semántica de transacciones de JDBC y Oracle AI Database.

En el modo DataSource, el SDK toma prestada una conexión JDBC para cada operación y cierra la conexión una vez finalizada la operación. El SDK no cambia explícitamente la configuración autoCommit de la conexión, ni confirma ni realiza un rollback de la transacción antes de devolver la conexión. El pool de conexiones o DataSource controla cómo se manejan el estado de conexión y las transacciones pendientes cuando se devuelve una conexión prestada al pool.

Nota

Nota: en el modo DataSource, cada operación de SDK toma prestada una conexión desde DataSource. Por lo tanto, no confíe en que los cambios sin confirmar de una operación de SDK estén disponibles para otra operación.

Las operaciones de SDK que crean o modifican operaciones de perfil, credencial, conversación e índice vectorial utilizan el comportamiento de transacción de la conexión JDBC y la API subyacente de Oracle AI Database. Algunas API de base de datos subyacentes pueden realizar una confirmación o un rollback implícitos. El SDK no cambia ni sustituye el comportamiento de esa base de datos.

Nota

Nota: en el modo DbConnectionConfig, SelectAI.getConnection() devuelve la conexión JDBC propiedad del SDK que el SDK utiliza para sus operaciones. Puede utilizar esta conexión para el trabajo de JDBC personalizado en la misma sesión de base de datos. El hecho de que las operaciones SDK y las sentencias JDBC personalizadas puedan formar una única transacción atómica depende del comportamiento de la transacción de las API de Oracle AI Database subyacentes.

Timeout de Consulta

La opción query-timeout configura el timeout de la sentencia JDBC. Utilice SelectAIOptions.queryTimeoutSeconds() para configurar el timeout de consulta de sentencia JDBC para operaciones de SDK. Por defecto, el SDK no configura un timeout de consulta JDBC. Un valor no definido o nulo significa que el SDK no llama a Statement.setQueryTimeout(). Un valor de 0 utiliza el comportamiento sin timeout de JDBC. El SDK rechaza los valores negativos.

El timeout configurado se aplica a las sentencias JDBC creadas para operaciones SDK. Controla el timeout de la sentencia JDBC o de la base de datos; no configura:

• Timeout de solicitud de proveedor de IA
• Timeout de lectura o conexión HTTP
• cancelación de una solicitud de modelo remoto
• un timeout independiente para una operación DBMS_CLOUD_AI de larga ejecución

Si una operación de base de datos ya ha enviado una solicitud a un proveedor de AI, un timeout de sentencia JDBC no garantiza la cancelación de la solicitud del proveedor. Si el controlador JDBC interrumpe la llamada a la base de datos y cuándo depende del comportamiento de la base de datos y JDBC de Oracle.

Para obtener más información sobre SelectAIOptions, la gestión de conexiones y las operaciones de recursos, consulte Seleccionar AI para Java API Reference (Javadoc).

Antes de empezar

Antes de utilizar Select AI for Java:

1. Confirme que la versión de la base de datos está soportada.
2. Obtenga la información de conexión a la base de datos y la autenticación que necesita la aplicación.
3. Configure el proveedor de AI y las credenciales de base de datos necesarias.
4. Cree o identifique un perfil de IA para el flujo de trabajo deseado.
5. Confirme que el usuario de la base de datos tiene los privilegios y el acceso de red necesarios para las funciones seleccionadas.
6. Revise Realizar requisitos previos para Select AI para conocer los requisitos de configuración.

Gestión de Privilegios de Base de Datos y Acceso de Red

Select AI for Java proporciona la interfaz DatabaseAdmin para operaciones de configuración de bases de datos con privilegios. Utilice la interfaz SelectAI para las operaciones normales de la aplicación.

Utilice DatabaseAdmin solo en un flujo de trabajo de administración o aprovisionamiento controlado por separado. No exponga DatabaseAdmin a los usuarios normales de la aplicación ni lo incluya en la ruta de tiempo de ejecución general de la aplicación.

La interfaz DatabaseAdmin proporciona métodos administrativos para:

• Otorgue o revoque los privilegios del paquete Select AI para los usuarios de base de datos.
• Otorgue o revoque el acceso HTTP a hosts externos.
• Otorgue o revoque el acceso de red para hosts, privilegios y rangos de puertos opcionales especificados.
• Active o desactive Seleccionar acceso a datos de AI.

Estas operaciones requieren un usuario de base de datos administrativa con privilegios adecuados. El usuario de la base de datos que ejecuta la aplicación no necesita privilegios de DatabaseAdmin a menos que ese usuario también realice la configuración administrativa.

Privilegios de paquete

Utilice los métodos de privilegio de paquete DatabaseAdmin para otorgar o revocar los privilegios de paquete de base de datos que necesitan los usuarios de Select AI.

Para utilizar Select AI, un administrador de base de datos otorga EXECUTE en DBMS_CLOUD_AI al usuario de base de datos. Las capacidades de selección de AI pueden requerir privilegios de paquete adicionales. Por ejemplo, la generación con recuperación aumentada (RAG) requiere acceso a DBMS_CLOUD_PIPELINE.

Las operaciones de credenciales utilizan DBMS_CLOUD y necesitan que el usuario de la base de datos que gestiona las credenciales tenga acceso a las API DBMS_CLOUD correspondientes.

El paquete otorga privilegios de cambio para los usuarios de la base de datos especificados en la solicitud administrativa. Realice estos permisos durante el aprovisionamiento de la base de datos o la aplicación en lugar de durante el inicio normal de la aplicación.

Nota

Nota: DBMS_CLOUD_AI_AGENT está fuera del ámbito de Select AI for Java versión 1.0.0.

Para obtener los privilegios necesarios, consulte Perform Prerequisites for Select AI.

Acceso de red

Utilice los métodos de acceso de red DatabaseAdmin solo cuando un administrador de base de datos necesite configurar el acceso de salida para los usuarios de Select AI.

La API proporciona:

• Métodos de acceso HTTP para otorgar o revocar el acceso HTTP a un host especificado.
• Métodos generales de acceso de red para otorgar o revocar privilegios de red especificados para un host y, opcionalmente, un rango de puertos TCP.

La configuración de ACL de red no es necesaria para cada proveedor de AI seleccionado o despliegue de base de datos. Configure el acceso de red solo cuando el proveedor seleccionado y el despliegue lo requieran. Por ejemplo, Select AI no requiere una ACL de red para OCI Generative AI.

Los cambios de la ACL de red modifican la configuración de la ACL de red de la base de datos. La configuración de ACL reside en la base de datos en lugar de en la aplicación Java o el esquema del usuario de destino. Una entrada de control de acceso identifica el usuario o rol de la base de datos que recibe acceso, por lo tanto, la configuración de una ACL no otorga automáticamente acceso de red a cada usuario de la base de datos.

Especifique solo los hosts que necesita la aplicación. Un host puede identificar un nombre de host, una dirección IP, un dominio o un comodín admitido. Cuando corresponda, utilice los parámetros de puerto inferior y superior para restringir el acceso al rango de puertos TCP necesario. Si no especifica un rango de puertos, las reglas de ACL de red subyacentes determinan el acceso sin una restricción de puerto.

Los cambios de ACL de red siguen formando parte de la configuración de la base de datos hasta que un administrador los cambia o los elimina. No son valores temporales asociados al proceso de SDK de Java o a la sesión de JDBC.

Atención: los cambios en la ACL de red afectan a la configuración de seguridad de la base de datos. Configure el acceso a la red como parte de un flujo de trabajo de administración o aprovisionamiento controlado. No otorgue privilegios de gestión de red DatabaseAdmin al tiempo de ejecución normal de la aplicación.

Para conocer los puntos finales y los requisitos de red del proveedor, consulte Perform Prerequisites for Select AI.

Seleccionar acceso a datos de IA

Utilice DatabaseAdmin.enableDataAccess() y DatabaseAdmin.disableDataAccess() para controlar si las funciones de Select AI aplicables pueden enviar datos de base de datos o contenido de documentos de búsqueda vectorial a un modelo de lenguaje grande.

Esta configuración se aplica a las capacidades de selección de IA que requieren acceso a datos, incluida la acción de narración, la generación con recuperación aumentada (RAG) y la generación de datos sintéticos.

Solo un administrador puede cambiar la configuración de acceso a datos de Select AI. Los procedimientos DBMS_CLOUD_AI.ENABLE_DATA_ACCESS y DBMS_CLOUD_AI.DISABLE_DATA_ACCESS subyacentes no aceptan un parámetro de esquema o usuario de base de datos.

Tratar los cambios para seleccionar acceso a datos de IA como configuración de base de datos administrativa. Configure el valor necesario durante el aprovisionamiento o mediante un cambio administrativo explícitamente autorizado, en lugar de durante el inicio normal de la aplicación.

Atención: la desactivación del acceso de datos de selección de IA puede limitar las funciones de selección de IA que necesitan enviar datos de base de datos o contenido de documento recuperado al proveedor de IA. Revise las capacidades de selección de IA afectadas antes de cambiar esta configuración.

Operaciones administrativas y de tiempo de ejecución

Oracle recomienda mantener la configuración administrativa separada del procesamiento normal de la aplicación.

Utilice un usuario de base de datos con el mínimo de privilegios para el tiempo de ejecución normal de la aplicación. No otorgue privilegios administrativos a un usuario de aplicación únicamente para que la aplicación pueda configurar sus propios requisitos en el inicio.

Para conocer los privilegios, las credenciales, la configuración del proveedor y los requisitos de red de Select AI necesarios, consulte Perform Prerequisites for Select AI.

Para conocer los métodos, parámetros y excepciones DatabaseAdmin, consulte Select AI for Java API Reference (Javadoc)

Acciones que Puede Realizar

El SDK de Select AI for Java proporciona una API de Java para trabajar con recursos de Select AI.

En la siguiente tabla se resumen las capacidades principales de Select AI for Java:

Para obtener más información sobre la API de Java, consulte Seleccionar AI para Java API Reference (Javadoc).

Clases Soportadas

Select AI for Java proporciona interfaces públicas y clases de modelos para operaciones de aplicaciones, configuración administrativa, gestión de conexiones y configuración de recursos Select AI.

El código de aplicación debe utilizar las interfaces públicas en com.oracle.database.selectai y los tipos de modelo relacionados en com.oracle.database.selectai.model. Las clases de com.oracle.database.selectai.impl son clases de implantación internas y no están destinadas al uso directo de la aplicación.

Clases de aplicación principal

Utilice estas clases para flujos de trabajo comunes de la aplicación Select AI.

Clases Administrativas

Utilice la interfaz DatabaseAdmin independientemente del procesamiento normal de la aplicación.

Utilice DatabaseAdmin solo en un flujo de trabajo de administración o aprovisionamiento controlado por separado. Para obtener más información, consulte Gestión de privilegios de base de datos y acceso de red.

Modelos de configuración y solicitud

Utilice las siguientes clases de modelo para configurar los recursos y las operaciones de SDK.

API de conexión y puntos de extensión

El SDK proporciona interfaces de conexión pública y puntos de extensión para aplicaciones que requieren acceso directo a la conexión JDBC o manejo de conexiones personalizadas.

Para la mayoría de las aplicaciones, utilice DbConnectionConfig o un DataSource gestionado por la aplicación con SelectAI. Utilice los puntos de extensión de conexión solo cuando la aplicación necesite un manejo de conexión JDBC personalizado.

Para conocer el comportamiento de propiedad, ciclo de vida, transacción y thread de la conexión, consulte Conexión a Autonomous AI Database.

Clases de proveedor

Seleccione AI para Java representa los proveedores de AI mediante la enumeración Provider y las clases de configuración específicas del proveedor para los proveedores de AI soportados. Utilice la configuración de proveedor adecuada al configurar un perfil AI.

La selección de AI para Java incluye las siguientes clases de configuración de proveedor:

• OpenAIProviderProfile
• CohereProviderProfile
• AzureProviderProfile
• OCIGenAIProviderProfile
• GoogleProviderProfile
• HuggingFaceProviderProfile
• AWSProviderProfile

Utilice la configuración de proveedor adecuada para el proveedor que configure en ProfileAttributes. Para conocer los requisitos previos y los requisitos de configuración del proveedor, consulte Perform Prerequisites for Select AI.

Clases de implantación interna

Las clases del paquete com.oracle.database.selectai.impl implantan las interfaces del SDK público y gestionan las interacciones internas de JDBC y base de datos.

Nota

Nota: Las clases del paquete com.oracle.database.selectai.impl proporcionan las implantaciones internas de las interfaces del SDK público. Estas clases no están soportadas como API orientadas a aplicaciones y pueden cambiar independientemente de la API pública. En su lugar, utilice las interfaces públicas y los métodos de fábrica en com.oracle.database.selectai.

Para obtener información completa sobre las clases públicas, las interfaces, los tipos de modelos, los métodos y los puntos de extensión, consulte Select AI for Java API Reference (Javadoc).

Trabajo con credenciales

Una credencial de base de datos almacena la información de autenticación que utiliza Autonomous AI Database para acceder a un proveedor de AI o a un servicio externo como Object Storage.

Cree la credencial necesaria antes de crear un perfil AI o un índice vectorial que haga referencia a ella. El usuario de la base de datos que crea la credencial la posee y el nombre de la credencial la identifica en el esquema de ese usuario.

Crear y gestionar credenciales

Utilice SelectAI.credential(CredentialConfig) para crear un objeto Credential a partir de la configuración de credenciales. Este método crea sólo un objeto Credential de Java; no crea la credencial en la base de datos. Llame a Credential.create() en el objeto Credential devuelto para crear la credencial de base de datos.

Utilice los siguientes métodos Credential:

• create(): crea la credencial de base de datos.
• drop(): elimina la credencial de base de datos.
• drop(boolean force): elimina la credencial de base de datos y, cuando force es true, trata una credencial que ya está ausente como resultado correcto.

La clase CredentialConfig define los detalles de creación de credenciales, incluido el nombre de la credencial y la información de autenticación soportada.

Propiedad de credencial

El usuario de base de datos que crea la credencial es el propietario de la credencial. El nombre de la credencial identifica la credencial en el esquema de ese usuario.

El SDK no proporciona un método para recuperar los valores secretos almacenados de una credencial. Proteja contraseñas, claves privadas, huellas digitales, OCID y configuraciones de credenciales completas. No incluya secretos en el código fuente, los logs, los informes de error ni las peticiones de datos.

Credenciales de proveedor de AI

Las credenciales de proveedor de AI almacenan la información de autenticación necesaria para acceder al proveedor de AI configurado.

Configure una credencial de proveedor de AI cuando el perfil de AI necesite una credencial de base de datos para la autenticación del proveedor. El perfil hace referencia a la credencial por nombre mediante su configuración de perfil.

Para la autenticación de OCI, CredentialConfig soporta la configuración de credenciales que incluye el nombre de credencial, el OCID de usuario, el OCID de arrendamiento, la clave privada y la huella.

Credenciales de Object Storage

Utilice una credencial de base de datos para autenticar el acceso a Object Storage cuando un índice vectorial utilice el contenido almacenado allí.

El SDK de Select AI para Java no define un tipo de Java independiente para una credencial de Object Storage. Cree la credencial de base de datos mediante métodos en la interfaz Credential. Especifique la credencial para el acceso a Object Storage en la configuración de vector-índice.

VectorIndexAttributes define el atributo de credencial de Object Storage, junto con otros atributos de índice vectorial, como la ubicación de origen.

Varios recursos Select AI pueden hacer referencia a la misma credencial de base de datos cuando necesitan la misma información de autenticación.

Borrado de una credencial

Utilice Credential.drop() o Credential.drop(boolean force) para eliminar una credencial.

El borrado de una credencial no actualiza automáticamente los perfiles AI o los índices vectoriales que hacen referencia a ella. Si un recurso aún hace referencia a la credencial borrada, una operación que requiere la credencial puede fallar.

Atención: antes de borrar una credencial, identifique los perfiles de IA, los índices vectoriales y otros recursos que hacen referencia a ella. Actualice o elimine esas dependencias según sea necesario.

Principales de recursos y principales de instancias de OCI

Algunas configuraciones de autenticación de OCI pueden utilizar principales de recurso o principales de instancia en lugar de credenciales de usuario almacenadas. Cuando el proveedor y el entorno de base de datos seleccionados soportan estos métodos de autenticación, puede utilizar la configuración de autenticación de OCI soportada sin almacenar información de firma de usuario en una credencial de base de datos.

Para conocer los requisitos de autenticación específicos del proveedor, consulte Perform Prerequisites for Select AI.

Para la configuración de credenciales, las propiedades de autenticación soportadas, las operaciones de ciclo de vida y las excepciones, consulte Seleccionar AI para Java API Reference (Javadoc).

Trabajar con perfiles de IA

Un perfil de AI define cómo se comunica Select AI con un proveedor de AI y qué objetos de base de datos e índices vectoriales puede utilizar Select AI. Un perfil puede incluir la configuración de proveedor, modelo, credencial, lista de objetos, conversación, traducción e índice vectorial.

Utilice la interfaz Profile para crear y gestionar perfiles de AI y realizar operaciones Select AI. Todos los métodos de la interfaz Profile son síncronos. El thread de llamada espera a que cada operación finalice o devuelva un error.

Configurar un perfil de AI

Utilice la clase ProfileAttributes para configurar un perfil AI. La configuración del perfil depende del proveedor y de la capacidad Select AI que utilice.

Especifique el proveedor y otros atributos necesarios para ese proveedor. Los atributos específicos del proveedor pueden incluir el modelo, la credencial, el punto final, la región, el compartimento y otros valores del proveedor.

Configure una credencial de base de datos en la que el proveedor seleccionado y el método de autenticación requieran una. Algunos métodos de autenticación soportados no necesitan una credencial de base de datos almacenada.

Utilice las clases de configuración específicas del proveedor en ProviderProfile para definir los valores del proveedor. Para conocer los atributos obligatorios y opcionales de cada proveedor, consulte Perform Prerequisites for Select AI.

Crear un perfil de IA

Utilice SelectAI.profile(String profileName, ProfileAttributes profileAttributes, String description, ProfileStatus status) para crear un objeto Profile de Java inicializado con la configuración de perfil.

Este método no crea el perfil AI en la base de datos. Llame a Profile.create() en el objeto devuelto para crear el perfil de base de datos.

Por ejemplo:

ProfileAttributes attributes =
    ProfileAttributes.builder()
        .provider(Provider.OCI)
        // Add provider-specific attributes.
        .build();

Profile profile =
    selectAI.profile(
        "MY_PROFILE",
        attributes,
        "Select AI profile",
        ProfileStatus.ENABLED);

profile.create();

Los valores ProfileAttributes necesarios dependen del proveedor, el método de autenticación y la funcionalidad de perfil seleccionados. Configure cualquier credencial necesaria antes de crear un perfil que haga referencia a ella.

Para obtener un ejemplo completo de creación de perfiles para su proveedor, consulte Seleccionar AI para Java API Reference (Javadoc).

Uso de un perfil de IA existente

Utilice SelectAI.profile(String profileName) para abrir un perfil de AI existente en el esquema actual. El método devuelve un objeto Profile que puede utilizar para operaciones de perfil.

Por ejemplo:

Profile profile = selectAI.profile("MY_PROFILE");

String sql = profile.showsql("Show the total sales by region");

Utilice la interfaz Profile para:

• Genere y ejecute SQL con runsql().
• Genere SQL sin ejecutarlo con showsql().
• Explicar el SQL generado con explainsql().
• Limite los resultados de la consulta con narrate().
• Chatee con el proveedor de IA configurado con chat().
• Devuelve la petición de datos aumentada con showprompt().
• Utilice la generación con recuperación aumentada (RAG) con índices vectoriales configurados en el perfil AI mediante ProfileAttributes.
• Resuma el contenido con summarize().
• Traduce el contenido con translate().
• Envíe comentarios para el SQL generado con feedback().
• Genere datos sintéticos con generateSyntheticData().

Configuración de Objetos de Base de Datos para NL2SQL

Utilice la configuración de lista de objetos de perfil para controlar qué objetos de base de datos considera Select AI al generar SQL.

La clase ProfileAttributes soporta la configuración de lista de objetos y los valores ObjectListMode AUTOMATED y ALL. La configuración de la lista de objetos del perfil determina los metadatos de la base de datos que Select AI pone a disposición para la generación de SQL en lenguaje natural.

La lista de objetos no otorga privilegios de base de datos. El usuario de la base de datos debe tener los privilegios necesarios en los objetos que utiliza el perfil.

Para conocer la configuración de la lista de objetos y el comportamiento de la selección de objetos, consulte Manage AI Profiles.

Configurar índices vectoriales para RAG

Asocie índices vectoriales a un perfil AI para utilizar la generación con recuperación aumentada (RAG). La clase ProfileAttributes proporciona los valores de índice vectorial que utiliza el perfil.

Cuando se utiliza un perfil activado para RAG, Select AI recupera el contenido relevante del índice vectorial configurado y agrega ese contenido a la petición de datos aumentada enviada al proveedor de AI.

Cree y configure el índice vectorial necesario antes de utilizarlo con el perfil. Para obtener más información, consulte Seleccionar AI con generación aumentada de recuperación (RAG).

Uso de perfiles en interfaces AI seleccionadas

El método Profile.create() crea el perfil AI como recurso de base de datos. El objeto Profile de Java proporciona una representación Java de ese perfil de base de datos.

Puesto que el perfil reside en la base de datos en lugar de en el proceso Java, otras interfaces de Select AI que pueden acceder al mismo perfil de base de datos pueden utilizarlo según sus privilegios de base de datos y la funcionalidad de perfil soportada. Esto incluye interfaces SQL y PL/SQL y otros SDK o API de Select AI soportados.

Resumir y traducir contenido

Utilice el método Profile.summarize() para resumir el contenido en línea o el contenido en una ubicación externa. Para cada solicitud de resumen, especifique el contenido en línea o un URI de ubicación, pero no ambos.

Utilice el método Profile.translate() para traducir texto con un proveedor de traducción soportado configurado en el perfil. Se aplican los requisitos de autenticación, soporte de idioma y servicio específicos del proveedor.

Para obtener más información, consulte Generar un resumen con Select AI y Traducir.

Proporcionar comentarios SQL

Utilice el método Profile.feedback() para enviar comentarios positivos o negativos para la generación de NL2SQL.

Los comentarios positivos confirman el SQL generado para referencia futura. Los comentarios negativos pueden identificar problemas con el SQL generado y proporcionar el SQL esperado o orientación adicional. Seleccionar AI puede utilizar comentarios almacenados relevantes como indicaciones para peticiones de datos similares durante la siguiente generación de SQL.

Para obtener más información, consulte Comentarios.

Para obtener información completa sobre la interfaz Profile, la clase ProfileAttributes, la configuración específica del proveedor, los métodos de ciclo de vida del perfil, los métodos de generación y los ejemplos, consulte Seleccionar AI para Java API Reference (Javadoc).

Trabajo con Conversaciones

Un objeto Conversation representa una conversación Seleccionar AI almacenada en la base de datos. Utilice una conversación para retener el contexto y el historial de peticiones de datos en las interacciones relacionadas con Select AI.

Una conversación es un recurso de base de datos identificado por un ID de conversación. No está asociado permanentemente a un perfil de AI. Las aplicaciones pueden utilizar el identificador de conversación con operaciones Select AI que soportan el contexto conversacional, según la configuración del perfil y los privilegios de la base de datos de la aplicación.

Creación de una conversación

Utilice SelectAI.conversation(ConversationAttributes) para crear un objeto Conversation de Java inicializado con atributos de conversación.

Este método no crea la conversación en la base de datos. Llame a Conversation.create() en el objeto devuelto para crear la conversación de la base de datos. El método create() devuelve el identificador de conversación generado.

Atributos de conversación

Utilice ConversationAttributes para configurar los metadatos de conversación, incluidos:

• título
• descripción
• días de retención
• duración de conversación

El atributo retentionDays especifica cuánto tiempo conserva la conversación Select AI. El atributo conversationLength especifica la cantidad de contexto de conversación que conserva Select AI para interacciones relacionadas.

Utilice Conversation.getConversationAttributes() para recuperar los atributos actuales de una conversación existente. Utilice Conversation.setAttributes() para actualizar los atributos de conversación soportados.

Seleccione AI para almacenar el historial de mensajes de conversación en la base de datos. Utilice Conversation.listPrompts() para recuperar peticiones de datos registradas para la conversación, ordenadas por hora de creación. Utilice Conversation.deletePrompt() para eliminar una petición de datos individual. La eliminación de un campo individual con deletePrompt() no elimina la conversación. Utilice Conversation.drop() para eliminar la conversación de la base de datos.

Conservar el identificador de conversación cuando las operaciones posteriores de la aplicación necesiten acceder a la misma conversación.

Uso de una conversación existente

Utilice SelectAI.conversation(String conversationId) para abrir una conversación existente por su identificador de conversación.

Después de abrir o crear una conversación, utilice la interfaz Conversation para:

• Recupere el identificador de conversación con getConversationId().
• Recupere los atributos de conversación con getConversationAttributes().
• Actualice los atributos de conversación con setAttributes().
• Mostrar peticiones de datos almacenadas para la conversación con listPrompts().
• Suprimir una petición de datos individual con deletePrompt().
• Elimine la conversación con drop().

Ciclo de vida de las conversaciones

Un objeto Conversation de Java no elimina automáticamente la conversación de base de datos correspondiente cuando el objeto Java se sale del ámbito o cuando se cierra el cliente SelectAI.

Gestione el ciclo de vida de las conversaciones de la base de datos de forma explícita. Llame a Conversation.drop() cuando la aplicación ya no necesite la conversación.

Nota

Nota: la opción Select AI for Java SDK actual no define un ciclo de vida de sesión pública independiente que suprima automáticamente una conversación cuando se cierre la sesión. Gestione conversaciones a través de la interfaz Conversation y el identificador de conversación.

Comportamiento de thread para conversaciones

El SDK no proporciona una garantía de seguridad de thread global para los objetos Conversation.

Varios threads pueden utilizar instancias Conversation independientes para operaciones independientes. No utilice varios threads al mismo tiempo para actualizar, suprimir peticiones de datos o borrar la misma instancia Conversation a menos que la aplicación sincronice el acceso.

Para conocer el comportamiento general del thread del SDK y las consideraciones del modo de conexión, consulte Comportamiento del thread.

Directrices para conversaciones

Tratar identificadores de conversación y contenido de conversación como datos de aplicación. Una conversación puede contener peticiones de datos y metadatos derivados de interacciones de base de datos o información de negocio confidencial.

No incluya identificadores de conversación, campos o contenido de conversación en registros, informes de error u otra salida a menos que las políticas de seguridad y registro de la aplicación lo permitan. Restrinja el acceso a la base de datos a las conversaciones según los requisitos de control de acceso de la aplicación.

Para obtener información completa sobre la interfaz Conversation, la clase ConversationAttributes, los métodos de ciclo de vida de conversación, los metadatos de petición de datos y ejemplos, consulte Seleccionar AI para referencia de API de Java (Javadoc).

Trabajo con índices vectoriales

Los índices vectoriales soportan flujos de trabajo de generación con recuperación aumentada (RAG). Un índice vectorial almacena representaciones de búsqueda del contenido de origen para que Select AI pueda recuperar información relevante para una respuesta de AI.

Utilice la interfaz VectorIndex para crear, recuperar, actualizar, activar, desactivar y eliminar índices vectoriales. Configure el índice vectorial con la ubicación de origen, la credencial, la configuración de embebido y otros atributos necesarios para el flujo de trabajo de RAG deseado.

Uso de Índices Vectoriales con RAG

Después de crear un índice vectorial, configure un perfil AI para utilizar el índice para RAG.

El índice vectorial proporciona el contenido de origen recuperado. El perfil activado para RAG proporciona el proveedor de IA y la configuración del modelo utilizados para procesar la petición de datos del usuario y el contenido recuperado.

Puede utilizar el mismo índice vectorial con varios perfiles cuando esos perfiles admiten la configuración de RAG necesaria.

Crear un índice vectorial

Utilice SelectAI.vectorIndex(VectorIndexConfig) para crear un objeto VectorIndex de Java a partir de una configuración de índice vectorial. Este método crea el objeto Java; no crea el índice vectorial en la base de datos.

Llame a VectorIndex.create() para crear el índice vectorial en la base de datos.

Cuando el SDK crea un índice vectorial, la base de datos:

1. Lee el contenido desde la ubicación de origen configurada.
2. Utiliza el perfil y el proveedor configurados para el índice vectorial para generar incrustaciones.
3. Almacena los vectores generados para la recuperación durante las operaciones de RAG.

La clase VectorIndexConfig proporciona la configuración de tiempo de creación, incluido el nombre de índice vectorial, el nombre de perfil, el estado, la descripción, el valor de espera para finalización y los atributos de índice vectorial.

Inserción y perfiles RAG

El perfil especificado en la configuración de índice vectorial proporciona el proveedor y la configuración de incrustación que utiliza la base de datos para crear incrustaciones para el contenido de origen.

El perfil utilizado para crear incrustaciones no determina automáticamente qué perfil utiliza una aplicación para las solicitudes RAG. Configure un perfil para RAG por separado especificando el índice vectorial en su configuración ProfileAttributes.

El flujo de trabajo de RAG utiliza perfiles de IA en diferentes roles. La siguiente tabla asigna cada recurso del flujo de trabajo al recurso o configuración de Select AI for Java correspondiente.

Cuando el perfil activado para RAG procesa una solicitud, Select AI recupera contenido relevante del índice vectorial y agrega ese contenido a la petición de datos aumentada enviada al proveedor de AI.

Para obtener más información, consulte Seleccionar AI con generación aumentada de recuperación (RAG).

Creación de índice de vectores de monitor

La creación del índice vectorial se puede ejecutar de forma síncrona o asíncrona en función del valor waitForCompletion en VectorIndexConfig.

Utilice VectorIndex.getStatus() para recuperar el estado actual de un índice vectorial respaldado por base de datos. Utilice VectorIndex.getVectorIndexAttributes() para recuperar sus atributos actuales.

Si falla la creación del índice vectorial, VectorIndex.create() informa del fallo de la base de datos o JDBC mediante SelectAIException.

El SDK no proporciona una interfaz de progreso independiente ni un objeto de trabajo asíncrono para la creación del índice vectorial.

Refrescar Índices de Vector

Un índice vectorial puede utilizar un ratio de refrescamiento configurado para controlar cómo procesa el índice los cambios de contenido de origen.

Cuando cambian los documentos de origen, la base de datos actualiza el índice vectorial según el comportamiento de refrescamiento configurado. Configure el ratio de refrescamiento en VectorIndexAttributes.

La aplicación no necesita volver a crear el índice vectorial únicamente porque el contenido de origen cambia cuando el comportamiento de refrescamiento configurado admite las actualizaciones necesarias.

La credencial y la ubicación de origen necesarios deben permanecer disponibles mientras el índice vectorial procesa o refresca su contenido.

Para conocer la configuración y los atributos de refrescamiento soportados, consulte Select AI for Java API Reference (Javadoc).

Actualizar un índice vectorial

Utilice VectorIndex.update(VectorIndexAttributes) o los métodos update() de atributo único para actualizar los atributos de índice vectorial soportados.

Algunos atributos solo se aplican cuando se crea el índice vectorial y no se pueden cambiar posteriormente. La base de datos determina si se puede actualizar un atributo.

Cree la solicitud de actualización solo con los atributos que la base de datos soporta para la modificación. Por ejemplo, chunk_size es un atributo de tiempo de creación y no se puede actualizar después de crear el índice vectorial.

Utilice VectorIndex.getVectorIndexAttributes() para recuperar los atributos actuales de un índice vectorial existente antes de realizar cambios.

Activación o desactivación de un índice vectorial

Utilice los siguientes métodos para controlar si Select AI puede utilizar un índice vectorial para la recuperación de RAG.

La activación o desactivación de un índice vectorial no elimina los datos vectoriales.

Soltar un índice vectorial

Utilice VectorIndex.drop(boolean force) para eliminar el índice vectorial.

Este formulario elimina tanto los metadatos del índice vectorial como los datos del vector de respaldo.

Utilice VectorIndex.drop(boolean includeData, boolean force) cuando necesite controlar si se eliminan los datos del vector de respaldo.

Atención: antes de borrar un índice vectorial, identifique los perfiles o aplicaciones activados para RAG que lo utilicen. Compruebe si se deben conservar los datos vectoriales subyacentes antes de seleccionar la opción de borrado.

Para ver orígenes de ejemplo ejecutables completos, consulte vectorindex.

Para conocer la configuración de la base de datos y los conceptos de RAG, consulte Perform Prerequisites for Select AI y Select AI with Retrieval Augmented Generation (RAG).

Para obtener información sobre los atributos soportados, las opciones de creación, los valores de estado, los métodos de actualización y los métodos de borrado, consulte Seleccionar AI para referencia de API de Java (Javadoc).

Generar datos sintéticos

Seleccione AI para Java puede generar datos sintéticos para un único objeto de base de datos o para varios objetos de base de datos relacionados. Utilice datos sintéticos para pruebas, desarrollo, creación de prototipos y análisis. La generación de datos sintéticos utiliza el proveedor de AI configurado en el objeto Profile asociado.

Utilice Profile.generateSyntheticData(SyntheticDataSingleRequest) para generar datos sintéticos para un objeto de base de datos. Utilice Profile.generateSyntheticData(SyntheticDataBatchRequest) para generar datos sintéticos para varios objetos.

Una solicitud puede especificar:

• Nombre de objeto de base de datos.
• Propietario de objeto.
• Número de filas que se deben generar.
• Orientación del usuario.
• Parámetros de generación admitidos.

Los datos generados se dirigen a los objetos de base de datos especificados en la solicitud. Los métodos Java devuelven un resultado booleano que indica si la operación de la base de datos se ha realizado correctamente; no devuelven las filas generadas al emisor de la llamada.

Requisitos para generar datos sintéticos

Antes de generar datos sintéticos:

• Asegúrese de que los objetos de la base de datos destino existen.
• Otorgue al usuario de la base de datos los privilegios necesarios para acceder a los objetos de destino y modificarlos.
• Configure un perfil de AI para un proveedor que admita la generación de datos sintéticos.
• Active Select AI data access.
• Complete los requisitos de autenticación y configuración específicos del proveedor.

Para conocer los privilegios Select AI y la configuración de la base de datos, consulte Perform Prerequisites for Select AI.

Generar datos para objetos relacionados

Utilice SyntheticDataBatchRequest cuando necesite generar datos para varios objetos de base de datos relacionados.

La solicitud por lotes puede incluir varios objetos y su configuración de generación. Utilice este formulario cuando los datos generados deban reflejar relaciones entre los objetos especificados.

La solicitud admite un número especificado de filas para la generación de datos sintéticos. El límite efectivo puede depender de la funcionalidad, el proveedor y los recursos de la base de datos subyacente.

Si falla una operación de generación de un solo objeto o lote, el SDK informa del fallo de la base de datos o JDBC mediante SelectAIException.

Comportamiento de transacción para la generación de datos sintéticos

La generación de datos sintéticos sigue el comportamiento de la transacción de la conexión JDBC que utiliza el objeto Profile.

El SDK no confirma ni realiza un rollback explícito de la transacción. En el modo DbConnectionConfig, la operación utiliza la conexión JDBC propiedad del SDK. En el modo DataSource, la operación utiliza una conexión prestada de DataSource gestionado por la aplicación.

Para obtener más información sobre el comportamiento de las transacciones, consulte Conexión a Autonomous AI Database.

Para obtener información sobre los parámetros y las excepciones soportados, consulte Select AI for Java API Reference (Javadoc).

Recuperar y actualizar objetos existentes

Seleccione AI para Java que representa perfiles, conversaciones, credenciales e índices vectoriales como objetos Java respaldados por base de datos.

Utilice los métodos de recuperación soportados para obtener información actual sobre los objetos existentes. Según el objeto, la información devuelta puede incluir el nombre, el identificador, la descripción, el estado, los atributos y los metadatos.

Actualice solo los atributos soportados por las API de base de datos Select AI subyacentes. Una actualización no sustituye necesariamente al objeto completo. Recupere el objeto cuando la aplicación necesite el estado actual de la base de datos y confirme que el objeto existe antes de realizar una operación específica del objeto.

La recuperación de recopilación devuelve objetos accesibles para el usuario de la base de datos conectada.

Para ver los métodos de recuperación soportados, las operaciones de actualización, los objetos de solicitud y los valores de devolución, consulte Seleccionar AI para Java API Reference (Javadoc).

Suprimir Objetos

Elimine los perfiles, credenciales, conversaciones e índices vectoriales que la aplicación ya no necesita.

Antes de suprimir un objeto:

• Confirme que el objeto ya no es necesario.
• Compruebe los perfiles dependientes, las credenciales, las conversaciones y los índices vectoriales.
• Confirme que el usuario de la base de datos conectada puede eliminar el objeto.
• Conservar los metadatos o la configuración necesarios fuera de la base de datos.

Algunos métodos de recursos proporcionan una opción de eliminación forzada que trata un objeto que ya está ausente como un resultado correcto. Utilice esa opción solo cuando la aplicación pueda aceptar de forma segura un objeto ausente como estado final.

Para conocer los métodos de eliminación específicos de objetos, el comportamiento de dependencia y las excepciones, consulte Seleccionar AI para Java API Reference (Javadoc).

Uso de API síncronas

Seleccione AI para Java 1.0.0 proporciona solo API de Java síncronas. El SDK no proporciona API asíncronas ni operaciones de perfil de flujo. Utilice las API síncronas cuando la aplicación pueda esperar a que finalice cada operación de base de datos antes de continuar.

Un método síncrono espera a que la operación de la base de datos finalice o devuelva un error antes de que el control vuelva a la aplicación que realiza la llamada. Las operaciones que se comunican con un proveedor de AI o realizan un procesamiento de base de datos de larga ejecución pueden bloquear el thread de llamada durante un período prolongado.

Para aplicaciones multithread, utilice el modo DataSource y cambie el tamaño del pool de conexiones para la simultaneidad y la carga de trabajo esperadas. Para obtener información sobre los timeouts de consultas JDBC, consulte Comportamiento de la transacción.

Nota

Nota: Un timeout de consulta JDBC no configura tiempos de espera de solicitud de proveedor de AI ni garantiza la cancelación de una solicitud de proveedor que ya está en curso.

Para conocer los métodos síncronos disponibles en esta versión, consulte Select AI for Java API Reference (Javadoc).

Manejo de errores

Seleccione AI para los informes de Java detectados localmente errores de validación mediante excepciones e informes de Java estándar de la base de datos, JDBC, DBMS_CLOUD, DBMS_CLOUD_AI y fallos del proveedor mediante SelectAIException.

El SDK valida la información de solicitud que puede comprobar antes del procesamiento de JDBC. La base de datos y el controlador JDBC validan los privilegios de la base de datos, el estado de los recursos, los requisitos de los paquetes, la configuración del proveedor, el acceso a la red y otros requisitos de la base de datos.

Manejar excepciones de SDK

El SDK utiliza las siguientes excepciones para condiciones de error comunes:

SelectAIException hereda de Exception, lo que lo convierte en una excepción comprobada que los emisores de llamadas deben manejar o declarar explícitamente. Los métodos respaldados por la base de datos pública declaran SelectAIException, incluidos los métodos de ciclo de vida y generación de perfiles, las operaciones de conversación, las operaciones de índice vectorial, las operaciones de credenciales, las operaciones DatabaseAdmin y la creación y limpieza de conexiones propiedad del SDK.

Para la declaración de excepción de un método individual, consulte Select AI for Java API Reference (Javadoc).

Validación de Cliente y de Base de Datos

El SDK valida las entradas soportadas antes del procesamiento de JDBC cuando puede determinar la validez de la solicitud de Java.

El SDK detecta condiciones como:

• Nombres de recursos nulos o en blanco.
• Peticiones de datos y acciones nulas o en blanco cuando sea necesario.
• Usuarios, hosts o privilegios no válidos.
• Rangos de puertos no válidos.
• Valores de timeout de consulta negativos.
• Combinaciones de credenciales no válidas.
• Operaciones en recursos que aún no se han creado o abierto.

Estas condiciones normalmente dan como resultado IllegalArgumentException o IllegalStateException antes del procesamiento de JDBC.

La base de datos valida las condiciones que dependen de la configuración de la base de datos, los recursos o los servicios remotos. Estas condiciones incluyen:

• Privilegios de base de datos.
• Existencia y estado de los recursos.
• Requisitos DBMS_CLOUD y DBMS_CLOUD_AI.
• Configuración de Proveedor.
• Validez de credencial.
• Configuración de ACL de red.
• Reglas de lista de objetos.
• Restricciones del índice vectorial.
• Respuestas de proveedores de IA remotos.

El SDK informa estos fallos del lado de la base de datos mediante SelectAIException.

Manejar SelectAIException

Capture SelectAIException para gestionar los fallos de las operaciones Select AI respaldadas por base de datos.

Por ejemplo:

try (SelectAI selectAI = SelectAI.create(dataSource)) {
    Profile profile = selectAI.profile("MY_PROFILE");
    String response = profile.chat("Show the top five products");
} catch (SelectAIException exception) {
    System.err.println(exception.getMessage());
    System.err.println(exception.getErrorCode());
    System.err.println(exception.getSqlState());
}

Registre suficiente información de diagnóstico para solucionar el fallo, pero no registre contraseñas, claves privadas, tokens ni complete las configuraciones de credenciales.

Para conocer la jerarquía de excepciones, los detalles del error y el comportamiento específico de la operación, consulte Select AI for Java API Reference (Javadoc).

Inspeccionar detalles de error

Utilice los siguientes métodos SelectAIException para inspeccionar la información de error disponible:

Los fallos del proveedor no utilizan un tipo de excepción de proveedor Java independiente. DBMS_CLOUD o DBMS_CLOUD_AI normalmente reciben un fallo de proveedor, lo informan a través de las capas de base de datos y JDBC y el SDK encapsula el fallo en SelectAIException.

Por ejemplo, un error HTTP devuelto por un proveedor de AI puede aparecer como un error de Oracle, como ORA-20400. Inspeccione los detalles del error SelectAIException y la causa subyacente de la información de diagnóstico disponible para la operación.

Para conocer los métodos SelectAIException completos y los valores de retorno, consulte Select AI for Java API Reference (Javadoc).

Reintentar operaciones fallidas

La selección de AI para Java no reintenta automáticamente las operaciones con fallos.

Puede considerar reintentar una operación de metadatos de solo lectura después de confirmar que un fallo de conexión fue transitorio.

No vuelva a intentar automáticamente las operaciones de creación, actualización, supresión, administración, generación o chat. Es posible que la base de datos o el proveedor de AI hayan comenzado a procesar la solicitud antes de que la aplicación recibiera el fallo.

Antes de reintentar una operación que puede cambiar el estado de la base de datos o enviar una solicitud a un proveedor de AI, verifique la operación o el estado del recurso actual y confirme que la repetición de la solicitud es segura.

Timeout y Trabajo del Servidor

El valor queryTimeoutSeconds configura el timeout de la sentencia JDBC. No necesariamente configura:

• Timeout de punto final de proveedor de AI.
• Una conexión HTTP o un timeout de lectura.
• Cancelación de una solicitud de modelo remoto.
• Cancelación de una operación DBMS_CLOUD_AI de larga ejecución.

Un timeout de JDBC puede impedir que la aplicación espere la sentencia JDBC mientras continúa el procesamiento del lado de la base de datos o del lado del proveedor.

Precaución: no suponga que una operación con tiempo de espera agotado haya dejado de procesarse. Antes de reintentar la operación, verifique el estado de la operación o el recurso de base de datos afectados y considere si el proveedor de AI aún puede estar procesando la solicitud original.

Para obtener más información, consulte Comportamiento de la transacción.

Solucionar errores

Cuando una operación falla:

1. Revise el mensaje SelectAIException, el código de error de Oracle, SQLState y la causa subyacente cuando esté disponible.
2. Confirme que el usuario de la base de datos tiene los privilegios necesarios.
3. Confirme que existe el perfil, la credencial, la conversación o el índice vectorial a los que se hace referencia y que tiene el estado necesario.
4. Verifique la configuración del proveedor y la credencial cuando sea necesario.
5. Verifique el acceso a la red y la configuración de ACL cuando el proveedor o el origen de datos lo requieran.
6. Para los fallos del proveedor, revise el error de Oracle y la información de diagnóstico subyacente devuelta a través de DBMS_CLOUD o DBMS_CLOUD_AI.
7. Para un timeout o fallo de conexión, verifique la operación o el estado del recurso antes de reintentar la solicitud.

Para obtener información completa sobre SelectAIException, las excepciones específicas del método, el comportamiento de validación y el manejo de errores, consulte Select AI for Java API Reference (Javadoc).

Seleccionar AI para ejemplos de Java

Explore los ejemplos de selección de IA para Java para el código Java de ejemplo que muestra cómo configurar y utilizar las funciones de selección de IA para Java. Utilice estos ejemplos con Select AI for Java API Reference (Javadoc) para comprender las clases, los métodos y la configuración utilizados en cada flujo de trabajo.