Oracle Cloud Infrastructureドキュメント

RAGツールMySQL HeatWave MySQL生成AIエージェントのガイドライン

MySQL HeatWave MySQLデータベースからOCI Generative AI Agentsに独自の(BYO)ベクトル埋込みを導入できます。

このトピックでは、生成AIエージェントのデータ・オプションとしてMySQL HeatWave MySQLを使用するためのサポート情報、前提条件タスクおよびガイドラインについて説明します。提供される情報は、仮想クラウド・ネットワーク(VCNs)とサブネット、MySQL HeatWave MySQL、およびデータベース・ツール・サービスを使用した接続の作成に精通していることを前提としています

手順1.サポート情報の確認

MySQL HeatWave MySQLベクトル・ストアを生成AIエージェントのデータ・オプションとして使用する前に、サポートされている内容を理解し、必要なタスクを完了してください。

データベース・サポート

生成AIエージェントは、次の場所からのBYOベクトル埋込みをサポートしています。

  • MySQL HeatWave MySQLデータベース・システム。非推奨のイノベーション・バージョン。

  • OCIコンピュート・インスタンスで実行されているユーザー管理MySQL HeatWave MySQLデータベース

リージョン間およびクロステナンシのサポート
ホスト・リージョンで生成AIエージェントを使用する場合、次の場所にあるMySQL HeatWave MySQLデータベースに接続できます:
  • 同じテナンシ内の別のリージョン。エージェント・サービスが使用可能なリージョンにデータベース・ツール接続を作成して、接続を有効にします。
  • 別のテナンシエージェント・サービスが使用可能なテナンシにデータベース・ツール接続を作成して、接続を有効にします。

ネットワーク設定を設定するには、ステップ3のネットワーキング要件(クロスリージョンおよびクロステナンシ・データベース)を参照してください。ネットワークおよびセキュリティー要件を構成します。

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

ステップ2.動的グループおよびポリシーの追加

「サービスを使用する前にポリシーを追加」の説明に従って、すべての生成AIエージェント・リソースへのアクセス権をユーザーに付与することに加えて、データベース・ツールへのアクセス権を持つ動的グループを作成する必要があります。

  1. 動的グループを作成し、次の一致ルールを追加します。

    ALL {resource.type='genaiagent'}

    ヘルプが必要な場合は、動的グループの作成を参照してください。

  2. 動的グループに権限を付与します。

    • デフォルトのアイデンティティ・ドメインで使用できる次のポリシーを記述します。

      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>

    • Oracle Identity Cloud Service (IDCS)ドメイン名および動的グループ名を指定して、デフォルトではないアイデンティティ・ドメインで次のポリシーを使用します: 

      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'}
ステップ3.ネットワーキングおよびセキュリティ要件の構成

必要なリソースをまだ構成または作成していない場合は、これらのタスクを実行します。

ネットワーク要件
  • MySQL HeatWave MySQLデータベースをVCNのプライベート・サブネットに追加します。
  • プライベート・サブネットのイングレス・ルールに次のプロパティを設定します:
    • ソース・タイプ: CIDR
    • ソースCIDR: VCNのIPv4 CIDRブロック(10.0.0.0/16など)
    • IPプロトコル : TCP
    • ソース・ポート範囲: すべて
    • 宛先ポート範囲: 3306
ネットワーク要件(クロスリージョンおよびクロステナンシ・データベース)
  • 重複しないCIDRを持つ2つのVCNsを設定します。ネットワーク設定を構成するには、リモートVCNピアリングを参照してください。
  • MySQL HeatWave MySQLデータベースのVCNで、データベース・ツール接続のVCN CIDRのイングレス・ルールを追加して、データベース・ポート3306にアクセスしていることを確認します。

クロスリージョン・データベースの例: 生成AIエージェント・サービスが実行されているリージョンとは異なるリージョンにあるデータベースに接続できます。たとえば:

  • エージェント・サービスは、ORDリージョンのテナンシAで実行されています。

  • MySQL HeatWave MySQLデータベースは、PHXリージョンにデプロイされます。

  • データベースにアクセスするには、両方のリージョンで動的ルーティング・ゲートウェイ(DRG)を構成し、ORDでデータベース・ツール接続を設定してPHXでデータベースに接続します。

クロステナンシ・データベースの例: 生成AIエージェント・サービスから、別のテナンシにあるデータベースに接続できます。たとえば:

  • エージェント・サービスは、ORDリージョンのテナンシAで実行されています。

  • MySQL HeatWave MySQLデータベースは、PHXリージョンのテナンシBにデプロイされます。

  • データベースにアクセスするには、両方のテナンシで動的ルーティング・ゲートウェイ(DRG)を構成し、テナンシA (ORDリージョン)でデータベース・ツール接続を設定して、テナンシB (PHXリージョン)でデータベースに接続します。

クロステナンシ・ネットワーキング構成は、データベース・サービスとエージェント・サービスが同じリージョンにあるか、異なるリージョンにあるかに関係なく適用されます。

Vaultのセキュリティ要件

MySQL HeatWave MySQLデータベースのシークレット(データベースにアクセスするためのパスワードなど)を格納するには、OCI Vaultのボールトが必要です。

データベース・ツール接続と同じコンパートメントにボールトを作成します。これは、生成AIエージェント・サービスと同じリージョン内のデータベース、およびリージョン間またはクロステナンシ・データベースに適用されます。

  1. Create a vault.
  2. マスター暗号化キーを作成します。
  3. ボールトで、データベース・パスワードのシークレットを作成します。
