生成AIエージェントのRAGツール・オブジェクト・ストレージ・ガイドライン

次の項を参照して、生成AIエージェントのRAGツール用のオブジェクト・ストレージ・データを準備します。

一般的なガイドライン

オブジェクト・ストレージにアップロードする前に、生成AIエージェント・データ・ソースのデータを準備するには、次のガイドラインに従います:

データ・ソース: 生成AIエージェントのデータは、ファイルとしてオブジェクト・ストレージ・バケットにアップロードする必要があります。
バケット数: データ・ソースごとに許可されるバケットは1つのみです。
サポートされているファイル・タイプ: PDFおよびtxtファイルのみがサポートされます。
ファイル・サイズ制限: 各ファイルは100MB以下にする必要があります。
PDFコンテンツ: PDFファイルには、イメージ、チャートおよび参照表を含めることができますが、これらは8MBを超えないようにする必要があります。
チャートの準備: ラベル付き軸の2次元であるかぎり、チャートに特別な準備は必要ありません。モデルは、明示的な説明なしにチャートに関する質問に答えることができます。
表の準備: 複数の行および列を含む参照表を使用します。たとえば、エージェントは「制限」ページで表を読み取ることができます。
URL: PDFドキュメントに存在するすべてのハイパーリンクが抽出され、チャット・レスポンスにハイパーリンクとして表示されます。
データの準備ができていません: データがまだ使用できない場合は、データ・ソースの空のフォルダを作成し、後で移入します。このようにして、フォルダの移入後にデータをソースに取り込むことができます。

ノート

続行する前に、次のオブジェクト・ストレージ権限を設定してください。

オブジェクト・ストレージ・ファイルへのユーザー・アクセス
長時間実行ジョブのオブジェクト・ストレージ・ファイルへのデータ取込みジョブ・アクセス

権限については、アクセスの取得を参照してください。

表の強化の理解

RAGツールの機能である強化された表理解は、PDF表データに埋め込まれた回答を使用して問合せに対するレスポンスの精度を向上させることを目的としています。これらのテーブルが処理され、含まれている情報に合わせて、より正確で関連性の高い応答が生成されます。一般に、RAGツールはテーブルを読み取ることができます。RAGツールで、表の理解を深めて表を読み取るには、表に次の機能があることを確認します。

表のすべてのセルは、最初の行のヘッダー名を含め、他のセルから表示可能な行またはオブジェクトの境界で区切られます。
最初の列を含むすべての列にヘッダー名があります。
各表には、複数の列と複数の行があり、ヘッダー名を含む行は除外されます。

強化された表理解で取り込まれた表は、データの取込み時にリストされます。メッセージの例:

Count of tables that support enhanced table understanding in following PDFs:
      - enhanced_table_test_data/2025_Report1.pdf has 4 tables processed successfully
      - enhanced_table_test_data/2025_Report2.pdf has 3 tables processed successfully
      - enhanced_table_test_data/2025_Report3.pdf has 3 tables processed successfully

メタデータ・フィルタリングによるレスポンスの拡張

事前定義されたメタデータを使用して、チャット中にフィルタを適用します。フィルタが適用されると、チャット・セッションでのエージェントの検索は、メタデータに関連付けられているデータファイルに制限され、モデルがコンテンツ・スコープに関連する回答を生成し、エージェントのレスポンスの正確性と関連性を高めるのに役立ちます。

次のステップでは、メタデータ・フィルタリング機能の使用方法の概要を説明します。ワークフローの概要を理解したら、概要ステップの後の項でユースケースの詳細を確認します。

