Oracle Cloud Infrastructureドキュメント

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

生成AIエージェントでRAGツールのオブジェクト・ストレージ・データを準備するには、次のガイドラインを確認してください。

一般的なガイドライン

OCI生成AIエージェントの生成AIエージェント・データ・ソースのデータを準備するには、次のガイドラインに従います。

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

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

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

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

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

メタデータ・フィルタリング機能は、定義したフィルタ条件を使用してレスポンス品質を向上させ、モデルがコンテンツ・スコープに関連する回答を生成できるようにすることを目的としています。

次のオプションを確認して、最適な方法を1つ以上選択します。

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

  1. _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"
        }  
    ]
}

    指定できる値は、integer、string、list_of_stringおよびdoubleです。

    integerのスキーマ例:
    "publication_year": {
  "type": "integer"         
}
    stringのスキーマ例:
    "title": {
  "type": "text",
  "fields": {
      "keyword": {
          "type": "keyword"
      },
      "search_as_you_type": {
          "type": "search_as_you_type"
      }
   }
}
    list_of_stringのスキーマ例:
    "publishers": {
    "type": "text",
    "fields": {
    "keyword": {
        "type": "keyword"
    },
    "search_as_you_type": {
        "type": "search_as_you_type"
    }
  }
}
    doubleのスキーマ例:
    "rating": {
  "type": "double"
}
  2. (オプション)すべてのファイルに共通するメタデータ用の_commmon.metadata.jsonというJSONファイルを作成します。例: 
    {
    "metadataAttributes": {
        "field_1": value_1,
        "field_2": value_2,
        "field_3": value_3,
        ......,
        "field_n": value_n
    }
}
  3. (オプション)_all.metadata.jsonというJSONファイルを作成し、このファイルにバケット内の各ファイルのメタデータを追加します。例: 
    {
    "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
        }
    }
}
  4. (オプション)バケット内の各ファイルに対して<file-name>.metadata.jsonというJSONファイルを作成し、各ファイルにメタデータを個別に追加します。例: 
    {
    "metadataAttributes": {
        "field_1": value_1,
        "field_2": value_2,
        "field_3": value_3,
        ......,
        "field_n": value_n
    }
}
    ノート

    ナレッジ・ベース・データの取込み後は、メタデータ・フィールドを変更または削除できません。許可された制限を超えて新しいフィールドを追加できます。フィールドを削除または更新するには、ナレッジ・ベースを再作成します。

内容 制限
_all.metadata.json内のエントリの最大数 10,000
ファイルごとに指定できるメタデータ・フィールドの最大数 20
list_of_string type内のアイテムの最大数 10
list_of_string型の個々のアイテムの最大長 50
メタデータ・キーの最大長(文字数) 25
メタデータ値の最大長(文字) 50
オブジェクト・ストレージ・メタデータ・ヘッダーへのメタデータの追加
オブジェクト・ストレージ・バケットを作成し、OCI生成AIエージェントでRAGレスポンスのソース・ファイルをアップロードします。オプションで、引用のために各ファイルにカスタムURLを追加します。
  1. コンソールのナビゲーション・バーで、生成AIエージェントをホストするリージョン(米国中西部(シカゴ)など)を選択します。選択するリージョンがわからない場合は、生成AIエージェントを使用するリージョンを参照してください。
  2. ナビゲーション・メニューを開き、「ストレージ」を選択します。「オブジェクト・ストレージおよびアーカイブ・ストレージ」で、「バケット」を選択します。
  3. バケットまたは使用するバケットを含むコンパートメントを作成するコンパートメントを選択します。このコンパートメントにオブジェクト・ストレージ・リソースを追加するには、すでに次の権限が必要です。 
    allow group <your-group-name> to manage object-family in compartment <compartment-with-bucket>
  4. バケットを作成するには、次のステップに従います:
    1. 「Create Bucket」を選択します。
    2. バケットのリージョンに一意の名前を入力します。
    3. 他のフィールドでは、「詳細」リンクを選択し、データに適用するオプションを選択します。オブジェクト・ストレージ・バケットの作成も参照してください。
    4. 「作成」を選択します。
      デフォルトでは、新しいバケットはプライベートです。バケットの作成後に、そのバケットの表示を変更できます。
  5. 使用するバケットの名前を選択します。
  6. バケットの詳細ページの「オブジェクト」で、「アップロード」を選択します。
  7. (オプション)「オプションのヘッダーおよびメタデータの表示」を選択し、次の値を選択して入力します。
    • タイプ: メタデータ
    • 名前: 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}

  8. データ・ソースに1つ以上のファイルを追加し、「アップロード」を選択します。
    ノート

    • 既存のオブジェクトのmetadataプロパティは更新できません。かわりに、ファイルをコピーし、そのファイルに新しいメタデータを追加してから、古いファイルを削除できます。

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

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

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

ベータ版の顧客:

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

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

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

  1. 環境またはクラウド・シェルでOCI CLIを起動します。コマンドに慣れるために、まずCloud Shellで試すことをお薦めします。
    コマンドライン・インタフェースの開始を参照してください。
  2. カスタム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.

    コンソールでオブジェクト名を検索することもできます。バケットの詳細ページで、オブジェクトの「アクション」メニュー(アクション・メニュー)を選択し、「オブジェクト詳細の表示」を選択して名前をコピーします。

    ノート

    ファイルがフォルダにある場合、ファイル名とそのオブジェクト名は異なります。たとえば、file1.pdfという名前のファイルの場合、そのオブジェクト名はfolder1/file1.pdfになります。それ以外の場合、ファイル名とそのオブジェクト名は同じです。
  3. ファイルを現在の作業ディレクトリにダウンロードします。

    ファイルのmetadataオブジェクトを追加または更新するには、ファイルを新しいmetadataオブジェクトを持つ同じファイルに置き換えます。そのため、最初にファイルを現在の作業ディレクトリにコピーします。

    oci os object get 
--bucket-name <the-bucket-name> 
--file <the-file-name>
--name <the-object-name>
  4. 現在のファイルの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名に自動的に追加されます。

  5. オブジェクト・ストレージにあるファイルを現在の作業ディレクトリにあるものと同じファイルに置き換え、新しい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>"}'
  6. カスタム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のコマンドに示されている形式で渡してください。
リンク