Directrices de RAG Tool HeatWave MySQL para agentes de IA generativa

Antes de utilizar un almacén de vectores HeatWave MySQL como opción de datos para agentes de IA generativa, asegúrese de comprender lo que está soportado y de completar las tareas necesarias.

Soporte de base de datos

Los agentes de IA generativa admiten incrustaciones de vectores BYO de:

• Sistemas de base de datos de HeatWave MySQL. Cualquier versión de innovación no en desuso.

• Bases de datos HeatWave MySQL gestionadas por el usuario que se ejecutan en instancias de OCI Compute

Soporte entre regiones y entre arrendamientos

Al utilizar agentes de IA generativa en una región alojada, puede conectarse a una base de datos HeatWave MySQL en:

• Otra región dentro del mismo arrendamiento. Active la conectividad creando una conexión de herramientas de base de datos en la región en la que el servicio de agente está disponible.
• Otro arrendamiento. Active la conectividad creando una conexión de herramientas de base de datos en el arrendamiento donde el servicio de agente está disponible.

Para configurar la configuración de red, consulte Requisitos de red (base de datos entre regiones y entre arrendamientos) en el paso 3. Configure los requisitos de red y seguridad.

Para crear una conexión, introduzca manualmente la cadena de conexión como se describe en el Step 5. Cree conexiones de Database Tools.

Además de proporcionar al usuario acceso a todos los recursos de agentes de IA generativa, como se describe en Adición de políticas antes de poder utilizar el servicio, debe crear un grupo dinámico con acceso a las herramientas de base de datos.

1. Crear un grupo dinámico y agregar la siguiente regla de coincidencia.

   ALL {resource.type='genaiagent'}

   Si necesita ayuda, consulte Creación de un grupo dinámico.

2. Permita el grupo dinámico.

   • Escriba las siguientes políticas, que se pueden utilizar con el dominio de identidad por defecto:

     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>
     

   • Utilice las siguientes políticas con un dominio de identidad no por defecto, que proporciona el nombre de dominio de Oracle Identity Cloud Service (IDCS) y el nombre de grupo dinámico:

     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'}

Realice estas tareas si aún no ha configurado ni creado los recursos necesarios.

Requisitos de red

• Agregue la base de datos HeatWave MySQL a la subred privada de una VCN.
• Configure las siguientes propiedades para la regla de entrada de la subred privada:
  • Tipo de origen: CIDR
  • CIDR de origen: bloque IPv4 CIDR de la VCN (como 10.0.0.0/16)
  • Protocolo IP: TCP
  • Rango de puertos de origen: Todo
  • Rango de puertos de destino: 3306

Requisitos de red (base de datos entre regiones y entre arrendamientos)

• Configure dos redes virtuales en la nube con CIDR que no se solapen. Para configurar los valores de red, consulte Intercambio de tráfico de VCN remoto.
• En la VCN de la base de datos HeatWave MySQL, asegúrese de agregar la regla de entrada para el CIDR de la VCN de la conexión de herramientas de base de datos para acceder al puerto de base de datos 3306.

Ejemplo de base de datos entre regiones: puede conectarse a una base de datos que esté en una región diferente de la que se está ejecutando el servicio Generative AI Agents. Por ejemplo:

• El servicio de agente se está ejecutando en el arrendamiento A en la región ORD.

• La base de datos HeatWave MySQL se despliega en la región PHX.

• Para acceder a la base de datos, configure gateways de enrutamiento dinámico (DRG) en ambas regiones y configure una conexión de herramientas de base de datos en ORD para conectarse a la base de datos en PHX.

Ejemplo de base de datos entre arrendamientos: puede conectarse a una base de datos ubicada en un arrendamiento diferente del servicio Agentes de IA generativa. Por ejemplo:

• El servicio de agente se está ejecutando en el arrendamiento A en la región ORD.

• La base de datos HeatWave MySQL se despliega en el arrendamiento B en la región PHX.

• Para acceder a la base de datos, configure gateways de enrutamiento dinámico (DRG) en ambos arrendamientos y configure una conexión de herramientas de base de datos en el arrendamiento A (región ORD) para conectarse a la base de datos en el arrendamiento B (región PHX).

La configuración de red entre arrendamientos se aplica independientemente de si el servicio de base de datos y el servicio de agente están en la misma región o en regiones diferentes.

Requisitos de seguridad de Vault

Se necesita un almacén en OCI Vault para almacenar secretos para la base de datos HeatWave MySQL, como la contraseña para acceder a la base de datos.

Cree el almacén en el mismo compartimento que la conexión de herramientas de base de datos. Esto se aplica a las bases de datos de la misma región que el servicio Agentes de IA generativa y a las bases de datos entre regiones o entre arrendamientos.

1. Crear un almacén.
2. Cree una clave del cifrado maestra.
3. En el almacén, cree un secreto para la contraseña de la base de datos.

En la base de datos HeatWave MySQL que ha creado para utilizarla con agentes de IA generativa, cree una tabla de base de datos con determinados campos necesarios y configure un procedimiento de base de datos que devuelva los resultados de búsqueda vectorial de las consultas.

