Sélectionner AI pour Java

Select AI pour Java est un kit SDK Java qui fournit une API native Java pour la configuration et l'utilisation de Select AI avec Oracle Autonomous AI Database. Le kit SDK fournit des fonctionnalités Select AI, notamment les profils d'IA, les informations d'identification, les conversations, les index vectoriels, le langage naturel SQL, la synthèse, la traduction, les commentaires et la génération de données synthétiques via des classes, des interfaces et des méthodes Java.

Le kit SDK utilise JDBC pour communiquer avec la base de données et utilise les API de base de données sous-jacentes requises pour les opérations Select AI. Il prend en charge les connexions JDBC gérées par le kit SDK et les connexions DataSource gérées par l'application.

Cette documentation fournit des conseils orientés tâche pour l'installation, la configuration et l'utilisation du kit SDK. Pour obtenir des détails complets sur les classes, les méthodes, les paramètres et les exceptions, reportez-vous à la section Select AI for Java API Reference.

Pour les constructeurs, les méthodes, les classes de demande et de réponse, les attributs, paramètres, exemples et exceptions pris en charge, reportez-vous à Sélection d'IA pour la référence d'API Java (Javadoc).

Environnements pris en charge

Select AI for Java a été validé avec :

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

Remarque

Remarque : DBMS_CLOUD_AI_AGENT n'est pas inclus dans la portée de Select AI pour Java version 1.0.0.

Le kit SDK utilise le pilote léger JDBC Oracle pour la connectivité de base de données. Vous pouvez utiliser le kit SDK avec des déploiements de base de données Oracle pris en charge qui fournissent les privilèges et packages de base de données Select AI requis. Confirmez la configuration du fournisseur AI des versions de base de données et de pilote JDBC prises en charge, ainsi que les privilèges requis avant de déployer une application. Reportez-vous à la matrice des fonctionnalités d'Oracle AI Database Select AI pour connaître les fonctionnalités prises en charge ainsi que leurs versions de base de données.

Télécharger le kit SDK

Sélectionnez AI pour la version 1.0.0 de Java publiée dans Maven Central.

Pour les applications Maven et Gradle, déclarez le kit SDK en tant que dépendance. Maven ou Gradle résout le SDK et ses dépendances d'exécution à partir de Maven Central.

Utilisez la page d'artefact Maven Central pour télécharger : Sélectionner l'IA pour Java 1.0.0 sur Maven Central

Pour obtenir des descriptions d'API, des classes, des méthodes, des paramètres et des informations d'utilisation, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Ajouter Select AI pour Java à votre application

Sélectionnez AI pour Java en tant que fichier JAR Java standard. Le fichier JAR du kit SDK n'inclut pas ses dépendances d'exécution tierces. Maven ou Gradle résout ces dépendances à partir du POM publié.

Sélectionnez AI pour Java version 1.0.0 requiert JDK 17 ou version ultérieure.

Utilisez la dépendance Maven publiée pour le développement d'applications normal. Pour plus de détails, reportez-vous à Téléchargement du kit SDK.

Ajout du kit SDK à une application Maven

Ajoutez la dépendance suivante au fichier pom.xml de votre application :

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

Maven résout le kit SDK et ses dépendances d'exécution transitives à partir du POM publié.

Ajout du kit SDK à une application Gradle

Pour les applications Gradle qui utilisent le DSL Groovy, ajoutez la configuration suivante au fichier build.gradle : par exemple :

repositories {
    mavenLocal()
}

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

Remarque

Remarque : la configuration Gradle utilise l'artefact Maven Central. Il n'indique pas de distribution de Gradle distincte.

Dépendances d'exécution

Le fichier JAR du kit SDK ne regroupe pas les dépendances tierces. Lorsque vous utilisez le kit SDK en tant que dépendance Maven ou Gradle, l'outil de gestion des dépendances résout les dépendances directes et transitives requises à partir du POM publié.

Le kit SDK utilise les dépendances d'exécution principales suivantes :

Le kit SDK dépend de l'API SLF4J mais n'inclut pas de fournisseur de journalisation SLF4J. Configurez un fournisseur de journalisation SLF4J 2.x approprié pour votre application. Les exemples de kit SDK autonome utilisent slf4j-simple.

Si vous utilisez le fichier JAR SDK directement au lieu d'un système de gestion des dépendances, vous devez également rendre ses dépendances d'exécution disponibles sur le classpath de l'application. Utilisez les dépendances résolues à partir du kit SDK pom.xml pour vous assurer d'inclure les dépendances directes et transitives requises.

Pour copier les dépendances d'exécution pour une utilisation directe de JAR, exécutez la commande suivante :

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

Utilisez le fichier JAR SDK et les dépendances copiées sur la variable d'environnement CLASSPATH de l'application :

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

Sous Windows PowerShell, utilisez un point-virgule (;) au lieu du point-virgule (:) dans la variable d'environnement CLASSPATH :

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

Connexion à la base de données Autonomous AI

Sélectionnez AI pour Java qui utilise des connexions JDBC pour communiquer avec Autonomous AI Database. Vous pouvez fournir des informations de connexion directement ou fournir un DataSource JDBC.

Gérer les connexions JDBC

Choisissez une approche de gestion des connexions avant de créer des objets Select AI. Utiliser une approche cohérente dans l'ensemble d'une application ou documenter clairement la propriété lorsque plusieurs composants partagent les mêmes ressources de base de données.

Le kit SDK prend en charge les modes de connexion suivants :

• DbConnectionConfig : configuration de connexion utilisée par le kit SDK pour obtenir et gérer les connexions JDBC.
• DataSource : DataSource fourni par l'application.

DbConnection est une API de propriétaire de connexion autonome distincte.

Lorsque l'application fournit une connexion, assurez-vous que la connexion est ouverte et configurée pour l'utilisateur de base de données voulu. Lorsque le kit SDK obtient des connexions à partir d'une configuration ou de DataSource, suivez les règles de cycle de vie décrites dans Sélectionner AI pour la référence d'API Java (Javadoc).

Choisissez le mode qui correspond au modèle de gestion des connexions utilisé par votre application. Les applications qui utilisent déjà un pool de connexions peuvent fournir son DataSource. Les applications qui gèrent directement les propriétés de connexion peuvent utiliser la configuration de connexion du kit SDK.

Configuration de connexion de base de données

Utilisez DbConnectionConfig pour définir les propriétés de connexion à la base de données et les options liées à la connexion. En mode DbConnectionConfig, le kit SDK crée et possède une connexion JDBC unique pour le client SelectAI. Le kit SDK réutilise cette connexion pour les opérations effectuées par ce client. Le kit SDK ferme la connexion JDBC lorsque vous appelez SelectAI.close(). Etant donné que le client utilise une connexion JDBC conservée, traitez un client SelectAI basé sur DbConnectionConfig comme un seul thread, sauf si votre application synchronise l'accès en externe.

Utilisez DbConnectionConfig pour les applications simples, les programmes de ligne de commande, les exemples et les applications qui utilisent une seule connexion de base de données pour un client SelectAI. La configuration peut inclure l'URL de la base de données, les informations d'authentification, les paramètres de portefeuille ou de sécurité et les paramètres d'exécution facultatifs.

Conservez les informations de connexion et les secrets en dehors du code source de l'application. Utilisez les fonctions d'informations d'identification et de gestion des clés secrètes recommandées pour votre déploiement.