テキスト・エディタで、メタデータ・スキーマを作成します。このスキーマは、使用可能にするフィルタに必要です。JSON形式でスキーマを記述します。ファイルに_metadata_schema.jsonという名前を付けます。
例:
```
{
    "metadataSchema": [
        {
            "name": "publication_year",
            "type": "integer"
        },
        {
            "name": "title",
            "type": "string"
        }
	]
}
```
ステップ1で作成した_metadata_schema.jsonファイルを、ナレッジ・ベースのデータファイルを含むオブジェクト・ストレージ・バケットのルート・レベルにアップロードします。
JSONファイルを作成して、データ・ファイルを事前定義済のメタデータに関連付け、メタデータ値を指定します。
例:
```
{
    "metadataAttributes": {
        "publication_year": 2020
    }
} 
```
1つ以上のデータファイルまたはバケット内のすべてのファイルをメタデータに関連付けることができます。選択したオプションに使用するJSONファイル名の表記規則の詳細は、メタデータ・フィルタ・オプション(ファイル名および場所)を参照してください。
ステップ3で作成したJSONファイルを、ナレッジ・ベースのデータファイルを含むオブジェクト・ストレージ・バケットにアップロードします。各オプションについて、ファイルを階層の正しい場所に保存してください。
ナレッジ・ベースを作成します。データ・ストア・タイプとして「オブジェクト・ストレージ」を選択し、取込みジョブを自動的に開始するオプションを選択します。
データファイルが収集されると、生成AIエージェントは、チャットで選択できるメタデータ名と値のリストを作成します。収集したメタデータ名および値を表示するには、生成AIエージェントでのナレッジ・ベースの詳細の取得を参照してください。
ステップ5で作成したナレッジ・ベースを選択して、RAGツールを使用してエージェントを作成します。エージェントで、エンドポイントを自動的に作成するオプションを選択します。ヘルプが必要な場合は、エージェントの作成およびRAGツールの作成を参照してください。
チャット・ウィンドウで、1つ以上の事前定義済メタデータ・フィルタを追加し、適用する値を選択します。チャットでのメタデータ・フィルタの使用を参照してください。

ノート

ユースケース用のメタデータJSONファイルの準備、およびチャット・セッションでのメタデータ・フィルタの追加および適用方法についてさらに学習するには、次の項を参照してください。

メタデータ・フィルタ・オプション(ファイル名および場所)

最適な次の方法を1つ以上選択します。


Method	ファイル名と保存先	使用方法
ファイル名を指定せずに、バケット内のすべてのファイルのメタデータを含めます。	オブジェクト・ストレージのルート・レベルで`_common.metadata.json`ファイルを作成します。	このファイルは、バケット内のすべてのファイルに共通するメタデータに使用します。この方法は、オブジェクト間でのメタデータの重複入力を回避するのに役立ちます。
1つのファイルで、バケット内の各ファイルのメタデータ・エントリを作成し、ファイル名を含めます。	オブジェクト・ストレージのルート・レベルで`_all.metadata.json`ファイルを作成します。	多数のファイルがあり、すべてのファイル名を含む1つのファイルを作成すると、ファイルごとに1つのメタデータ・ファイルを作成するよりも便利です。
バケット内の各ファイルのメタデータ・ファイルを作成します。	ファイル・レベルで、ファイルごとに`<file-name>.metadata.json`ファイルを作成します。 `<file-name>`は、バケット内のデータファイルの名前と一致する必要があります。	この方法は、メタデータがファイルごとに異なり、メタデータ・ファイルを作成するファイルが多くない場合、またはメタデータ・ファイルの作成を自動化する場合に使用します。
オブジェクト・ストレージ・メタデータ・ヘッダーを各ファイルに追加します。	各ファイルのオブジェクト・ストレージ・メタデータ・プロパティを介してメタデータ・ヘッダーを追加します。	含めるメタデータ・プロパティがほとんどない場合は、この方法を使用します。ファイルの更新と管理が簡単で、メタデータ・ヘッダーの更新が困難なため、JSONファイルでは他の方法を使用することをお薦めします。

すべてのメソッドで、_metadata_schema.jsonというメタデータ・スキーマ・ファイルをオブジェクト・ストレージ・バケットのルート・レベルで定義する必要があります。

必要なメタデータ・ファイルを保存する階層の例を次に示します。

オブジェクト・ストレージ内のメタデータ・ファイルの階層を示すイメージです。bucket_rootには、_all.metadata.json、_common.metadata.json、_metadata_schema.json、file_0.pdf、file_0.pdf.metadata.json、folder_1およびfolder_2というファイルがあります。次に、folder_1にはfile_1.pdfおよびfile_1.pdf.metadata.jsonが含まれ、folder_2にはfile_2.pdfおよびfile_2.pdf.metadata.jsonが含まれます。