Tabla de base de datos

Cree una tabla con los siguientes campos:

Campos obligatorios

• DOCID: ID asignado a cada registro o documento
• BODY: contenido real que desea que busque el agente
• VECTOR: vector generado a partir de un modelo de embebido basado en el contenido body

Campos opcionales

• CHUNKID: ID del documento fragmentado, en caso de que el documento tenga más de 512 tokens.
• URL: referencia de URL para el contenido, si está disponible.
• TITLE: título del contenido de body
• PAGE_NUMBERS: los números de página del contenido, si están disponibles.

Consejo

Puede crear incrustaciones de texto en OCI Generative AI.

Procedimiento de base de datos

Configurar un procedimiento de base de datos que pueda devolver resultados de búsqueda vectorial de cada consulta. Estos son los requisitos:

Parámetros de Entrada

• p_query: cadena de consulta
• top_k: número de resultados principales

Tipo de Retorno

• JSON

Requisitos

• El modelo de embebido que utilice para el campo de consulta de la función debe ser el mismo que el modelo de embebido que transforma el contenido BODY de la tabla en embebidas vectoriales.

• Los campos de retorno de la función deben coincidir con los campos obligatorios (DOCID, BODY y SCORE) y opcionales (CHUNKID, TITLE y URL).

  El contenido BODY se procesa mediante un modelo de embebido para producir un VECTOR para cada contenido. La función calcula las distancias entre el vector de consulta y cada VECTOR, devolviendo las filas top_k. El campo SCORE representa las distancias entre el vector de consulta y VECTOR de BODY.

• Si los nombres de campo de retorno de la función no coinciden con los nombres de campo de tabla, debe utilizar alias en la función.

Ejemplo

A continuación se muestra un ejemplo de un procedimiento de base de datos:

-- 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

En OCI, utilice el servicio Database Tools para crear conexiones reutilizables a una base de datos HeatWave MySQL a través de un punto final privado.

Realice estas tareas para establecer una conexión a la base de datos.

1. Obtenga la siguiente información, si aún no tiene la información que necesita para crear una conexión.

   En la consola, abra el menú de navegación y seleccione Bases de datos. En HeatWave MySQL, seleccione Sistemas de base de datos.

   • Compartimento en la que se crea el servicio de base de datos
   • Nombre del sistema de base de datos
   • Para una base de datos entre regiones o entre arrendamientos: dirección IP privada y puerto de base de datos
   • Nombre del secreto de almacén para la contraseña del usuario de la base de datos

2. En el menú de navegación, seleccione Developer Services. En Herramientas de base de datos, seleccione Conexiones para crear una conexión.

   1. Introduzca un nombre para la conexión.
   2. Seleccione el compartimento en la que desea crear la conexión.

      Recomendamos crear la conexión de herramientas de base de datos en el mismo compartimento que el secreto de almacén para la contraseña del usuario de base de datos.

   3. Utilice una de las siguientes opciones para especificar la información de conexión.
      • Haga clic en la opción Seleccionar base de datos para seleccionar un sistema de base de datos y permitir que el servicio recupere la información de conexión.
        1. En Servicio de base de datos en la nube, seleccione MySQL Database.
        2. Seleccione el compartimento en el que se crea el servicio de base de datos.
        3. Seleccione el nombre del sistema de base de datos.
        4. Asegúrese de que el campo Cadena de conexión se rellene automáticamente con la cadena de conexión correcta. Esta es la dirección IP privada del punto final principal del sistema de base de datos y el puerto de base de datos. Por ejemplo:

           mysql://10.0.1.156:3306

      • Utilice la opción Introducir información de base de datos para una base de datos entre regiones o entre arrendamientos e introduzca la información de conexión manualmente.
        1. Para Tipo de conexión, seleccione MySQL.
        2. En Cadena de conexión, introduzca la cadena de conexión.

3. Complete el resto de la información para crear una conexión de herramientas de base de datos a la base de datos HeatWave MySQL a través de un punto final privado.

   1. Introduzca el nombre de usuario.

      Asegúrese de que el usuario de la base de datos tenga los permisos necesarios y de que pueda ejecutar el procedimiento de base de datos preparado en el Step 4. Configuración de una tabla de base de datos y un procedimiento.

   2. Seleccione el compartimento en el que ha creado el secreto de almacén para la contraseña del usuario de la base de datos.

      Si no tiene un secreto de almacén, seleccione Crear secreto de contraseña y cree un almacén. A continuación, cree un secreto para almacenar la contraseña en el almacén. Recomendamos crear el almacén y el secreto en el mismo compartimento que la conexión de herramientas de base de datos.

   3. Active la opción Acceder a la base de datos mediante una red privada y haga clic en Seleccionar punto final privado. A continuación, seleccione el compartimento y el punto final privado en la base de datos.

      Si no tiene un punto final privado, seleccione Crear punto final privado y cree un punto final con la misma VCN y subred privada que la base de datos.