Pour obtenir la liste complète des propriétés, constructeurs, règles de validation et options d'authentification pris en charge, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Source de données

Utilisez un élément DataSource lorsque l'application ou le serveur d'applications est propriétaire de la création et du regroupement de connexions. En mode DataSource, l'application est propriétaire de DataSource. Le kit SDK emprunte une connexion JDBC à DataSource pour chaque opération et ferme la connexion empruntée une fois l'opération terminée. Lorsque DataSource utilise un pool de connexions, la fermeture de la connexion empruntée la renvoie normalement au pool. L'appel de SelectAI.close() ne ferme pas le fichier DataSource appartenant à l'application.

Utilisez le mode DataSource pour les serveurs d'applications, les applications Spring ou Jakarta, les services multithread et les applications qui gèrent les pools de connexions JDBC. Un élément DataSource peut intégrer Select AI pour Java à l'infrastructure JDBC existante et aux pools de connexions Enterprise.

L'application reste responsable de la configuration de DataSource, de la capacité du pool, de la validation et de la sécurité. Le kit SDK utilise le fichier DataSource fourni par l'application pour les opérations de base de données.

Cycle de vie des connexions

Fermez les connexions et les autres ressources JDBC en fonction du modèle de propriété utilisé par l'application. Libérez les ressources lorsqu'une opération se termine et ne conservez pas les connexions de courte durée plus longtemps que nécessaire.

Lorsqu'une application utilise un pool de connexions, renvoyez les connexions au pool au lieu de fermer directement la ressource gérée par le pool.

Le kit SDK gère le cycle de vie des connexions JDBC en fonction du mode de connexion sélectionné :

Les objets ressource tels que Profile, Conversation et VectorIndex utilisent le cycle de vie de connexion du client SelectAI associé. Ils ne créent ni ne possèdent une connexion JDBC distincte.

Comportement de thread

Sélectionnez AI pour Java qui prend en charge différents comportements de thread en fonction du mode de connexion et de la façon dont les applications utilisent les objets ressource SDK. Le SDK ne constitue pas une garantie globale de sécurité des threads pour tous les objets publics.

Pour le mode DataSource, vous pouvez partager un client SelectAI entre les threads pour les opérations indépendantes car chaque opération obtient sa propre connexion JDBC.

Pour le mode DbConnectionConfig, traitez le client SelectAI comme un thread unique, sauf si votre application synchronise l'accès à la connexion JDBC conservée.

Attention : plusieurs threads peuvent utiliser des instances de ressource distinctes pour des opérations indépendantes. Si plusieurs threads utilisent la même instance de ressource, ne modifiez pas cette ressource simultanément, sauf si votre application synchronise l'accès. Par exemple, n'utilisez pas plusieurs threads en même temps pour modifier les mêmes ressources, telles que l'instance Profile, Credential, Conversation ou VectorIndex. Ne créez, ne mettez pas à jour, n'activez, ne désactivez ou ne supprimez pas simultanément la même ressource. Si votre application requiert un accès simultané à la même instance de ressource, synchronisez l'accès dans l'application.

Comportement de la transaction

Sélectionnez AI pour Java qui utilise le comportement des transactions JDBC. Le comportement de la transaction dépend de la configuration de la connexion et des API Oracle AI Database utilisées par le kit SDK. Configurer les limites de validation automatique et de transaction en fonction des exigences de l'application et du fonctionnement de la base de données. Sélectionnez AI pour Java. Les transactions ne sont pas explicitement validées ou annulées et ne modifient pas le paramètre autoCommit de la connexion JDBC.

En mode DbConnectionConfig, le kit SDK réutilise sa connexion JDBC appartenant au kit SDK entre les opérations. Si autoCommit est désactivé, les opérations SDK et les instructions JDBC personnalisées qui utilisent la même connexion participent à la transaction de la connexion en fonction de la sémantique des transactions JDBC et Oracle AI Database.

En mode DataSource, le kit SDK emprunte une connexion JDBC pour chaque opération et ferme la connexion une fois l'opération terminée. Le kit SDK ne modifie pas explicitement le paramètre autoCommit de la connexion, ni ne valide ou annule la transaction avant de renvoyer la connexion. Le pool de connexions ou le pool de connexions DataSource contrôle la manière dont l'état de la connexion et les transactions en attente sont gérés lorsqu'une connexion empruntée est renvoyée au pool.

Remarque

Remarque : en mode DataSource, chaque opération de kit SDK emprunte une connexion à DataSource. Par conséquent, ne vous fiez pas aux modifications non validées d'une opération SDK disponible pour une autre opération.

Les opérations SDK qui créent ou modifient des opérations de profil, d'informations d'identification, de conversation et d'index vectoriel utilisent le comportement de transaction de la connexion JDBC et de l'API Oracle AI Database sous-jacente. Certaines API de base de données sous-jacentes peuvent effectuer une validation ou une annulation implicite. Le kit SDK ne modifie ni ne remplace ce comportement de base de données.

Remarque

Remarque : en mode DbConnectionConfig, SelectAI.getConnection() renvoie la connexion JDBC détenue par le kit SDK utilisée pour ses opérations. Vous pouvez utiliser cette connexion pour le travail JDBC personnalisé dans la même session de base de données. Le fait que les opérations SDK et les instructions JDBC personnalisées puissent former une transaction atomique unique dépend du comportement des transactions des API Oracle AI Database sous-jacentes.

Délai d'expiration de la requête

L'option query-timeout configure le délai d'expiration de l'instruction JDBC. Utilisez SelectAIOptions.queryTimeoutSeconds() pour configurer le délai d'expiration de la requête d'instruction JDBC pour les opérations SDK. Par défaut, le kit SDK ne configure pas de délai d'expiration de requête JDBC. Une valeur non définie ou NULL signifie que le kit SDK n'appelle pas Statement.setQueryTimeout(). La valeur 0 utilise le comportement sans délai d'expiration JDBC. Le kit SDK rejette les valeurs négatives.

Le délai d'expiration configuré s'applique aux instructions JDBC créées pour les opérations SDK. Il contrôle le délai d'expiration de l'instruction JDBC ou de la base de données ; il ne configure pas :

• Délai d'expiration des demandes du fournisseur d'IA
• Délais d'expiration de connexion ou de lecture HTTP
• annulation d'une demande de modèle distant
• délai d'expiration distinct pour une opération DBMS_CLOUD_AI longue durée

Si une opération de base de données a déjà envoyé une demande à un fournisseur AI, le délai d'expiration d'une instruction JDBC ne garantit pas l'annulation de la demande de fournisseur. L'interruption de l'appel de base de données par le pilote JDBC dépend du comportement d'Oracle JDBC et de la base de données.

Pour plus de détails sur SelectAIOptions, la gestion des connexions et les opérations de ressource, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Avant de commencer

Avant d'utiliser Select AI pour Java :

1. Vérifiez que la version de base de données est prise en charge.
2. Obtenez les informations de connexion à la base de données et l'authentification requises par l'application.
3. Configurez les informations d'identification de base de données et de fournisseur AI requis.
4. Créez ou identifiez un profil AI pour le workflow prévu.
5. Vérifiez que l'utilisateur de base de données dispose des privilèges et de l'accès réseau requis pour les fonctionnalités sélectionnées.
6. Reportez-vous à Exécution des prérequis pour Select AI pour connaître les exigences de configuration.

