RAG-Tool HeatWave MySQL - Richtlinien für Generative AI Agents

Sie können Ihre eigenen (BYO-)Vektoreinbettungen aus einer HeatWave MySQL-Datenbank für OCI Generative AI Agents verwenden.

In diesem Thema werden Supportinformationen, erforderliche Aufgaben und Richtlinien für die Verwendung von HeatWave MySQL als Datenoption für Generative AI Agents beschrieben. Die bereitgestellten Informationen setzen voraus, dass Sie mit virtuellen Cloud-Netzwerken (VCNs) und Subnetzen, HeatWave MySQL, vertraut sind und Verbindungen mit dem Datenbanktoolservice erstellen.

Schritt 1. Supportinformationen prüfen

Bevor Sie einen Vektorspeicher HeatWave MySQL als Datenoption für Generative AI Agents verwenden, stellen Sie sicher, dass Sie verstehen, was unterstützt wird, und alle erforderlichen Aufgaben ausführen.

Datenbankunterstützung

Generative AI Agents unterstützt BYO-Vektoreinbettungen von:

  • HeatWave MySQL-Datenbanksysteme. Jede nicht veraltete Innovationsversion.
  • Vom Benutzer verwaltete HeatWave MySQL-Datenbanken, die auf OCI Compute-Instanzen ausgeführt werden

Regions- und mandantenübergreifende Unterstützung
Wenn Sie Generative AI Agents in einer gehosteten Region verwenden, können Sie eine Verbindung zu einer HeatWave MySQL-Datenbank herstellen in:
  • Eine andere Region innerhalb desselben Mandanten. Aktivieren Sie die Konnektivität, indem Sie eine Verbindung zu Datenbanktools in der Region erstellen, in der der Agent-Service verfügbar ist.
  • Weiterer Mandant. Aktivieren Sie die Konnektivität, indem Sie eine Verbindung zu Datenbanktools in dem Mandanten erstellen, in dem der Agent-Service verfügbar ist.

Informationen zum Einrichten der Netzwerkeinstellungen finden Sie unter Netzwerkanforderungen (regionsübergreifende und mandantenübergreifende Datenbank) in Schritt 3. Konfigurieren Sie Netzwerk- und Sicherheitsanforderungen.

To create a connection, enter the connect string manually as described in Step 5. Create Database Tools Connections.

Schritt 2. Dynamische Gruppe und Policys hinzufügen

Sie müssen nicht nur Benutzerzugriff auf alle Generative AI Agents-Ressourcen erteilen, wie unter Policys hinzufügen, bevor Sie den Service verwenden können beschrieben, sondern auch eine dynamische Gruppe mit Zugriff auf Datenbanktools erstellen.

  1. Erstellen Sie eine dynamische Gruppe, und fügen Sie die folgende Vergleichsregel hinzu.

    ALL {resource.type='genaiagent'}

    Weitere Informationen finden Sie unter Dynamische Gruppe erstellen.

  2. Erteilen Sie der dynamischen Gruppe Berechtigungen.

    • Schreiben Sie die folgenden Policys, die mit der Standardidentitätsdomain verwendet werden können:

      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>
      
    • Verwenden Sie die folgenden Policys mit einer Identitätsdomain, die nicht der Standard ist und den Oracle Identity Cloud Service-(IDCS-)Domainnamen und den Namen der dynamischen Gruppe angibt:

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

Wenn nach dem Schreiben der vorhergehenden Policys nicht auf die Verbindung zu den Datenbanktools zugegriffen werden kann, kann es zu einem Problem mit dem Sessiontoken des Resource Principals kommen. Verwenden Sie die folgenden Policy-Einstellungen, ohne sich auf dynamische Gruppen zu verlassen:

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'}
Schritt 3. Netzwerk- und Sicherheitsanforderungen konfigurieren

Führen Sie diese Aufgaben aus, wenn Sie die erforderlichen Ressourcen noch nicht konfiguriert oder erstellt haben.

Netzwerkanforderungen
  • Fügen Sie die Datenbank HeatWave MySQL zum privaten Subnetz eines VCN hinzu.
  • Richten Sie die folgenden Eigenschaften für die Ingress-Regel des privaten Subnetzes ein:
    • Quelltyp: CIDR
    • Source CIDR: The VCN's IPv4 CIDR Block (such as 10.0.0.0/16)
    • IP-Protokoll: TCP
    • Quellportbereich: Alle
    • Zielportbereich: 3306
