Diretrizes do MySQL HeatWave MySQL da Ferramenta RAG para Agentes de IA Generativa

Antes de usar um armazenamento de vetores MySQL do MySQL HeatWave como opção de dados para Agentes de IA Generativa, certifique-se de entender o que é suportado e concluir as tarefas necessárias.

Suporte ao Banco de Dados

O Generative AI Agents oferece suporte a incorporações de vetores BYO de:

• Sistemas de banco de dados MySQL HeatWave MySQL. Qualquer versão de Inovação não obsoleta.

• Bancos de dados MySQL HeatWave MySQL gerenciados pelo usuário em execução em instâncias do OCI Compute

Suporte entre regiões e entre tenancies

Ao usar Agentes de IA Generativa em uma região hospedada, você pode estabelecer conexão com um banco de dados MySQL do MySQL HeatWave em:

• Outra região na mesma tenancy. Ative a conectividade criando uma conexão de ferramentas de banco de dados na região em que o serviço do agente está disponível.
• Outra tenancy. Ative a conectividade criando uma conexão de ferramentas de banco de dados na tenancy em que o serviço do agente está disponível.

Para configurar as definições de rede, consulte Requisitos de Rede (banco de dados entre regiões e entre tenancies) na Etapa 3. Configure Networking e Security Requirements.

Para criar uma conexão, informe a string de conexão manualmente, conforme descrito na Etapa 5. Criar Conexões do Serviço Database Tools.

Além de conceder ao usuário acesso a todos os recursos do Generative AI Agents conforme descrito em Adicionando Políticas Antes de Usar o Serviço, você precisa criar um grupo dinâmico com acesso ao serviço Database Tools.

1. Crie um grupo dinâmico e adicione a seguinte regra de correspondência.

   ALL {resource.type='genaiagent'}

   Se precisar de ajuda, consulte Criando um Grupo Dinâmico.

2. Dê permissões ao grupo dinâmico.

   • Grave as seguintes políticas, que podem ser usadas com o domínio de identidades Padrão:

     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>
     

   • Use as seguintes políticas com um domínio de identidades não Padrão, fornecendo o nome do domínio do IDCS (Oracle Identity Cloud Service) e o nome do 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'}

Execute essas tarefas se você ainda não tiver configurado ou criado os recursos necessários.

Requisitos de Rede

• Adicione o banco de dados MySQL do MySQL HeatWave à sub-rede privada de uma VCN.
• Configure as seguintes propriedades para a regra de entrada da sub-rede privada:
  • Origem: CIDR
  • CIDR de Origem: O Bloco IPv4 CIDR da VCN (como 10.0.0.0/16)
  • Protocolo IP: TCP
  • Intervalo de Portas de Origem: Tudo
  • Intervalo de Portas de Destino: 3306

Requisitos de Rede (banco de dados entre regiões e entre tenancies)

• Configure duas VCNs com CIDRs não sobrepostos. Para configurar as definições de rede, consulte Pareamento Remoto de VCN.
• Na VCN do banco de dados do MySQL HeatWave MySQL, certifique-se de adicionar a regra de entrada do CIDR da VCN da conexão das ferramentas de banco de dados para acessar a porta do banco de dados 3306.

Exemplo de banco de dados entre regiões: Você pode estabelecer conexão com um banco de dados que esteja em uma região diferente da onde o serviço Generative AI Agents está sendo executado. Por exemplo:

• O serviço do agente está em execução na tenancy A na região ORD.

• O banco de dados MySQL HeatWave MySQL é implantado na região PHX.

• Para acessar o banco de dados, configure gateways de roteamento dinâmico (DRGs) em ambas as regiões e configure uma conexão de ferramentas de banco de dados no ORD para estabelecer conexão com o banco de dados no PHX.

Exemplo de banco de dados entre tenancies: Você pode estabelecer conexão com um banco de dados localizado em uma tenancy diferente do serviço Generative AI Agents. Por exemplo:

• O serviço do agente está em execução na tenancy A na região ORD.

• O banco de dados MySQL HeatWave MySQL é implantado na tenancy B na região PHX.

• Para acessar o banco de dados, configure gateways de roteamento dinâmico (DRGs) em tenancies e configure uma conexão de ferramentas de banco de dados na tenancy A (região ORD) para estabelecer conexão com o banco de dados na tenancy B (região PHX).

A configuração de rede entre tenancies se aplica independentemente de o serviço de banco de dados e o serviço de agente estarem na mesma região ou em regiões diferentes.

Requisitos de Segurança do Vault

Um vault no OCI Vault é necessário para armazenar segredos do banco de dados MySQL do MySQL HeatWave, como a senha para acessar o banco de dados.

Crie o vault no mesmo compartimento da conexão de ferramentas de banco de dados. Isso se aplica a bancos de dados na mesma região do serviço Generative AI Agents e a bancos de dados entre regiões ou entre tenancies.

1. Criar um vault.
2. Crie uma chave de criptografia principal.
3. No vault, crie um segredo para a senha do banco de dados.

No banco de dados MySQL HeatWave MySQL que você criou para usar com Agentes de IA Generativa, crie uma tabela de banco de dados com determinados campos obrigatórios e configure um procedimento de banco de dados que retorne resultados de pesquisa vetorial de consultas.