Gérer les privilèges de base de données et l'accès réseau

Sélectionnez AI pour Java qui fournit l'interface DatabaseAdmin pour les opérations de configuration de base de données privilégiées. Utilisez l'interface SelectAI pour les opérations d'application normales.

Utilisez DatabaseAdmin uniquement dans un workflow de provisionnement ou d'administration contrôlé séparément. N'exposez pas DatabaseAdmin aux utilisateurs d'application normaux et ne l'incluez pas dans le chemin d'exécution général de l'application.

L'interface DatabaseAdmin fournit des méthodes d'administration pour :

• Accordez ou révoquez les privilèges de package Select AI pour les utilisateurs de base de données.
• Accordez ou révoquez l'accès HTTP aux hôtes externes.
• Accordez ou révoquez l'accès réseau pour les hôtes, privilèges et plages de ports facultatifs spécifiés.
• Activer ou désactiver l'accès aux données Select AI.

Ces opérations nécessitent un utilisateur de base de données d'administration doté de privilèges appropriés. L'utilisateur de base de données qui exécute l'application n'a pas besoin de privilèges DatabaseAdmin, sauf si cet utilisateur effectue également la configuration administrative.

Privilèges de package

Utilisez les méthodes package-privilege DatabaseAdmin pour accorder ou révoquer les privilèges de package de base de données requis par les utilisateurs Select AI.

Pour utiliser Select AI, un administrateur de base de données accorde EXECUTE sur DBMS_CLOUD_AI à l'utilisateur de base de données. Certaines fonctionnalités d'IA peuvent nécessiter des privilèges de package supplémentaires. Par exemple, la génération augmentée par récupération (RAG) nécessite l'accès à DBMS_CLOUD_PIPELINE.

Les opérations d'informations d'identification utilisent DBMS_CLOUD et nécessitent que l'utilisateur de base de données qui gère les informations d'identification ait accès aux API DBMS_CLOUD correspondantes.

Le package accorde des privilèges de modification aux utilisateurs de base de données spécifiés dans la demande d'administration. Effectuez ces autorisations pendant le provisionnement de la base de données ou des applications plutôt que pendant le démarrage normal de l'application.

Remarque

Remarque : DBMS_CLOUD_AI_AGENT n'est pas inclus dans la portée de Select AI pour Java version 1.0.0.

Pour connaître les privilèges requis, reportez-vous à Exécution des prérequis pour Select AI.

Accès réseau

Utilisez les méthodes d'accès réseau DatabaseAdmin uniquement lorsqu'un administrateur de base de données doit configurer l'accès sortant pour les utilisateurs Select AI.

L'API fournit :

• Méthodes d'accès HTTP permettant d'accorder ou de révoquer l'accès HTTP à un hôte spécifié.
• Méthodes générales d'accès réseau permettant d'accorder ou de révoquer des privilèges réseau spécifiés pour un hôte et, éventuellement, une plage de ports TCP.

La configuration d'ACL réseau n'est pas requise pour chaque fournisseur ou déploiement de base de données Select AI. Configurez l'accès réseau uniquement lorsque le fournisseur et le déploiement sélectionnés en ont besoin. Par exemple, Select AI ne nécessite pas d'ACL réseau pour OCI Generative AI.

Les modifications apportées à l'ACL réseau modifient la configuration de l'ACL réseau de la base de données. La configuration d'ACL réside dans la base de données plutôt que dans l'application Java ou le schéma de l'utilisateur cible. Une entrée de contrôle d'accès identifie l'utilisateur ou le rôle de base de données qui reçoit l'accès. Par conséquent, la configuration d'une liste de contrôle d'accès n'accorde pas automatiquement l'accès réseau à chaque utilisateur de base de données.

Indiquez uniquement les hôtes dont l'application a besoin. Un hôte peut identifier un nom d'hôte, une adresse IP, un domaine ou un caractère générique pris en charge. Le cas échéant, utilisez les paramètres des ports inférieur et supérieur pour restreindre l'accès à la plage de ports TCP requise. Si vous ne spécifiez pas de plage de ports, les règles d'ACL du réseau sous-jacent déterminent l'accès sans restriction de port.

Les modifications d'ACL réseau restent une partie de la configuration de la base de données jusqu'à ce qu'un administrateur les modifie ou les supprime. Il ne s'agit pas de paramètres temporaires associés au processus SDK Java ou à la session JDBC.

Attention : les modifications d'ACL réseau affectent la configuration de la sécurité de la base de données. Configurer l'accès réseau dans le cadre d'un workflow de provisionnement ou d'administration contrôlé. N'accordez pas de privilèges de gestion réseau DatabaseAdmin à l'exécution d'application normale.

Pour connaître les adresses de fournisseur et la configuration réseau requise, reportez-vous à Exécution des prérequis pour Select AI.

Sélectionner l'accès aux données AI

Utilisez DatabaseAdmin.enableDataAccess() et DatabaseAdmin.disableDataAccess() pour déterminer si les fonctionnalités Select AI applicables peuvent envoyer des données de base de données ou du contenu de document de recherche vectorielle vers un modèle de langage volumineux.

Ce paramètre s'applique aux fonctionnalités Select AI qui nécessitent un accès aux données, notamment l'action de narration, la génération augmentée par extraction (RAG) et la génération de données synthétiques.

Seul un administrateur peut modifier le paramètre Sélectionner l'accès aux données AI. Les procédures DBMS_CLOUD_AI.ENABLE_DATA_ACCESS et DBMS_CLOUD_AI.DISABLE_DATA_ACCESS sous-jacentes n'acceptent pas de paramètre de schéma ou d'utilisateur de base de données.

Traitez les modifications de Sélectionner l'accès aux données AI en tant que configuration de base de données administrative. Configurez le paramètre requis pendant le provisionnement ou via une modification administrative explicitement autorisée, plutôt que pendant le démarrage normal de l'application.

Attention : la désactivation de l'accès aux données Select AI peut limiter les fonctionnalités Select AI qui doivent envoyer des données de base de données ou du contenu de document extrait au fournisseur d'IA. Vérifiez les fonctionnalités Select AI affectées avant de modifier ce paramètre.

Opérations administratives et d'exécution

Oracle recommande de séparer la configuration administrative du traitement normal des applications.

Utilisez un utilisateur de base de données avec le moins de privilèges possible pour l'exécution d'application normale. N'accordez pas de privilèges d'administration à un utilisateur d'application uniquement afin que l'application puisse configurer ses propres prérequis au démarrage.

Pour connaître les privilèges Select AI requis, les informations d'identification, la configuration du fournisseur et les exigences réseau, reportez-vous à Exécution des prérequis pour Select AI.

Pour connaître les méthodes, paramètres et exceptions DatabaseAdmin, reportez-vous à Sélection d'IA pour la référence d'API Java (Javadoc).

Tâches disponibles

Le kit SDK Select AI pour Java fournit une API Java pour l'utilisation des ressources Select AI.

Le tableau suivant récapitule les principales fonctionnalités Select AI pour Java :

Pour plus de détails sur l'API Java, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Classes prises en charge

Select AI for Java fournit des interfaces publiques et des classes de modèle pour les opérations d'application, la configuration administrative, la gestion des connexions et Select AI resource configuration.