Netzwerkanforderungen (regionale und mandantenübergreifende Datenbank)
  • Richten Sie zwei VCNs mit sich nicht überschneidenden CIDRs ein. Informationen zum Konfigurieren der Netzwerkeinstellungen finden Sie unter Remote-VCN-Peering.
  • Stellen Sie im VCN der HeatWave-MySQL-Datenbank sicher, dass Sie die Ingress-Regel für das VCN-CIDR der Datenbanktoolverbindung hinzufügen, um auf den Datenbankport 3306 zuzugreifen.

Beispiel für regionsübergreifende Datenbanken: Sie können eine Verbindung zu einer Datenbank herstellen, die sich in einer anderen Region befindet als der Generative AI Agents-Service. Beispiel:

  • Der Agent-Service wird im Mandanten A in der ORD-Region ausgeführt.

  • Die Datenbank HeatWave MySQL wird in der PHX-Region bereitgestellt.

  • Um auf die Datenbank zuzugreifen, konfigurieren Sie dynamische Routinggateways (DRGs) in beiden Regionen und richten eine Verbindung zu Datenbanktools in ORD ein, um eine Verbindung zur Datenbank in PHX herzustellen.

Beispiel für mandantenübergreifende Datenbanken: Sie können eine Verbindung zu einer Datenbank herstellen, die sich in einem anderen Mandanten als der Generative AI Agents-Service befindet. Beispiel:

  • Der Agent-Service wird im Mandanten A in der ORD-Region ausgeführt.

  • Die Datenbank HeatWave MySQL wird in Mandant B in der PHX-Region bereitgestellt.

  • Um auf die Datenbank zuzugreifen, konfigurieren Sie dynamische Routinggateways (DRGs) in beiden Mandanten und richten eine Verbindung zu Datenbanktools in Mandant A (ORD-Region) ein, um eine Verbindung zur Datenbank in Mandant B (PHX-Region) herzustellen.

Die mandantenübergreifende Netzwerkkonfiguration gilt unabhängig davon, ob sich der Datenbankservice und der Agent-Service in derselben Region oder in verschiedenen Regionen befinden.

Vault-Sicherheitsanforderungen

Ein Vault in OCI Vault ist erforderlich, um Secrets für die Datenbank HeatWave MySQL zu speichern, z.B. das Kennwort für den Zugriff auf die Datenbank.

Erstellen Sie den Vault in demselben Compartment wie die Verbindung mit den Datenbanktools. Dies gilt für Datenbanken in derselben Region wie der Generative AI Agents-Service sowie für regions- oder mandantenübergreifende Datenbanken.

  1. Vault erstellen.
  2. Masterverschlüsselungsschlüssel erstellen.
  3. Erstellen Sie im Vault ein Secret für das Datenbankkennwort.
Schritt 4. Datenbanktabellen und Prozeduren einrichten

Erstellen Sie in der Datenbank HeatWave MySQL, die Sie zur Verwendung mit Generative AI Agents erstellt haben, eine Datenbanktabelle mit bestimmten Pflichtfeldern, und richten Sie eine Datenbankprozedur ein, die Vektorsuchergebnisse aus Abfragen zurückgibt.

Datenbanktabelle
Erstellen Sie eine Tabelle mit den folgenden Feldern:

Pflichtfelder

  • DOCID: Eine ID, die jedem Datensatz oder Dokument zugewiesen ist
  • BODY: Der tatsächliche Inhalt, nach dem der Agent suchen soll
  • VECTOR: Der Vektor, der aus einem Einbettungsmodell basierend auf dem body-Inhalt generiert wird

Optionale Werte

  • CHUNKID: Eine ID für das blockierte Dokument, falls das Dokument größer als 512 Token ist.
  • URL: Eine URL-Referenz für den Inhalt, sofern verfügbar.
  • TITLE: Der Titel des Inhalts body
  • PAGE_NUMBERS: Die Seitenzahlen für den Inhalt, sofern verfügbar.
Tipp

Sie können Texteinbettungen erstellen in OCI Generative AI.
Datenbankprozedur

Richten Sie eine Datenbankprozedur ein, die Vektorsuchergebnisse aus jeder Abfrage zurückgeben kann. Hier sind die Anforderungen:

Eingabeparameter

  • p_query: Die Abfragezeichenfolge
  • top_k: Anzahl der Top-Ergebnisse

Rückgabetyp

  • JSON

