Lignes directrices de l'outil RAG HeatWave MySQL pour les agents d'IA générative

Avant d'utiliser un magasin de vecteurs HeatWave MySQL comme option de données pour les agents d'IA générative, assurez-vous de comprendre ce qui est pris en charge et d'effectuer toutes les tâches requises.

Bases de données prises en charge

Les agents d'IA générative prennent en charge les intégrations de vecteurs BYO à partir de :

• Systèmes de base de données HeatWave MySQL. Toute version d'innovation non obsolète.

• Bases de données HeatWave MySQL gérées par l'utilisateur exécutées sur des instances de calcul OCI

Prise en charge inter-région et interlocation

Lorsque vous utilisez des agents d'IA générative dans une région hébergée, vous pouvez vous connecter à une base de données HeatWave MySQL dans :

• Une autre région dans la même location. Activez la connectivité en créant une connexion aux outils de base de données dans la région où le service d'agent est disponible.
• Autre location. Activez la connectivité en créant une connexion aux outils de base de données dans la location où le service d'agent est disponible.

Pour configurer les paramètres de réseau, voir Exigences relatives au réseau (base de données inter-région et interlocation) à l'étape 3. Configurer les exigences en matière de réseau et de sécurité.

Pour créer une connexion, entrez la chaîne de connexion manuellement, comme décrit à l'étape 5. Créer des connexions au service d'outils de base de données.

En plus de permettre à l'utilisateur d'accéder à toutes les ressources des agents d'IA générative, comme décrit sous Ajout de politiques avant de pouvoir utiliser le service, vous devez créer un groupe dynamique avec accès au service d'outils de base de données.

1. Créer un groupe dynamique et ajouter la règle de correspondance suivante.

   ALL {resource.type='genaiagent'}

   Si vous avez besoin d'aide, voir Création d'un groupe dynamique.

2. Autorisez le groupe dynamique.

   • Écrivez les politiques suivantes, qui peuvent être utilisées avec le domaine d'identité par défaut :

     allow dynamic-group <dynamic-group-name> 
     to read database-tools-family in compartment <compartment-name>
     
     allow dynamic-group <dynamic-group-name> to use database-tools-connections in compartment <compartment-name>
     

   • Utilisez les politiques suivantes avec un domaine d'identité pas par défaut, en fournissant le nom de domaine Oracle Identity Cloud Service (IDCS) et le nom de groupe dynamique :

     allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
     to read database-tools-family in compartment <compartment-name>
     
     allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
     to use database-tools-connections in compartment <compartment-name>
     

allow any-user to read database-tools-family in compartment <compartment-name> where any {request.principal.type='genaiagent'}

allow any-user to use database-tools-connections in compartment <compartment-name> where any {request.principal.type='genaiagent'}

Effectuez ces tâches si vous n'avez pas encore configuré ou créé les ressources requises.

Exigences relatives au réseau

• Ajoutez la base de données HeatWave MySQL au sous-réseau privé d'un VCN.
• Configurez les propriétés suivantes pour la règle de trafic entrant du sous-réseau privé :
  • Type de source : CIDR
  • CIDR source : Bloc IPv4 CIDR du VCN (par exemple, 10.0.0.0/16)
  • Protocole IP : TCP
  • Intervalle de ports sources : Tous
  • Intervalle de ports de destination : 3306

Exigences en matière de réseau (base de données inter-région et interlocation)

• Configurez deux réseaux en nuage virtuels avec des blocs CIDR qui ne se chevauchent pas. Pour configurer les paramètres de réseau, voir Appairage distant de VCN.
• Dans le VCN de la base de données HeatWave MySQL, assurez-vous d'ajouter la règle de trafic entrant pour le bloc CIDR du VCN de la connexion aux outils de base de données afin d'accéder au port de base de données 3306.

Exemple de base de données inter-région : Vous pouvez vous connecter à une base de données située dans une région différente de celle où le service d'agents du service d'intelligence artificielle générative est exécuté. Exemple :

• Le service d'agent s'exécute dans la location A dans la région ORD.

• La base de données HeatWave MySQL est déployée dans la région PHX.