Le code d'application doit utiliser les interfaces publiques dans com.oracle.database.selectai et les types de modèle associés dans com.oracle.database.selectai.model. Les classes dans com.oracle.database.selectai.impl sont des classes d'implémentation internes qui ne sont pas destinées à une utilisation directe d'application.

Classes d'application principales

Utilisez ces classes pour les workflows d'application Select AI courants.

Classes administratives

Utilisez l'interface DatabaseAdmin séparément du traitement normal de l'application.

Utilisez DatabaseAdmin uniquement dans un workflow de provisionnement ou d'administration contrôlé séparément. Pour plus d'informations, reportez-vous à Gestion des privilèges de base de données et de l'accès réseau.

Modèles de configuration et de demande

Utilisez les classes de modèle suivantes pour configurer les ressources et les opérations SDK.

API de connexion et points d'extension

Le kit SDK fournit des interfaces de connexion publiques et des points d'extension pour les applications qui nécessitent un accès direct à une connexion JDBC ou une gestion personnalisée des connexions.

Pour la plupart des applications, utilisez DbConnectionConfig ou DataSource géré par l'application avec SelectAI. Utilisez les points d'extension de connexion uniquement lorsque votre application requiert un traitement de connexion JDBC personnalisé.

Pour connaître la propriété des connexions, le cycle de vie, les transactions et le comportement des threads, reportez-vous à Connexion à une base de données d'IA autonome.

Classes de fournisseur

Sélectionnez AI pour Java représente les fournisseurs d'IA via l'énumération Provider et les classes de configuration propres au fournisseur pour les fournisseurs d'IA pris en charge. Utilisez la configuration de fournisseur appropriée lorsque vous configurez un profil AI.

Sélectionnez AI pour Java et les classes de configuration de fournisseur suivantes :

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

Utilisez la configuration de fournisseur appropriée pour le fournisseur que vous configurez dans ProfileAttributes. Pour connaître les prérequis du fournisseur et les exigences de configuration, reportez-vous à Exécution des prérequis pour Select AI.

Classes d'implémentation internes

Les classes du package com.oracle.database.selectai.impl implémentent les interfaces de kit SDK public et gèrent les interactions JDBC et de base de données internes.

Remarque

Remarque : les classes du package com.oracle.database.selectai.impl fournissent les implémentations internes des interfaces de kit SDK public. Ces classes ne sont pas prises en charge en tant qu'API orientées application et peuvent changer indépendamment de l'API publique. Utilisez plutôt les méthodes d'usine et les interfaces publiques dans com.oracle.database.selectai.

Pour obtenir des informations complètes sur les classes publiques, les interfaces, les types de modèle, les méthodes et les points d'extension, reportez-vous à Sélection d'IA pour la référence d'API Java (Javadoc).

Utiliser les informations d'identification

Les informations d'identification de base de données stockent les informations d'authentification utilisées par Autonomous AI Database pour accéder à un fournisseur d'IA ou à un service externe tel qu'Object Storage.

Créez les informations d'identification requises avant de créer un profil AI ou un index vectoriel qui les référence. L'utilisateur de base de données qui crée les informations d'identification en est propriétaire et leur nom les identifie dans le schéma de cet utilisateur.

Créer et gérer des informations d'identification

Utilisez SelectAI.credential(CredentialConfig) pour créer un objet Credential à partir de la configuration des informations d'identification. Cette méthode crée un objet Credential Java uniquement ; elle ne crée pas les informations d'identification dans la base de données. Appelez Credential.create() sur l'objet Credential renvoyé pour créer les informations d'identification de base de données.

Utilisez les méthodes Credential suivantes :

• create() : crée les informations d'identification de base de données.
• drop() : enlève les informations d'identification de base de données.
• drop(boolean force) : enlève les informations d'identification de base de données et, lorsque force est true, traite les informations d'identification déjà absentes comme un résultat positif.

La classe CredentialConfig définit les détails de création des informations d'identification, notamment le nom des informations d'identification et les informations d'authentification prises en charge.

Propriété des informations d'identification

L'utilisateur de base de données qui crée les informations d'identification possède les informations d'identification. Ce nom identifie les informations d'identification dans le schéma de cet utilisateur.

Le kit SDK ne fournit pas de méthode permettant d'extraire les valeurs secrètes stockées d'informations d'identification. Protégez les mots de passe, les clés privées, les empreintes digitales, les OCID et les configurations complètes des informations d'identification. N'incluez pas de clés secrètes dans le code source, les journaux, les rapports d'erreur ou les invites.

Informations d'identification du fournisseur AI

Les informations d'identification du fournisseur AI stockent les informations d'authentification requises pour accéder au fournisseur AI configuré.

Configurez des informations d'identification de fournisseur AI lorsque le profil AI requiert des informations d'identification de base de données pour l'authentification de fournisseur. Le profil référence les informations d'identification par leur nom via sa configuration de profil.

Pour l'authentification OCI, CredentialConfig prend en charge la configuration des informations d'identification qui inclut le nom des informations d'identification, l'OCID utilisateur, l'OCID de location, la clé privée et l'empreinte.

Informations d'identification Object Storage

Utilisez des informations d'identification de base de données pour authentifier l'accès à Object Storage lorsqu'un index vectoriel utilise du contenu qui y est stocké.

Le programme d'installation automatisée de sélection pour le kit SDK Java ne définit pas de type Java distinct pour les informations d'identification Object Storage. Créez les informations d'identification de base de données à l'aide de méthodes dans l'interface Credential. Indiquez les informations d'identification pour l'accès Object Storage dans la configuration d'index vectoriel.

VectorIndexAttributes définit l'attribut d'informations d'identification Object Storage, ainsi que d'autres attributs d'index vectoriel tels que l'emplacement source.

Les mêmes informations d'identification de base de données peuvent être référencées par plusieurs ressources Select AI lorsqu'elles nécessitent les mêmes informations d'authentification.

Suppression d'informations d'identification

Utilisez Credential.drop() ou Credential.drop(boolean force) pour enlever des informations d'identification.

La suppression d'informations d'identification ne met pas automatiquement à jour les profils AI ou les index vectoriels qui les référencent. Si une ressource référence toujours les informations d'identification supprimées, une opération nécessitant ces informations peut échouer.

Attention : avant de supprimer des informations d'identification, identifiez les profils AI, les index vectoriels et les autres ressources qui les référencent. Mettez à jour ou supprimez ces dépendances selon vos besoins.

Principaux de ressource et principaux d'instance OCI

Certaines configurations d'authentification OCI peuvent utiliser des principaux de ressource ou d'instance au lieu d'informations d'identification utilisateur stockées. Lorsque le fournisseur et l'environnement de base de données sélectionnés prennent en charge ces méthodes d'authentification, vous pouvez utiliser la configuration d'authentification OCI prise en charge sans stocker les informations de signature utilisateur dans des informations d'identification de base de données.

Pour connaître les exigences d'authentification propres au fournisseur, reportez-vous à Exécution des prérequis pour Select AI.

Pour la configuration des informations d'identification, les propriétés d'authentification prises en charge, les opérations de cycle de vie et les exceptions, reportez-vous à Sélection d'IA pour la référence d'API Java (Javadoc).

Utilisation des profils d'IA

Un profil AI définit la façon dont Select AI communique avec un fournisseur AI et les objets de base de données et les index vectoriels que Select AI peut utiliser. Un profil peut inclure des paramètres de fournisseur, de modèle, d'informations d'identification, de liste d'objets, de conversation, de traduction et d'index vectoriel.