メタデータJSONファイルの例

次のステップでは、例を使用して、メタデータJSONファイルのフォーマット方法を示します。メタデータ・フィルタリングの制限も参照してください。

_metadata_schema.jsonというメタデータ・スキーマ・ファイルを作成し、オブジェクト・ストレージのルート・レベルで保存します。例:

{
    "metadataSchema": [
        {
            "name": "field_1",
            "type": "integer"
        },
        {
            "name": "field_2",
            "type": "string"
        },
        {
            "name": "field_3",
            "type": "list_of_string"
        },
        {
            "name": "field_4",
            "type": "double"
        }  
    ]
}

各メタデータ・フィルタには、nameおよびtypeがあります。

typeに使用できる値は、integer、string、list_of_stringおよびdoubleです。

例:

{
    "metadataSchema": [
        {
            "name": "rating",
            "type": "double"
        },
        {
            "name": "publication_year",
            "type": "integer"
        },
        {
            "name": "title",
            "type": "string"
        },
        {
            "name": "topic",
            "type": "list_of_string"
        }
    ]
}

OpenSearch、integerのサンプル索引マッピング:

"publication_year": {
  "type": "integer"         
}

OpenSearch、stringのサンプル索引マッピング:

"title": {
  "type": "text",
  "fields": {
      "keyword": {
          "type": "keyword"
      },
      "search_as_you_type": {
          "type": "search_as_you_type"
      }
   }
}

OpenSearch、list_of_stringのサンプル索引マッピング:

"publishers": {
    "type": "text",
    "fields": {
    "keyword": {
        "type": "keyword"
    },
    "search_as_you_type": {
        "type": "search_as_you_type"
    }
  }
}

OpenSearch、doubleのサンプル索引マッピング:

"rating": {
  "type": "double"
}

(オプション)バケット内のすべてのファイルに共通するメタデータ用に、_commmon.metadata.jsonというJSONファイルを作成します。例:

{
    "metadataAttributes": {
        "field_1": value_1,
        "field_2": value_2,
        "field_3": value_3,
        ......,
        "field_n": value_n
    }
}

例:

{
    "metadataAttributes": {
        "rating": 3.3,
        "publication_year": "2020",
        "topic": [
            "cooking",
            "health",
            "gardening"
        ]
    }
}

(オプション)_all.metadata.jsonというJSONファイルを作成します。この1つのファイルに、各ファイルのメタデータを名前で追加します。例:

{
    "folder_1/file_1.pdf" : {
        "metadataAttributes": {
            "field_1": value_1,
            "field_2": value_2,
            "field_3": value_3,
            ......,
            "field_n": value_n
        }
    },
    "folder_2/file_2.pdf": {
        "metadataAttributes": {
            "field_1": value_1,
            "field_2": value_2,
            "field_3": value_3,
            ......,
            "field_n": value_n
        }
    }
}

(オプション)ファイルの<file-name>.metadata.jsonというJSONファイルを作成して、バケット内のファイルのメタデータを個別に追加します。
<file-name>は、バケット内のデータファイルの名前と一致する必要があります。たとえば、データファイルfile1.pdfは、JSONファイルfile1.pdf.metadata.jsonで定義されたメタデータに関連付けられます。
```
{
    "metadataAttributes": {
        "field_1": value_1,
        "field_2": value_2,
        "field_3": value_3
    }
}
```

ノート

ナレッジ・ベース・データの収集後にメタデータ・フィールドを変更または削除することはできません。許可された制限に新規フィールドを追加できます。フィールドを削除または更新するには、ナレッジ・ベースを再作成します。

チャットでのメタデータ・フィルタの使用

次の手順では、必要なメタデータ・スキーマとオプションのメタデータ・フィルタJSONファイル、ナレッジ・ベース、およびRAGツールとエンドポイントを含むエージェントを作成していることを前提としています。