• Pour accéder à la base de données, configurez des passerelles de routage dynamique (DRG) dans les deux régions et configurez une connexion aux outils de base de données dans ORD pour la connexion à la base de données dans PHX.

Exemple de base de données interlocation : Vous pouvez vous connecter à une base de données située dans une location différente du service d'agents du service d'intelligence artificielle générative. Exemple :

• Le service d'agent s'exécute dans la location A dans la région ORD.

• La base de données HeatWave MySQL est déployée dans la location B dans la région PHX.

• Pour accéder à la base de données, configurez des passerelles de routage dynamique (DRG) dans les deux locations et configurez une connexion aux outils de base de données dans la location A (région OR) pour la connexion à la base de données dans la location B (région PHX).

La configuration réseau interlocation s'applique que le service de base de données et le service d'agent se trouvent dans la même région ou dans des régions différentes.

Exigences relatives à la sécurité de la chambre forte

Une chambre forte dans le service de chambre forte OCI est requise pour stocker les clés secrètes de la base de données HeatWave MySQL, telles que le mot de passe pour accéder à la base de données.

Créez la chambre forte dans le même compartiment que la connexion aux outils de base de données. Cela s'applique aux bases de données de la même région que le service d'agents d'IA générative et aux bases de données inter-région ou interlocation.

1. Créer une chambre forte.
2. Créez une clé de chiffrement principale.
3. Dans la chambre forte, créez une clé secrète pour le mot de passe de la base de données.

Dans la base de données HeatWave MySQL que vous avez créée pour l'utiliser avec les agents d'IA générative, créez une table de base de données avec certains champs obligatoires et configurez une procédure de base de données qui retourne les résultats de recherche vectorielle à partir des interrogations.

Table de base de données

Créez une table avec les champs suivants :

Champs obligatoires

• DOCID : ID affecté à chaque enregistrement ou document
• BODY : Contenu réel que l'agent doit rechercher
• VECTOR : Vecteur généré à partir d'un modèle d'intégration basé sur le contenu body

Champs facultatifs

• CHUNKID : ID du document fragmenté, au cas où le document serait supérieur à 512 jetons.
• URL : Référence d'URL pour le contenu, si disponible.
• TITLE : Titre du contenu body
• PAGE_NUMBERS : Numéros de page du contenu, s'il est disponible.

Conseil

Vous pouvez créer des intégrations de texte dans le service d'intelligence artificielle générative pour OCI.

Procédure de base de données

Configurez une procédure de base de données qui peut retourner des résultats de recherche vectorielle à partir de chaque interrogation. Voici les exigences :

Paramètres d'entrée

• p_query : Chaîne d'interrogation
• top_k : Nombre de premiers résultats

Type de valeur renvoyée

• JSON

Conditions requises

• Le modèle d'intégration que vous utilisez pour le champ d'interrogation de la fonction doit être identique au modèle d'intégration qui transforme le contenu BODY de la table en intégrations vectorielles.

• Les champs de retour de la fonction doivent correspondre aux champs obligatoires de la table (DOCID, BODY et SCORE) et facultatifs (CHUNKID, TITLE et URL).

  Le contenu BODY est traité par un modèle d'intégration pour produire un VECTOR pour chaque contenu. La fonction calcule les distances entre le vecteur d'interrogation et chaque VECTOR, retournant les rangées top_k. Le champ SCORE représente les distances entre le vecteur d'interrogation et VECTOR à partir de BODY.

• Si les noms de champ de retour de la fonction ne correspondent pas aux noms de champ de table, vous devez utiliser des alias dans la fonction.

Exemple

Voici un exemple de procédure de base de données :

-- Check if database exists, create it if not
CREATE DATABASE IF NOT EXISTS vector_store;
 
-- Switch to the database
USE vector_store;
 
-- Drop procedure if it exists (optional, for recreation)
DROP PROCEDURE IF EXISTS sample_search;
 