Utilisez l'interface Profile pour créer et gérer des profils AI et effectuer des opérations Select AI. Toutes les méthodes de l'interface Profile sont synchrones. Le thread appelant attend que chaque opération se termine ou renvoie une erreur.

Configuration d'un profil AI

Utilisez la classe ProfileAttributes pour configurer un profil AI. La configuration du profil dépend du fournisseur et de la fonctionnalité Select AI que vous utilisez.

Indiquez le fournisseur et les autres attributs requis par ce fournisseur. Les attributs propres au fournisseur peuvent inclure le modèle, les informations d'identification, l'adresse, la région, le compartiment et d'autres paramètres de fournisseur.

Configurez des informations d'identification de base de données lorsque le fournisseur et la méthode d'authentification sélectionnés en nécessitent une. Certaines méthodes d'authentification prises en charge ne nécessitent pas d'informations d'identification de base de données stockées.

Utilisez les classes de configuration propres au fournisseur dans ProviderProfile pour définir les paramètres du fournisseur. Pour connaître les attributs requis et facultatifs de chaque fournisseur, reportez-vous à Exécution des prérequis pour Select AI.

Créer un profil AI

Utilisez SelectAI.profile(String profileName, ProfileAttributes profileAttributes, String description, ProfileStatus status) pour créer un objet Java Profile initialisé avec la configuration de profil.

Cette méthode ne crée pas le profil AI dans la base de données. Appelez Profile.create() sur l'objet renvoyé pour créer le profil de base de données.

Par exemple :

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();

Les valeurs ProfileAttributes requises dépendent du fournisseur, de la méthode d'authentification et de la fonctionnalité de profil sélectionnés. Configurez les informations d'identification requises avant de créer un profil qui les référence.

Pour obtenir un exemple complet de création de profil pour votre fournisseur, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Utiliser un profil AI existant

Utilisez SelectAI.profile(String profileName) pour ouvrir un profil AI existant dans le schéma en cours. La méthode renvoie un objet Profile que vous pouvez utiliser pour les opérations de profil.

Par exemple :

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

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

Utilisez l'interface Profile pour :

• Générez et exécutez le code SQL avec runsql().
• Générez du code SQL sans l'exécuter avec showsql().
• Expliquer le code SQL généré avec explainsql().
• Signalez les résultats de la requête par narrate().
• Discutez avec le fournisseur d'IA configuré avec chat().
• Renvoyer l'invite augmentée par showprompt().
• Utilisez la génération augmentée de récupération (RAG) avec des index vectoriels configurés dans le profil AI via ProfileAttributes.
• Résumez le contenu avec summarize().
• Traduisez le contenu avec translate().
• Soumettez des commentaires pour le code SQL généré avec feedback().
• Générez des données synthétiques avec generateSyntheticData().

Configurer des objets de base de données pour NL2SQL

Utilisez la configuration de liste d'objets de profil pour contrôler les objets de base de données que Select AI prend en compte lors de la génération du code SQL.

La classe ProfileAttributes prend en charge la configuration de liste d'objets et les valeurs ObjectListMode AUTOMATED et ALL. Les paramètres de liste d'objets du profil déterminent les métadonnées de base de données que Select AI rend disponibles pour la génération SQL en langage naturel.

La liste d'objets n'accorde pas de privilèges de base de données. L'utilisateur de base de données doit disposer des privilèges requis sur les objets utilisés par le profil.

Pour connaître la configuration de liste d'objets et le comportement de sélection d'objets, reportez-vous à Gestion des profils AI.

Configuration des index vectoriels pour la RAG

Associez des index vectoriels à un profil AI pour utiliser la génération augmentée par récupération (RAG). La classe ProfileAttributes fournit les paramètres d'index vectoriel que le profil utilise.

Lorsque vous utilisez un profil compatible RAG, Select AI extrait le contenu pertinent de l'index vectoriel configuré et ajoute ce contenu à l'invite augmentée envoyée au fournisseur AI.

Créez et configurez l'index vectoriel requis avant de l'utiliser avec le profil. Pour plus d'informations, reportez-vous à Sélectionner une IA avec la génération augmentée d'extraction (RAG).

Utiliser des profils dans certaines interfaces AI

La méthode Profile.create() crée le profil AI en tant que ressource de base de données. L'objet Java Profile fournit une représentation Java de ce profil de base de données.

Etant donné que le profil réside dans la base de données plutôt que dans le processus Java, d'autres interfaces Select AI qui peuvent accéder au même profil de base de données peuvent l'utiliser en fonction de leurs privilèges de base de données et des fonctionnalités de profil prises en charge. Cela inclut les interfaces SQL et PL/SQL et d'autres SDK ou API Select AI pris en charge.

Synthèse et traduction de contenu

Utilisez la méthode Profile.summarize() pour récapituler le contenu incorporé ou le contenu à un emplacement externe. Pour chaque demande d'agrégation, spécifiez un contenu en ligne ou un URI d'emplacement, mais pas les deux.

Utilisez la méthode Profile.translate() pour traduire du texte avec un fournisseur de traduction pris en charge configuré dans le profil. Les exigences en matière d'authentification, de prise en charge linguistique et de service propres au fournisseur s'appliquent.

Pour plus d'informations, reportez-vous à Génération d'un récapitulatif avec Select AI et à Traduction.

Fournir des commentaires SQL

Utilisez la méthode Profile.feedback() pour soumettre des commentaires positifs ou négatifs pour la génération NL2SQL.

Un retour positif confirme le code SQL généré pour référence ultérieure. Les commentaires négatifs peuvent identifier les problèmes liés au code SQL généré et fournir le code SQL attendu ou des conseils supplémentaires. Select AI peut utiliser les retours stockés pertinents comme conseils pour des invites similaires lors de la génération suivante d'instructions SQL.

Pour plus d'informations, voir Commentaires.

Pour obtenir des informations complètes sur l'interface Profile, la classe ProfileAttributes, la configuration propre au fournisseur, les méthodes de cycle de vie de profil, les méthodes de génération et des exemples, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Utiliser les conversations

Un objet Conversation représente une conversation Select AI stockée dans la base de données. Utilisez une conversation pour conserver le contexte et l'historique des invites dans les interactions Select AI associées.

Une conversation est une ressource de base de données identifiée par un ID de conversation. Il n'est pas associé de manière permanente à un profil AI. Les applications peuvent utiliser l'identificateur de conversation avec les opérations Select AI qui prennent en charge le contexte conversationnel, sous réserve de la configuration de profil et des privilèges de base de données de l'application.

Créer une conversation

Utilisez SelectAI.conversation(ConversationAttributes) pour créer un objet Java Conversation initialisé avec des attributs de conversation.

Cette méthode ne crée pas la conversation dans la base de données. Appelez Conversation.create() sur l'objet renvoyé pour créer la conversation de base de données. La méthode create() renvoie l'identificateur de conversation généré.

Attributs de conversation

Utilisez ConversationAttributes pour configurer les métadonnées de conversation, notamment :

• titre
• description
• jours de conservation
• durée de la conversation

L'attribut retentionDays indique la durée pendant laquelle Select AI conserve la conversation. L'attribut conversationLength indique la quantité de contexte de conversation que Select AI conserve pour les interactions associées.