ステップ4.データベース表およびプロシージャの設定

生成AIエージェントで使用するために作成したMySQL HeatWave MySQLデータベースで、特定の必須フィールドを含むデータベース表を作成し、問合せからベクトル検索結果を返すデータベース・プロシージャを設定します。

データベース表
次のフィールドを含む表を作成します。

必須フィールド

  • DOCID: 各レコードまたはドキュメントに割り当てられたID
  • BODY: エージェントが検索する実際のコンテンツ
  • VECTOR: bodyコンテンツに基づいて埋込みモデルから生成されるベクトル

オプション・フィールド

  • CHUNKID: チャンク・ドキュメントのID。ドキュメントが512トークンより大きい場合。
  • URL: コンテンツのURL参照(使用可能な場合)。
  • TITLE: bodyコンテンツのタイトル
  • PAGE_NUMBERS: コンテンツのページ番号(使用可能な場合)。
ヒント

OCI生成AIでテキスト埋込みを作成できます。
データベース・プロシージャ

各問合せからベクトル検索結果を返すことができるデータベース・プロシージャを設定します。要件は次のとおりです。

入力パラメータ

  • p_query: 問合せ文字列
  • top_k: 上位結果の数

返品タイプ

  • JSON

要件

  • ファンクションの問合せフィールドに使用する埋込みモデルは、表のBODYコンテンツをベクトル埋込みに変換する埋込みモデルと同じである必要があります。

  • ファンクションの戻りフィールドは、表の必須フィールド(DOCID、BODYおよびSCORE)およびオプション・フィールド(CHUNKID、TITLEおよびURL)と一致する必要があります。

    BODYコンテンツは埋込みモデルによって処理され、コンテンツごとにVECTORが生成されます。このファンクションは、問合せベクトルと各VECTORの間の距離を計算し、top_k行を返します。SCOREフィールドは、問合せベクトルとBODYからのVECTORの間の距離を表します。

  • ファンクションの戻りフィールド名が表フィールド名と一致しない場合は、ファンクションで別名を使用する必要があります。

例

データベース・プロシージャの例を次に示します。

-- 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
ステップ5.データベース・ツール接続の作成

OCIでは、データベース・ツール・サービスを使用して、プライベート・エンドポイントを介してMySQL HeatWave MySQLデータベースへの再利用可能な接続を作成します。

データベース接続を確立するには、次のタスクを実行します。

  1. 接続の作成に必要な情報がまだない場合は、次の情報を取得します。

    コンソールで、ナビゲーション・メニューを開き、「データベース」を選択します。「MySQL HeatWave MySQL」で、「DBシステム」を選択します。

    • DBシステムが作成されているコンパートメント
    • DBシステムの名前
    • クロスリージョン・データベースまたはクロステナンシ・データベースの場合: プライベートIPアドレスとデータベース・ポート
    • データベース・ユーザーのパスワードのボールト・シークレットの名前

  2. ナビゲーション・メニューで、「開発者サービス」を選択します。「データベース・ツール」で、「接続」を選択して接続を作成します。

    1. 接続の名前を入力します。
    2. 接続を作成するコンパートメントを選択してください。

      データベース・ユーザーのパスワードのボールト・シークレットと同じコンパートメントにデータベース・ツール接続を作成することをお薦めします。

    3. 次のいずれかのオプションを使用して、接続情報を指定します。
      • 「データベースの選択」オプションをクリックしてDBシステムを選択し、サービスで接続情報を取得します。
        1. 「データベース・クラウド・サービス」で、「MySQL Database」を選択します。
        2. DBシステムが作成されるコンパートメントを選択します。
        3. DBシステム名を選択します。
        4. 「接続文字列」フィールドに正しい接続文字列が自動的に入力されていることを確認します。これは、DBシステムのプライマリ・エンドポイントのプライベートIPアドレスおよびデータベース・ポートです。たとえば:

          mysql://10.0.1.156:3306

      • クロスリージョン・データベースまたはクロステナンシ・データベースの「データベース情報の入力」オプションを使用し、接続情報を手動で入力します。
        1. 「Connection type」で、MySQLを選択します。
        2. 「接続文字列」に、接続文字列を入力してください。

  3. 残りの情報を入力して、プライベート・エンドポイントを介してMySQL HeatWave MySQLデータベースへのデータベース・ツール接続を作成します。

    1. ユーザー名を入力します。

      データベース・ユーザーに必要な権限があり、ステップ4で準備したデータベース・プロシージャを実行できることを確認します。データベース表およびプロシージャの設定

    2. データベース・ユーザーのパスワードのボールト・シークレットを作成したコンパートメントを選択します。

      ボールト・シークレットがない場合は、「パスワード・シークレットの作成」を選択し、ボールトを作成します。次に、ボールトにパスワードを格納するシークレットを作成します。ボールトおよびシークレットは、データベース・ツール接続と同じコンパートメントに作成することをお薦めします。

    3. 「プライベート・ネットワークを介したデータベースへのアクセス」オプションを有効にし、「プライベート・エンドポイントの選択」をクリックします。次に、コンパートメントとデータベースへのプライベート・エンドポイントを選択します。

      プライベート・エンドポイントがない場合は、「プライベート・エンドポイントの作成」を選択し、データベースと同じVCNおよびプライベート・サブネットを使用してエンドポイントを作成します。