Start a chat.
右側のパネルで、「メタデータ・フィルタ」を展開し、「フィルタの追加」を選択して1つ以上のフィルタを追加します。
1. 「フィルタの追加」パネルで、「フィルタの追加」を選択し、メニューを使用して、事前定義済のメタデータ・フィルタを名前、条件演算子およびメタデータ値で選択します。
  
  たとえば、フィルタtopic contains cookingを追加できます。ここで、topicはメタデータ・フィルタ名、containsは条件演算子、cookingはメタデータ値です。
2. 必要に応じて、「フィルタの追加」を選択してフィルタを追加します。
  
  フィルタを削除するには、行の最後にあるXアイコンを選択します。
3. 完了したら、「追加」を選択します。
  
  追加されたフィルタは、チャット・ウィンドウの「メタデータ・フィルタ」の下に表示されます。フィルタの横のチェックマークは、フィルタが適用されることを意味します。フィルタを適用しない場合は、フィルタの横にあるチェック・ボックスの選択を解除します。
メッセージを入力して「送信」を選択し、会話を開始します。

チャット・セッション中に、メタデータ・フィルタを追加または削除し、フィルタをクリアまたは適用して会話を続行できます。

メタデータ・フィルタリングの制限


内容	制限
`_all.metadata.json`内のエントリの最大数	10,000
ファイルごとに指定できるメタデータ・フィールドの最大数	20
`list_of_string type`内のアイテムの最大数	10
`list_of_string`型の個々のアイテムの最大長	50
メタデータ・キーの最大長(文字数)	25
メタデータ値の最大長(文字)	50

オブジェクト・ストレージ・メタデータ・ヘッダーへのメタデータの追加

オブジェクト・ストレージ・バケットを作成し、OCI生成AIエージェントでRAGレスポンスのソース・ファイルをアップロードします。オプションで、引用のために各ファイルにカスタムURLを追加します。

コンソールのナビゲーション・バーで、生成AIエージェントをホストするリージョン(米国中西部(シカゴ)など)を選択します。選択するリージョンがわからない場合は、生成AIエージェントを使用するリージョンを参照してください。
ナビゲーション・メニューを開き、「ストレージ」を選択します。「オブジェクト・ストレージおよびアーカイブ・ストレージ」で、「バケット」を選択します。
バケットまたは使用するバケットを含むコンパートメントを作成するコンパートメントを選択します。このコンパートメントにオブジェクト・ストレージ・リソースを追加するには、すでに次の権限が必要です。
```
allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
```
バケットを作成するには、次のステップに従います:
1. 「Create Bucket」を選択します。
2. バケットのリージョンに一意の名前を入力します。
3. 他のフィールドでは、「詳細」リンクを選択し、データに適用するオプションを選択します。オブジェクト・ストレージ・バケットの作成も参照してください。
4. 「作成」を選択します。
  デフォルトでは、新しいバケットはプライベートです。バケットの作成後に、そのバケットの表示を変更できます。
使用するバケットの名前を選択します。
バケットの詳細ページの「オブジェクト」で、「アップロード」を選択します。
(オプション)「オプションのヘッダーおよびメタデータの表示」を選択し、次の値を選択して入力します。
- タイプ: メタデータ
- 名前: gaas-metadata-filtering-field-<metadata-name>
- 値: <metadata-value>
重要

メタデータ・フィルタリングが機能するには、メタデータ「名前」に接頭辞gaas-metadata-filtering-field-を使用する必要があります。
次に、オブジェクト・ストレージによってメタデータ名の前にopc-meta-が付けられるため、ヘッダーはopc-meta-gaas-metadata-filtering-field-<metadata-name>として表示されます。

たとえば、publication_yearという名前のメタデータを追加するには、gaas-metadata-filtering-field-publication_yearという名前のメタデータ・ヘッダーを追加します。このファイルの詳細を取得すると、メタデータ名はopc-meta-gaas-metadata-filtering-field-publication_yearと表示されます。

リスト値には、次の形式を使用します。