Utilisez Conversation.getConversationAttributes() pour extraire les attributs en cours d'une conversation existante. Utilisez Conversation.setAttributes() pour mettre à jour les attributs de conversation pris en charge.

Sélectionnez AI pour stocker l'historique des invites de conversation dans la base de données. Utilisez Conversation.listPrompts() pour extraire les invites enregistrées pour la conversation, triées par heure de création. Utilisez Conversation.deletePrompt() pour enlever une invite individuelle. La suppression d'une invite individuelle avec deletePrompt() ne supprime pas la conversation. Utilisez Conversation.drop() pour enlever la conversation de la base de données.

Conservez l'identifiant de conversation lorsque les opérations d'application suivantes doivent accéder à la même conversation.

Utilisation d'une conversation existante

Utilisez SelectAI.conversation(String conversationId) pour ouvrir une conversation existante en fonction de son identificateur de conversation.

Une fois que vous avez ouvert ou créé une conversation, utilisez l'interface Conversation pour :

• Récupérez l'identificateur de conversation avec getConversationId().
• Extrayez les attributs de conversation avec getConversationAttributes().
• Mettez à jour les attributs de conversation avec setAttributes().
• Répertoriez les invites stockées pour la conversation avec listPrompts().
• Supprimez une invite individuelle avec deletePrompt().
• Supprimez la conversation avec drop().

Cycle de vie de conversation

Un objet Conversation Java n'enlève pas automatiquement la conversation de base de données correspondante lorsque l'objet Java est hors de portée ou lorsque le client SelectAI se ferme.

Gérez explicitement le cycle de vie des conversations de base de données. Appelez Conversation.drop() lorsque l'application ne nécessite plus la conversation.

Remarque

Remarque : l'instance Select AI en cours pour le kit SDK Java ne définit pas de cycle de vie de session publique distinct qui supprime automatiquement une conversation lorsque la session se ferme. Gérez les conversations via l'interface Conversation et l'identificateur de conversation.

Comportement de thread pour les conversations

Le kit SDK ne fournit pas de garantie globale de sécurité des threads pour les objets Conversation.

Plusieurs threads peuvent utiliser des instances Conversation distinctes pour des opérations indépendantes. N'utilisez pas plusieurs threads en même temps pour mettre à jour, supprimer des invites ou supprimer la même instance Conversation, sauf si votre application synchronise l'accès.

Pour connaître le comportement général des threads SDK et les considérations relatives au mode de connexion, reportez-vous à Comportement de thread.

Consignes pour les conversations

Traitez les identifiants de conversation et le contenu de conversation comme des données d'application. Une conversation peut contenir des invites et des métadonnées dérivées d'interactions de base de données ou d'informations commerciales sensibles.

N'incluez pas d'identifiants de conversation, d'invites ou de contenu de conversation dans les journaux, les rapports d'erreur ou toute autre sortie, sauf si les stratégies de sécurité et de journalisation de votre application le permettent. Limitez l'accès à la base de données aux conversations en fonction des exigences de contrôle d'accès de l'application.

Pour obtenir des informations complètes sur l'interface Conversation, la classe ConversationAttributes, les méthodes de cycle de vie des conversations, les métadonnées d'invite et des exemples, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Utiliser des index vectoriels

Les index vectoriels prennent en charge les workflows de génération augmentée par récupération (RAG). Un index vectoriel stocke les représentations recherchables du contenu source afin que Select AI puisse extraire les informations pertinentes pour une réponse AI.

Utilisez l'interface VectorIndex pour créer, extraire, mettre à jour, activer, désactiver et enlever des index vectoriels. Configurez l'index vectoriel avec l'emplacement source, les informations d'identification, les paramètres d'intégration et d'autres attributs requis par le workflow RAG prévu.

Utiliser des index vectoriels avec la RAG

Après avoir créé un index vectoriel, configurez un profil AI pour utiliser l'index pour la RAG.

L'index vectoriel fournit le contenu source extrait. Le profil compatible RAG fournit le fournisseur AI et la configuration de modèle utilisés pour traiter l'invite de l'utilisateur et le contenu extrait.

Vous pouvez utiliser le même index vectoriel avec plusieurs profils lorsque ces profils prennent en charge la configuration RAG requise.

Créer un index vectoriel

Utilisez SelectAI.vectorIndex(VectorIndexConfig) pour créer un objet Java VectorIndex à partir d'une configuration d'index vectoriel. Cette méthode crée l'objet Java ; elle ne crée pas l'index vectoriel dans la base de données.

Appelez VectorIndex.create() pour créer l'index vectoriel dans la base de données.

Lorsque le kit SDK crée un index vectoriel, la base de données :

1. Lit le contenu à partir de l'emplacement source configuré.
2. Utilise le profil et le fournisseur configurés pour l'index vectoriel pour générer des incorporations.
3. Stocke les vecteurs générés pour la récupération pendant les opérations RAG.

La classe VectorIndexConfig fournit la configuration de création, y compris le nom de l'index vectoriel, le nom du profil, le statut, la description, le paramètre d'attente de finalisation et les attributs d'index vectoriel.

Insertion et profil RAG

Le profil spécifié dans la configuration d'index vectoriel fournit le fournisseur et la configuration d'intégration que la base de données utilise pour créer des incorporations pour le contenu source.

Le profil utilisé pour créer des incorporations ne détermine pas automatiquement le profil utilisé par une application pour les demandes RAG. Configurez un profil pour la RAG séparément en spécifiant l'index vectoriel dans sa configuration ProfileAttributes.

Le workflow RAG utilise des profils AI dans différents rôles. Le tableau suivant met en correspondance chaque ressource du workflow avec la ressource ou la configuration Java Select AI correspondante.

Lorsque le profil compatible RAG traite une demande, Select AI extrait le contenu pertinent de l'index vectoriel et ajoute ce contenu à l'invite augmentée envoyée au fournisseur d'IA.

Pour plus d'informations, reportez-vous à Sélectionner une IA avec la génération augmentée d'extraction (RAG).

Surveillance de la création d'index de vecteur

La création d'index vectoriels peut être exécutée de manière synchrone ou asynchrone en fonction du paramètre waitForCompletion dans VectorIndexConfig.

Utilisez VectorIndex.getStatus() pour extraire le statut en cours d'un index vectoriel sauvegardé par la base de données. Utilisez VectorIndex.getVectorIndexAttributes() pour extraire ses attributs en cours.

En cas d'échec de la création de l'index vectoriel, VectorIndex.create() signale l'échec de la base de données ou de JDBC via SelectAIException.

Le kit SDK ne fournit pas d'interface de progression distincte ni d'objet de travail asynchrone pour la création d'index vectoriels.

Actualiser les index vectoriels

Un index vectoriel peut utiliser un taux d'actualisation configuré pour contrôler la façon dont l'index traite les modifications du contenu source.

Lorsque les documents source changent, la base de données met à jour l'index vectoriel en fonction du comportement d'actualisation configuré. Configurez la fréquence d'actualisation dans VectorIndexAttributes.

L'application n'a pas besoin de recréer l'index vectoriel uniquement parce que le contenu source change lorsque le comportement d'actualisation configuré prend en charge les mises à jour requises.

Les informations d'identification et l'emplacement source requis doivent rester disponibles pendant que l'index vectoriel traite ou actualise son contenu.

Pour connaître les attributs d'actualisation et la configuration pris en charge, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Mise à jour d'un index de vecteur