-- Create the procedure
CREATE PROCEDURE vector_store.sample_search(
  IN p_query TEXT,
  IN top_k INT UNSIGNED,
  OUT context JSON
)
BEGIN
  DECLARE i INT DEFAULT 0;
  DECLARE temp_json JSON DEFAULT JSON_ARRAY();
  -- Instead of using a temporary table, build the JSON directly
  SET i = 99; -- Start with highest scores
  -- Generate the top k results directly
  WHILE i >= (100 - top_k) AND i >= 0 DO
    SET temp_json = JSON_ARRAY_APPEND(temp_json, '$',
      JSON_OBJECT(
        'SCORE', FORMAT(i * 0.01, 2),
        'DOCID', i,
        'BODY', CONCAT('The sample text serves as a standardized sample for conducting comprehensive testing and performance evaluation in the environment.
Key Testing Objectives: Functionality verification, Performance assessment and System behavior analysis', i)
      )
    );
    SET i = i - 1;
  END WHILE;
  SET context = temp_json;
END

Dans OCI, utilisez le service d'outils de base de données pour créer des connexions réutilisables à une base de données HeatWave MySQL au moyen d'un point d'extrémité privé.

Effectuez ces tâches pour établir une connexion à la base de données.

1. Obtenez les informations suivantes, si vous ne disposez pas déjà des informations dont vous avez besoin pour créer une connexion.

   Dans la console, ouvrez le menu de navigation et sélectionnez Bases de données. Sous HeatWave MySQL, sélectionnez Systèmes de base de données.

   • Compartiment dans lequel le système de base de données a été créé
   • Nom du système de base de données
   • Pour une base de données inter-région ou interlocation : Adresse IP privée et port de base de données
   • Nom de la clé secrète de la chambre forte pour le mot de passe de l'utilisateur de la base de données

2. Dans le menu de navigation, sélectionnez Services de développement. Sous Outils de base de données, sélectionnez Connexions pour créer une connexion.

   1. Entrez un nom pour la connexion
   2. Sélectionnez le compartiment dans lequel créer la connexion.

      Nous recommandons de créer la connexion aux outils de base de données dans le même compartiment que la clé secrète de la chambre forte pour le mot de passe de l'utilisateur de la base de données.

   3. Utilisez l'une des options suivantes pour spécifier les informations de connexion.
      • Cliquez sur l'option Sélectionner une base de données pour sélectionner un système de base de données et laisser le service extraire les informations de connexion.
        1. Pour le service Database Cloud, sélectionnez MySQL Database.
        2. Sélectionnez le compartiment dans lequel le système de base de données a été créé.
        3. Sélectionnez le nom du système de base de données.
        4. Assurez-vous que le champ Chaîne de connexion est automatiquement alimenté avec la chaîne de connexion correcte. Il s'agit de l'adresse IP privée et du port de base de données du point d'extrémité principal du système de base de données. Exemple :

           mysql://10.0.1.156:3306

      • Utilisez l'option Entrer les informations sur la base de données pour une base de données inter-région ou interlocation et entrez les informations de connexion manuellement.
        1. Pour Type de connexion, sélectionnez MySQL.
        2. Dans Chaîne de connexion, entrez la chaîne de connexion.

3. Complétez le reste des informations pour créer une connexion d'outils de base de données à la base de données HeatWave MySQL au moyen d'un point d'extrémité privé.

   1. Entrez le nom d'utilisateur.

      Assurez-vous que l'utilisateur de base de données dispose des autorisations nécessaires et qu'il peut exécuter la procédure de base de données préparée à l'étape 4. Configurer une table de base de données et une procédure.

   2. Sélectionnez le compartiment dans lequel vous avez créé la clé secrète de chambre forte pour le mot de passe de l'utilisateur de la base de données.

      Si vous n'avez pas de clé secrète de chambre forte, sélectionnez Créer une clé secrète de mot de passe et créez une chambre forte. Créez ensuite une clé secrète pour stocker le mot de passe dans la chambre forte. Nous recommandons de créer la chambre forte et la clé secrète dans le même compartiment que la connexion aux outils de base de données.

   3. Activez l'option Accéder à la base de données au moyen d'un réseau privé et cliquez sur Sélectionner un point d'extrémité privé. Sélectionnez ensuite le compartiment et le point d'extrémité privé de la base de données.

      Si vous n'avez pas de point d'extrémité privé, sélectionnez Créer un point d'extrémité privé et créez un point d'extrémité à l'aide du même VCN et du même sous-réseau privé que la base de données.