Tabela de Banco de Dados

Crie uma tabela com os seguintes campos:

Campos Obrigatórios

• DOCID: Um id atribuído a cada registro ou documento
• BODY: O conteúdo real que você deseja que o agente pesquise
• VECTOR: O vetor gerado de um modelo de incorporação com base no conteúdo body

Campos opcionais

• CHUNKID: Um id para o documento em blocos, caso o documento seja maior que 512 tokens.
• URL: Uma referência de URL para o conteúdo, se disponível.
• TITLE: O título do conteúdo body
• PAGE_NUMBERS: Os números de página do conteúdo, se disponível.

Dica

Você pode criar incorporações de texto na OCI Generative AI.

Procedimento do banco de dados

Configure um procedimento de banco de dados que possa retornar resultados de pesquisa vetorial de cada consulta. Aqui estão os requisitos:

Parâmetros de Entrada

• p_query: A string de consulta
• top_k: Número de resultados principais

Tipo de Devolução

• JSON

Requisitos

• O modelo de incorporação que você usa para o campo de consulta da função deve ser o mesmo que o modelo de incorporação que transforma o conteúdo BODY da tabela em incorporações de vetores.

• Os campos de retorno da função devem corresponder aos campos obrigatórios da tabela (DOCID, BODY e SCORE) e opcionais (CHUNKID, TITLE e URL).

  O conteúdo BODY é processado por um modelo de incorporação para produzir um VECTOR para cada conteúdo. A função calcula as distâncias entre o vetor de consulta e cada VECTOR, retornando as linhas top_k. O campo SCORE representa as distâncias entre o vetor de consulta e o VECTOR do BODY.

• Se os nomes dos campos de retorno da função não corresponderem aos nomes dos campos da tabela, você deverá usar aliases na função.

Exemplo

Veja a seguir um exemplo de procedimento de banco de dados:

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

Na OCI, use o serviço Database Tools para criar conexões reutilizáveis com um banco de dados MySQL do MySQL HeatWave por meio de um ponto final privado.

Execute estas tarefas para estabelecer uma conexão de banco de dados.

1. Obtenha as informações a seguir, se você ainda não tiver as informações necessárias para criar uma conexão.

   Na Console, abra o menu de navegação e selecione Bancos De Dados. Em MySQL HeatWave MySQL, selecione Sistemas de BD.

   • Compartimento no qual o sistema de banco de dados é criado
   • Nome dos sistemas de banco de dados
   • Para um banco de dados entre regiões ou entre tenancies: O endereço IP privado e a porta do banco de dados
   • Nome do segredo do vault para a senha do usuário do banco de dados

2. No Menu de Navegação, selecione Serviços ao Desenvolvedor. Em Database Tools, selecione Conexões para criar uma conexão.

   1. Digite um nome para a conexão.
   2. Selecione o compartimento no qual criar a conexão.

      Recomendamos criar a conexão de ferramentas de banco de dados no mesmo compartimento do segredo do vault para a senha do usuário do banco de dados.

   3. Use uma das opções a seguir para especificar as informações de conexão.
      • Clique na opção Selecionar banco de dados para selecionar um sistema de banco de dados e permitir que o serviço recupere as informações de conexão.
        1. Para Serviço de nuvem de banco de dados, selecione MySQL Database.
        2. Selecione o compartimento no qual o sistema de banco de dados é criado.
        3. Selecione o nome do sistema do BD.
        4. Certifique-se de que o campo String de conexão seja preenchido automaticamente com a string de conexão correta. Este é o endereço IP privado do ponto final principal do sistema de banco de dados e a porta do banco de dados. Por exemplo:

           mysql://10.0.1.156:3306

      • Use a opção Especificar informações do banco de dados para um banco de dados entre regiões ou entre tenancies e especifique as informações de conexão manualmente.
        1. Para Tipo de conexão, selecione MySQL.
        2. Em String da conexão, informe a string de conexão.

3. Preencha o restante das informações para criar uma conexão de ferramentas de banco de dados com o banco de dados MySQL do MySQL HeatWave por meio de um ponto final privado.

   1. Informe o nome de usuário.

      Certifique-se de que o usuário do banco de dados tenha as permissões necessárias e possa executar o procedimento do banco de dados que está preparado na Etapa 4. Configurar uma Tabela de Banco de Dados e um Procedimento.

   2. Selecione o compartimento no qual você criou o segredo do vault para a senha do usuário do banco de dados.

      Se você não tiver um segredo de vault, selecione Criar segredo de senha e crie um vault. Em seguida, crie um segredo para armazenar a senha no vault. Recomendamos criar o vault e o segredo no mesmo compartimento da conexão de ferramentas de banco de dados.

   3. Ative a opção Acessar banco de dados por meio de uma rede privada e clique em Selecionar ponto final privado. Em seguida, selecione o compartimento e o ponto final privado para o banco de dados.

      Se você não tiver um ponto final privado, selecione Criar ponto final privado e crie um ponto final usando a mesma VCN e sub-rede privada do banco de dados.