Anforderungen

  • Das Einbettungsmodell, das Sie für das Abfragefeld der Funktion verwenden, muss mit dem Einbettungsmodell identisch sein, das den BODY-Inhalt der Tabelle in Vektoreinbettungen transformiert.

  • Die Rückgabefelder der Funktion müssen mit den erforderlichen Feldern (DOCID, BODY und SCORE) und optionalen Feldern (CHUNKID, TITLE und URL) der Tabelle übereinstimmen.

    Der BODY-Inhalt wird von einem Einbettungsmodell verarbeitet, um eine VECTOR für jeden Inhalt zu erstellen. Die Funktion berechnet die Abstände zwischen dem Abfragevektor und jedem VECTOR und gibt die top_k-Zeilen zurück. Das Feld SCORE stellt die Entfernungen zwischen dem Abfragevektor und dem VECTOR von BODY dar.

  • Wenn die Rückgabefeldnamen der Funktion nicht mit den Tabellenfeldnamen übereinstimmen, müssen Sie Aliasnamen in der Funktion verwenden.

Beispiel

Beispiel für eine Datenbankprozedur:

-- 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
Schritt 5. Datenbanktoolverbindungen erstellen

Verwenden Sie in OCI den Datenbanktools-Service, um wiederverwendbare Verbindungen zu einer HeatWave MySQL-Datenbank über einen privaten Endpunkt zu erstellen.

Führen Sie diese Aufgaben aus, um eine Datenbankverbindung herzustellen.

  1. Rufen Sie die folgenden Informationen ab, wenn Sie noch nicht über die Informationen verfügen, die Sie zum Erstellen einer Verbindung benötigen.

    Rufen Sie in der Konsole das Navigationsmenü auf, und wählen Sie Datenbanken aus. Wählen Sie unter HeatWave MySQL die Option DB-Systeme.

    • Compartment, in dem das DB-System erstellt wird
    • Name des DB-Systems
    • Für eine regions- oder mandantenübergreifende Datenbank: Die private IP-Adresse und der Datenbankport
    • Name des Vault Secrets für das Kennwort des Datenbankbenutzers
  2. Wählen Sie im Navigationsmenü Entwicklerservices aus. Wählen Sie unter Datenbanktools die Option Verbindungen aus, um eine Verbindung zu erstellen.

    1. Geben Sie einen Namen für die Verbindung ein.
    2. Wählen Sie das Compartment, in dem die Verbindung erstellt werden soll.

      Es wird empfohlen, die Verbindung zu den Datenbanktools in demselben Compartment wie das Vault Secret für das Kennwort des Datenbankbenutzers zu erstellen.

    3. Verwenden Sie eine der folgenden Optionen, um die Verbindungsinformationen anzugeben.
      • Klicken Sie auf die Option Datenbank auswählen, um ein DB-System auszuwählen und den Service die Verbindungsinformationen abrufen zu lassen.
        1. Wählen Sie unter Database Cloud Service die Option MySQL Database aus.
        2. Wählen Sie das Compartment aus, in dem das DB-System erstellt wird.
        3. Wählen Sie den DB-Systemnamen aus.
        4. Stellen Sie sicher, dass das Feld Verbindungszeichenfolge automatisch mit der richtigen Verbindungszeichenfolge ausgefüllt wird. Dies ist die private IP-Adresse und der Datenbankport des primären Endpunkts des DB-Systems. Beispiel:

          mysql://10.0.1.156:3306

      • Verwenden Sie die Option Datenbankinformationen eingeben für eine regions- oder mandantenübergreifende Datenbank, und geben Sie die Verbindungsinformationen manuell ein.
        1. Wählen Sie unter Verbindungstyp die Option MySQL aus.
        2. Geben Sie unter Verbindungszeichenfolge die Verbindungszeichenfolge ein.
  3. Geben Sie die restlichen Informationen ein, um eine Datenbanktoolverbindung zur Datenbank HeatWave MySQL über einen privaten Endpunkt zu erstellen.

    1. Geben Sie den Benutzernamen ein

      Ensure that the database user has the necessary permissions, and can run the database procedure that's prepared in Step 4. Set Up a Database Table and a Procedure.

    2. Wählen Sie das Compartment aus, in dem Sie das Vault Secret für das Kennwort des Datenbankbenutzers erstellt haben.

      Wenn Sie kein Vault Secret haben, wählen Sie Kennwort-Secret erstellen aus, und erstellen Sie einen Vault. Erstellen Sie dann ein Secret, um das Kennwort im Vault zu speichern. Es wird empfohlen, den Vault und das Secret in demselben Compartment wie die Verbindung mit den Datenbanktools zu erstellen.

    3. Aktivieren Sie die Option Über ein privates Netzwerk auf Datenbank zugreifen, und klicken Sie auf Privaten Endpunkt auswählen. Wählen Sie dann das Compartment und den privaten Endpunkt für die Datenbank aus.

      Wenn Sie keinen privaten Endpunkt haben, wählen Sie Privaten Endpunkt erstellen aus, und erstellen Sie einen Endpunkt mit demselben VCN und privaten Subnetz wie die Datenbank.