Utilisez les méthodes VectorIndex.update(VectorIndexAttributes) ou update() à attribut unique pour mettre à jour les attributs d'index vectoriel pris en charge.

Certains attributs s'appliquent uniquement lorsque vous créez l'index vectoriel et ne peuvent pas être modifiés ultérieurement. La base de données détermine si un attribut peut être mis à jour.

Créez la demande de mise à jour avec uniquement les attributs que la base de données prend en charge pour la modification. Par exemple, chunk_size est un attribut de création et ne peut pas être mis à jour après la création de l'index vectoriel.

Utilisez VectorIndex.getVectorIndexAttributes() pour extraire les attributs en cours d'un index vectoriel existant avant d'apporter des modifications.

Activation ou désactivation d'un index vectoriel

Utilisez les méthodes suivantes pour déterminer si Select AI peut utiliser un index vectoriel pour la récupération de RAG.

L'activation ou la désactivation d'un index vectoriel ne supprime pas les données vectorielles.

Supprimer un index de vecteur

Utilisez VectorIndex.drop(boolean force) pour enlever l'index de vecteur.

Ce formulaire supprime à la fois les métadonnées d'index vectoriel et les données de vecteur de sauvegarde.

Utilisez VectorIndex.drop(boolean includeData, boolean force) lorsque vous devez contrôler la suppression des données vectorielles de sauvegarde.

Attention : avant de supprimer un index vectoriel, identifiez tous les profils ou applications compatibles RAG qui l'utilisent. Vérifiez si les données vectorielles sous-jacentes doivent être conservées avant de sélectionner l'option de suppression.

Pour obtenir des exemples complets de sources exécutables, reportez-vous à vectorindex.

Pour connaître la configuration de base de données et les concepts de RAG, reportez-vous à Exécution des prérequis pour Select AI et à Sélection de l'IA avec génération augmentée de récupération (RAG).

Pour plus d'informations sur les attributs pris en charge, les options de création, les valeurs de statut, les méthodes de mise à jour et les méthodes de suppression, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Générer des données synthétiques

Sélectionnez AI pour Java pour générer des données synthétiques pour un seul objet de base de données ou pour plusieurs objets de base de données associés. Utiliser des données synthétiques pour les tests, le développement, le prototypage et l'analyse. La génération de données synthétiques utilise le fournisseur d'IA configuré dans l'objet Profile associé.

Utilisez Profile.generateSyntheticData(SyntheticDataSingleRequest) pour générer des données synthétiques pour un objet de base de données. Utilisez Profile.generateSyntheticData(SyntheticDataBatchRequest) pour générer des données synthétiques pour plusieurs objets.

Une demande peut indiquer :

• Nom d'objet de base de données.
• Propriétaire de l'objet.
• Nombre de lignes à générer.
• Conseils d'utilisation.
• Paramètres de génération pris en charge.

Les données générées ciblent les objets de base de données indiqués dans la demande. Les méthodes Java renvoient un résultat booléen qui indique si l'opération de base de données a réussi ; elles ne renvoient pas les lignes générées à l'appelant.

Prérequis pour la génération de données synthétiques

Avant de générer des données synthétiques :

• Assurez-vous que les objets de base de données cible existent.
• Accordez à l'utilisateur de base de données les privilèges requis pour accéder aux objets cible et les modifier.
• Configurez un profil AI pour un fournisseur qui prend en charge la génération de données synthétiques.
• Activer l'accès aux données Select AI.
• Répondez aux exigences de configuration et d'authentification propres au fournisseur.

Pour connaître les privilèges Select AI et la configuration de base de données requis, reportez-vous à Exécution des prérequis pour Select AI.

Générer des données pour les objets liés

Utilisez SyntheticDataBatchRequest lorsque vous devez générer des données pour plusieurs objets de base de données associés.

La demande par lots peut inclure plusieurs objets et leurs paramètres de génération. Utilisez ce formulaire lorsque les données générées doivent refléter les relations entre les objets spécifiés.

La demande prend en charge un nombre spécifié de lignes pour la génération de données synthétiques. La limite effective peut dépendre de la fonctionnalité de base de données sous-jacente, du fournisseur et des ressources de base de données.

En cas d'échec d'une opération de génération de batch ou d'objet unique, le kit SDK signale l'échec de la base de données ou de JDBC via SelectAIException.

Comportement des transactions pour la génération de données synthétiques

La génération de données synthétiques suit le comportement de transaction de la connexion JDBC utilisée par l'objet Profile.

Le kit SDK ne valide pas ou n'annule pas explicitement la transaction. En mode DbConnectionConfig, l'opération utilise la connexion JDBC appartenant au kit SDK. En mode DataSource, l'opération utilise une connexion empruntée au fichier DataSource géré par l'application.

Pour plus d'informations sur le comportement des transactions, reportez-vous à Connexion à la base de données Autonomous AI.

Pour plus d'informations sur les paramètres et exceptions pris en charge, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Extraire et mettre à jour des objets existants

Sélectionnez AI pour Java qui représente les profils, les conversations, les informations d'identification et les index vectoriels en tant qu'objets Java soutenus par la base de données.

Utilisez les méthodes d'extraction prises en charge pour obtenir des informations à jour sur les objets existants. Selon l'objet, les informations renvoyées peuvent inclure le nom, l'identificateur, la description, le statut, les attributs et les métadonnées.

Mettez à jour uniquement les attributs pris en charge par les API de base de données Select AI sous-jacentes. Une mise à jour ne remplace pas nécessairement l'objet complet. Extrayez l'objet lorsque l'application a besoin de l'état actuel de la base de données et vérifiez qu'il existe avant d'effectuer une opération propre à l'objet.

L'extraction de collection renvoie les objets accessibles à l'utilisateur de base de données connecté.

Pour connaître les méthodes d'extraction, les opérations de mise à jour, les objets de demande et les valeurs renvoyées pris en charge, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Supprimer des objets

Supprimez les profils, informations d'identification, conversations et index vectoriels dont l'application n'a plus besoin.

Avant de supprimer un objet :

• Vérifiez que l'objet n'est plus nécessaire.
• Vérifiez les profils dépendants, les informations d'identification, les conversations et les index vectoriels.
• Vérifiez que l'utilisateur de base de données connecté peut enlever l'objet.
• Conservez toutes les métadonnées ou configurations requises en dehors de la base de données.

Certaines méthodes de ressource fournissent une option de suppression forcée qui traite un objet déjà absent comme un résultat réussi. Utilisez cette option uniquement lorsque l'application peut accepter en toute sécurité un objet absent comme état final.

Pour connaître les méthodes de suppression, le comportement des dépendances et les exceptions propres à un objet, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Utiliser des API synchrones

Sélectionnez AI pour Java 1.0.0 fournit uniquement des API Java synchrones. Le kit SDK ne fournit pas d'API asynchrones ni d'opérations de profil de transmission en continu. Utilisez les API synchrones lorsque l'application peut attendre la fin de chaque opération de base de données avant de continuer.

Une méthode synchrone attend que l'opération de base de données se termine ou renvoie une erreur avant que le contrôle ne retourne à l'application appelante. Les opérations qui communiquent avec un fournisseur d'IA ou effectuent un traitement de base de données à longue durée d'exécution peuvent donc bloquer le thread appelant pendant une longue période.