_LIST_OF_STRING_|list_value_1|list_value_2。_LIST_OF_STRING_は固定で、各リスト項目はパイプの'|'文字で区切られます。この形式は、値のリストとしてデコードされます: {list_value_1, list_value_2}
データ・ソースに1つ以上のファイルを追加し、「アップロード」を選択します。
ノート
- 既存のオブジェクトのmetadataプロパティは更新できません。かわりに、ファイルをコピーし、そのファイルに新しいメタデータを追加してから、古いファイルを削除できます。
- オブジェクト・ストレージのナレッジ・ベース・データとそのメタデータの取込み後にメタデータ・フィルタリングを使用して、エージェントとのチャット会話にフィルタを追加できます。フィルタの追加について学習するには、生成AIエージェントでのエージェントとのチャットのステップ11を参照してください。ナレッジ・ベースでデータを取り込んだ後に、メタデータ値の詳細を表示することもできます。生成AIエージェントでのナレッジ・ベースの詳細の取得のメタデータ・リソースを参照してください。

カスタムURLを使用したオブジェクト・ストレージ・バケットへのデータの追加

コンソールのナビゲーション・バーで、生成AIエージェントをホストするリージョン(米国中西部(シカゴ)など)を選択します。選択するリージョンがわからない場合は、生成AIエージェントを使用するリージョンを参照してください。
ナビゲーション・メニューを開き、「ストレージ」を選択します。「オブジェクト・ストレージおよびアーカイブ・ストレージ」で、「バケット」を選択します。
バケットまたは使用するバケットを含むコンパートメントを作成するコンパートメントを選択します。このコンパートメントにオブジェクト・ストレージ・リソースを追加するには、すでに次の権限が必要です。
```
allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
```
バケットを作成するには、次のステップに従います:
1. 「Create Bucket」を選択します。
2. バケットのリージョンに一意の名前を入力します。
3. 他のフィールドでは、「詳細」リンクを選択し、データに適用するオプションを選択します。オブジェクト・ストレージ・バケットの作成も参照してください。
4. 「作成」を選択します。
  デフォルトでは、新しいバケットはプライベートです。バケットの作成後に、そのバケットの表示を変更できます。
使用するバケットの名前を選択します。
バケットの詳細ページの「オブジェクト」で、「アップロード」を選択します。
(オプション)「オプションのヘッダーおよびメタデータの表示」を選択し、次の値を選択して入力します。
- タイプ: メタデータ
- 名前: customized_url_source
- 値: <Custom-URL-for-the-file>
重要

引用リンクのオーバーライドが機能するには、「名前」: customized_url_sourceを使用する必要があります。
データ・ソースに1つ以上のファイルを追加し、「アップロード」を選択します。

ノート

ステップ7でオブジェクトにcustomized_url_sourceメタデータを追加した場合、このカスタムURLは、このオブジェクトに対してアップロードするすべてのファイルに適用されます。既存のオブジェクトのmetadataプロパティは更新できません。かわりに、ファイルをコピーし、そのファイルに新しいメタデータを追加してから、古いファイルを削除できます。customized_url_sourceメタデータでファイルを追加または更新するには、OCI CLIを使用します。「引用へのカスタムURLの割当て」を参照してください。

ノート

ベータ版の顧客:

ベータ・フェーズでナレッジ・ベースを作成した場合は、URL処理機能が動作するように、データ・ソースを削除して再作成する必要がある場合があります。

召喚へのカスタムURLの割当て

エージェントが応答にRAGを使用すると、引用を取得できます。デフォルトでは、引用はファイルが格納されているオブジェクト・ストレージを指しています。参照されているファイルではなくURLを参照するには、そのファイルのmetadataオブジェクトにカスタムURLを追加します。

このトピックでは、OCI CLIを使用してmetadataオブジェクトを追加または更新する方法について説明します。

環境またはクラウド・シェルでOCI CLIを起動します。コマンドに慣れるために、まずCloud Shellで試すことをお薦めします。
コマンドライン・インタフェースの開始を参照してください。
カスタムURLを追加するファイルのオブジェクト名を取得します。
```
oci os object list --bucket-name <the-bucket-name> 
--file <the-file-name>
```
出力例:
```
"data": [
    {
      "archival-state": null,
      "etag": "xxx",
      "md5": "xxx==",
      "name": "<the-object-name>",
      "size": 1117630,
      "storage-tier": "Standard",
      "time-created": "2025-03-12T22:21:26.991000+00:00",
      "time-modified": "2025-03-12T22:38:10.217000+00:00"
    },
Other objects are listed similarly after this comma.
```
コンソールでオブジェクト名を検索することもできます。バケット詳細ページで、オブジェクトの「アクション」メニュー(3つのドット)を選択し、「オブジェクト詳細の表示」を選択して名前をコピーします。

