Outil RAG HeatWave MySQL Directives pour les agents d'IA générative

Avant d'utiliser une banque de vecteurs HeatWave MySQL en tant qu'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.

Prise en charge des bases de données

Les agents d'IA générative prennent en charge l'intégration 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 OCI Compute

Prise en charge inter-région et inter-locations

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 de 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.
• Une autre location. Activez la connectivité en créant une connexion aux outils de base de données dans la location dans laquelle le service d'agent est disponible.

Pour configurer les paramètres réseau, reportez-vous à la section Networking Requirements (Cross-region and Cross-tenancy database) de l'étape 3. Configuration des 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'Step 5. Créez des connexions Database Tools.

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

1. Créez un groupe dynamique et ajoutez la règle suivante de mise en correspondance.

   ALL {resource.type='genaiagent'}

   Si vous avez besoin d'aide, reportez-vous à Création d'un groupe dynamique.

2. Accordez des droits d'accès au groupe dynamique.

   • Ecrivez les stratégies 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 stratégies suivantes avec un domaine d'identité non par défaut, en indiquant 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.

Configuration réseau requise

• 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 entrante du sous-réseau privé :
  • Type de source : CIDR
  • Source CIDR: The VCN's IPv4 CIDR Block (such as 10.0.0.0/16)
  • Protocole IP : TCP
  • Plage de ports source : Tout
  • Plage de ports de destination: 3306

Configuration réseau requise (base de données inter-région et inter-location)

• Configurez deux réseaux cloud virtuels avec des CIDR qui ne se chevauchent pas. Pour configurer les paramètres réseau, reportez-vous à Appairage VCN distant.
• Dans le VCN de la base de données HeatWave MySQL, veillez à ajouter la règle entrante pour le CIDR VCN de la connexion des 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 qui se trouve dans une autre région que celle où le service Agents d'IA générative est exécuté. Par exemple :

• Le service d'agent est en cours d'exécution dans la location A de 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 dans les deux régions et configurez une connexion aux outils de base de données dans ORD pour vous connecter à la base de données dans PHX.

Exemple de base de données inter-locations : vous pouvez vous connecter à une base de données située dans une autre location que le service Agents d'IA générative. Par exemple :

• Le service d'agent est en cours d'exécution dans la location A de 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 ORD) afin de vous connecter à la base de données dans la location B (région PHX).

La configuration réseau inter-location s'applique indépendamment du fait 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 de sécurité du coffre

Un coffre dans OCI Vault est requis pour stocker les clés secrètes de la base de données HeatWave MySQL, par exemple le mot de passe permettant d'accéder à la base de données.

Créez le coffre dans le même compartiment que la connexion Database Tools. Cela s'applique aux bases de données de la même région que le service Generative AI Agents, ainsi qu'aux bases de données inter-région ou inter-locations.

1. Créer un coffre.
2. Création d'une clé de cryptage maître.
3. Dans le coffre, créez une clé secrète correspondant au mot de passe de 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 renvoie des résultats de recherche vectorielle à partir de requêtes.

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é, si le document est 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, le cas échéant.

Conseil

Vous pouvez créer des incorporations de texte dans OCI Generative AI.

Procédure de base de données

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

Paramètres d'entrée

• p_query : chaîne de requête
• top_k : nombre de premiers résultats

Type de retour

• JSON

Exigences

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

• Les champs renvoyés par 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 afin de produire une valeur VECTOR pour chaque contenu. La fonction calcule les distances entre le vecteur de requête et chaque élément VECTOR, renvoyant les lignes top_k. Le champ SCORE représente les distances entre le vecteur de requête 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 Database Tools pour créer des connexions réutilisables à une base de données HeatWave MySQL via une adresse privée.

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

1. Obtenez les informations suivantes, si vous ne disposez pas déjà des informations nécessaires 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 processus de base de données est créé
   • Nom du système de base de données
   • Pour une base de données inter-région ou inter-location : adresse IP privée et port de base de données
   • Nom de la clé secrète de coffre pour le mot de passe de l'utilisateur de base de données

2. Dans le menu de navigation, sélectionnez Services de développeur. Sous Database Tools, sélectionnez Connexions pour créer une connexion.

   1. Entrez le nom de la connexion.
   2. Sélectionnez le compartiment dans lequel la connexion doit être créée.

      Nous vous recommandons de créer la connexion aux outils de base de données dans le même compartiment que la clé secrète de coffre pour le mot de passe de l'utilisateur de 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 Service cloud Database, sélectionnez MySQL Database.
        2. Sélectionnez le compartiment dans lequel le réseau de base de données est créé.
        3. Sélectionnez le nom de système de base de données.
        4. Assurez-vous que le champ Chaîne de connexion est automatiquement renseigné avec la chaîne de connexion correcte. Adresse IP privée et port de base de données de l'adresse principale du système de base de données. Par exemple :

           mysql://10.0.1.156:3306

      • Utilisez l'option Entrer les informations de base de données pour une base de données inter-région ou inter-location et entrez les informations de connexion manuellement.
        1. Pour le type de connexion, sélectionnez MySQL.
        2. Entrez la chaîne de connexion dans 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 via une adresse privée.

   1. Entrez le nom d'utilisateur.

      Assurez-vous que l'utilisateur de base de données dispose des droits d'accès nécessaires et peut exécuter la procédure de base de données préparée à l'Step 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 coffre pour le mot de passe de l'utilisateur de base de données.

      Si vous n'avez pas de clé secrète de coffre, sélectionnez Créer une clé secrète de mot de passe et créez un coffre. Créez ensuite une clé secrète pour stocker le mot de passe dans le coffre. Nous vous recommandons de créer le coffre 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 via un réseau privé et cliquez sur Sélectionner une adresse privée. Sélectionnez ensuite le compartiment et l'adresse privée dans la base de données.

      Si vous ne disposez pas d'adresse privée, sélectionnez Créer une adresse privée et créez une adresse à l'aide du même VCN et du même sous-réseau privé que la base de données.