Pour les applications multithread, utilisez le mode DataSource et définissez la taille du pool de connexions pour la simultanéité et la charge globale attendues. Pour plus d'informations sur les délais d'expiration des requêtes JDBC, reportez-vous à Comportement des transactions.

Remarque

Remarque : un délai d'expiration de requête JDBC ne configure pas les délais d'expiration de demande de fournisseur AI ni ne garantit l'annulation d'une demande de fournisseur déjà en cours.

Pour connaître les méthodes synchrones disponibles dans cette version, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Gestion des erreurs

Sélectionnez AI pour Java signale les erreurs de validation détectées localement via les exceptions Java standard et signale les échecs de base de données, JDBC, DBMS_CLOUD, DBMS_CLOUD_AI et de fournisseur via SelectAIException.

Le kit SDK valide les informations de demande qu'il peut vérifier avant le traitement JDBC. La base de données et le pilote JDBC valident les privilèges de base de données, l'état des ressources, les exigences de package, la configuration du fournisseur, l'accès réseau et d'autres exigences côté base de données.

Gérer les exceptions SDK

Le kit SDK utilise les exceptions suivantes pour les conditions d'erreur courantes :

SelectAIException hérite de Exception, ce qui en fait une exception vérifiée que les appelants doivent explicitement gérer ou déclarer. Les méthodes publiques soutenues par une base de données déclarent SelectAIException, y compris les méthodes de génération de profil et de cycle de vie, les opérations de conversation, les opérations d'index vectoriel, les opérations d'informations d'identification, les opérations DatabaseAdmin et la création et le nettoyage de connexions appartenant au kit SDK.

Pour connaître la déclaration d'exception pour une méthode individuelle, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Validation côté client et côté base de données

Le kit SDK valide les entrées prises en charge avant le traitement JDBC lorsqu'il peut déterminer la validité à partir de la demande Java.

Le kit SDK détecte des conditions telles que :

• Noms de ressource NULL ou vides.
• Invites et actions NULL ou vides, le cas échéant.
• Utilisateurs, hôtes ou privilèges non valides.
• Plages de ports non valides.
• Valeurs de délai d'expiration de requête négatives.
• Combinaisons d'informations d'identification non valides.
• Opérations sur des ressources qui n'ont pas encore été créées ou ouvertes.

Ces conditions génèrent normalement IllegalArgumentException ou IllegalStateException avant le traitement JDBC.

La base de données valide les conditions qui dépendent de la configuration de la base de données, des ressources ou des services distants. Ces conditions comprennent :

• Privilèges de base de données.
• Existence et état de la ressource.
• Exigences DBMS_CLOUD et DBMS_CLOUD_AI.
• Configuration du fournisseur.
• Validité des informations d'identification.
• Configuration d'ACL réseau.
• Règles de liste d'objets.
• Restrictions d'index vectoriels.
• Réponses du fournisseur d'IA distant.

Le kit SDK signale ces échecs côté base de données via SelectAIException.

Gérer une exception SelectAIException

Recherchez SelectAIException pour gérer les échecs des opérations Select AI sauvegardées dans la base de données.

Par exemple :

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());
}

Enregistrez suffisamment d'informations de diagnostic pour résoudre l'échec, mais n'enregistrez pas les mots de passe, les clés privées, les jetons ou les configurations d'informations d'identification complètes.

Pour connaître la hiérarchie des exceptions, les détails des erreurs et le comportement propre à l'opération, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Détails de l'erreur d'inspection

Utilisez les méthodes SelectAIException suivantes pour examiner les informations d'erreur disponibles :

Les échecs de fournisseur n'utilisent pas de type d'exception de fournisseur Java distinct. DBMS_CLOUD ou DBMS_CLOUD_AI reçoit normalement une défaillance de fournisseur, la signale via la base de données et les couches JDBC, et le kit SDK encapsule la défaillance dans SelectAIException.

Par exemple, une erreur HTTP renvoyée par un fournisseur AI peut apparaître comme une erreur Oracle telle que ORA-20400. Examinez les détails de l'erreur SelectAIException et la cause sous-jacente des informations de diagnostic disponibles pour l'opération.

Pour obtenir les méthodes SelectAIException complètes et les valeurs renvoyées, reportez-vous à Sélectionner AI pour la référence d'API Java (Javadoc).

Réessayer les opérations ayant échoué

Sélectionnez AI pour Java et ne relancez pas automatiquement les opérations ayant échoué.

Vous pouvez envisager de réessayer une opération de métadonnées en lecture seule après avoir confirmé qu'un échec de connexion était transitoire.

Ne retentez pas automatiquement les opérations de création, de mise à jour, de suppression, d'administration, de génération ou de discussion. La base de données ou le fournisseur AI a peut-être commencé à traiter la demande avant que l'application ne reçoive l'échec.

Avant de réessayer une opération qui peut modifier l'état de la base de données ou envoyer une demande à un fournisseur AI, vérifiez l'état de l'opération ou de la ressource en cours et vérifiez que la répétition de la demande est sûre.

Délai d'expiration et travail côté serveur

Le paramètre queryTimeoutSeconds configure le délai d'expiration de l'instruction JDBC. Elle ne configure pas nécessairement :

• Délai d'expiration d'adresse de fournisseur AI.
• Délai d'expiration de connexion ou de lecture HTTP.
• Annulation d'une demande de modèle distant.
• Annulation d'une opération DBMS_CLOUD_AI de longue durée.

Un délai d'attente JDBC peut empêcher l'application d'attendre l'instruction JDBC pendant que le traitement côté base de données ou côté fournisseur continue.

Attention : ne présumez pas qu'une opération d'expiration a arrêté le traitement. Avant de relancer l'opération, vérifiez l'état de la ressource ou de l'opération de base de données concernée et déterminez si le fournisseur Al peut toujours traiter la demande d'origine.

Pour plus d'informations, reportez-vous à la rubrique Comportement des transactions.

Résolution d'erreurs

En cas d'échec d'une opération :

1. Vérifiez le message SelectAIException, le code d'erreur Oracle, l'état SQL et la cause sous-jacente, le cas échéant.
2. Vérifiez que l'utilisateur de base de données dispose des privilèges requis.
3. Vérifiez que le profil, les informations d'identification, la conversation ou l'index vectoriel référencé existe et qu'il a l'état requis.
4. Vérifiez la configuration et les informations d'identification du fournisseur si nécessaire.
5. Vérifiez l'accès réseau et la configuration d'ACL lorsque le fournisseur ou la source de données l'exige.
6. Pour les défaillances du fournisseur, passez en revue l'erreur Oracle et les informations de diagnostic sous-jacentes renvoyées par l'intermédiaire de DBMS_CLOUD ou de DBMS_CLOUD_AI.
7. En cas d'expiration ou d'échec de connexion, vérifiez l'état de l'opération ou de la ressource avant de relancer la demande.

Pour obtenir des informations complètes sur SelectAIException, les exceptions propres à une méthode, le comportement de validation et la gestion des erreurs, reportez-vous à Sélectionner AI pour Java API Reference (Javadoc).

Sélectionner l'IA pour les exemples Java

Explorez les exemples Select AI for Java pour obtenir un exemple de code Java montrant comment configurer et utiliser les fonctionnalités Select AI for Java. Utilisez ces exemples avec Sélectionner AI pour la référence d'API Java (Javadoc) pour comprendre les classes, les méthodes et la configuration utilisées dans chaque workflow.