ノート

ファイルがフォルダにある場合、ファイル名とそのオブジェクト名は異なります。たとえば、file1.pdfという名前のファイルの場合、そのオブジェクト名はfolder1/file1.pdfになります。それ以外の場合、ファイル名とそのオブジェクト名は同じです。
ファイルを現在の作業ディレクトリにダウンロードします。
ファイルのmetadataオブジェクトを追加または更新するには、ファイルを新しいmetadataオブジェクトを持つ同じファイルに置き換えます。そのため、最初にファイルを現在の作業ディレクトリにコピーします。
```
oci os object get 
--bucket-name <the-bucket-name> 
--file <the-file-name>
--name <the-object-name>
```
現在のファイルのmetadataオブジェクト値を検索します。
```
oci os object head 
--bucket-name <the-bucket-name> 
--name <the-object-name>
```
出力例:
```
{
 some data

  "opc-client-request-id": "xxx",
  "opc-meta-key1": "value1",
  "opc-meta-key2": "value2",
  "opc-request-id": "xxx",
 ...
}
```
この例は、metadataオブジェクト値が'{"key1":"value1","key2":"value2"}'であることを示しています。metadata名は接頭辞opc-meta-で保存されますが、次のステップでmetadata名を追加するときに、この接頭辞を追加する必要はありません。この接頭辞は、各metadata名に自動的に追加されます。

オブジェクト・ストレージにあるファイルを現在の作業ディレクトリにあるものと同じファイルに置き換え、新しいmetadataオブジェクトを追加します。

現在のメタデータを保持し、カスタムURLの名前と値'{"customized_url_source":"<the-custom-url>"をmetadataオブジェクトに追加するには:

oci os object put 
--bucket-name <the-bucket-name> 
--file <the-file-name> 
--name <the-object-name>
--force --metadata 
'{"customized_url_source":"<the-custom-url>",
"<existing-metadata-name-1>":"<existing-metadata-value-1>"
"<existing-metadata-name-2>":"<existing-metadata-value-2>"}'

たとえば、ステップ4の例に表示されているmetadataの名前と値を保持するには:

oci os object put 
--bucket-name <the-bucket-name> 
--file <the-file-name> 
--name <the-object-name>
--force --metadata 
'{"customized_url_source":"<the-custom-url>",
"key1":"value1",
"key2":"value2"}'

既存のmetadataオブジェクトをカスタムURLのみを含めるように置換するには、次のコマンドを実行します

oci os object put 
--bucket-name <the-bucket-name> 
--file <the-file-name> 
--name <the-object-name>
--force --metadata '{"customized_url_source":"<the-custom-url>"}'

カスタムURLのmetadataオブジェクトが置換されていることを確認します。

oci os object head 
--bucket-name <the-bucket-name> 
--name <the-object-name>

出力例:

{
 some data

  "opc-meta-customized_url_source": "some-new-link",
 ...
}

重要

デフォルトの引用をオーバーライドするmetadataオブジェクトには、customized_url_sourceという名前が必要です。
customized_url_sourceという名前のmetadataオブジェクトを1つ持つことができます。
各customized_url_sourceにはURLを1つのみ含めることができます。
ステップ5のコマンドは、現在のmetadataオブジェクトの値を置き換えるため、metadataオブジェクトの追加と更新の両方に有効です。
--metadataオブジェクトの値を、ステップ5のコマンドに示されている形式で渡してください。

リンク

Oracle Cloud Infrastructureドキュメント

生成AIエージェントのRAGツール・オブジェクト・ストレージ・ガイドライン

一般的なガイドライン

表の強化の理解

メタデータ・フィルタリングによるレスポンスの拡張

オブジェクト・ストレージ・メタデータ・ヘッダーへのメタデータの追加

カスタムURLを使用したオブジェクト・ストレージ・バケットへのデータの追加

召喚へのカスタムURLの割当て