メタデータ検索でフィルタする

このページでは、Gemini Enterprise Agent Platform の RAG Engine でスキーマベースのメタデータ検索機能を使用する方法について説明します。コーパスのメタデータ スキーマを定義し、そのコーパス内のファイルにメタデータを添付して、このメタデータを使用して検索時にコンテキストをフィルタできます。

始める前に

メタデータ検索を使用するには、既存の RAG コーパスと RAG ファイルが必要です。コーパスを作成してファイルをアップロードする方法については、RAG ナレッジベースを管理するをご覧ください。

コーパスを作成するかファイルをアップロードすると、API は数値の RAG_CORPUS_ID と RAG_FILE_ID（123456789 など）を返します。メタデータ リソースを管理するには、これらの ID が必要です。

メタデータ リソース

メタデータ検索機能は、次のリソース階層を使用します。

  • RagCorpus: RAG ファイルとその構成を含む最上位のリソース。

    • RagDataSchema: RagCorpus の子リソース。コーパス内で使用される単一のメタデータ フィールドの構造を定義します。各スキーマは、キー（year など）とデータ型（INTEGER、FLOAT、STRING、DATETIME、BOOLEAN、LIST）を指定します。フィルタリングに使用するメタデータキーごとに RagDataSchema を定義する必要があります。

    • RagFile: 取り込まれた単一のドキュメントを表す RagCorpus の子リソース。

      • RagMetadata: RagFile の子リソース。特定のファイルに添付された単一の Key-Value メタデータ ペア（year=2024 など）を表します。RagMetadata リソースで使用されるキーは、親コーパスの RagDataSchema で定義されたキーに対応している必要があります。複数の RagMetadata リソースを 1 つのファイルに添付できます。

メタデータ スキーマを管理

RAG コーパスを作成したら、コーパスレベルで RagDataSchema リソースを使用してメタデータ構造を定義します。定義したスキーマを表示して削除することもできます。

メタデータ スキーマを定義する

スキーマを定義するときに、キーとデータ型を指定します。キーに使用できる有効な型は次のとおりです。

  • INTEGER: メタデータ値として int_value で渡されます。
  • FLOAT: メタデータ値として float_value で渡されます。
  • STRING: メタデータ値として str_value で渡されます。
  • DATETIME: メタデータ値として datetime_value で渡されます（RFC 3339 形式の文字列（例: "2024-01-01T00:00:00Z"））。
  • BOOLEAN: メタデータ値として bool_value で渡されます。
  • LIST: メタデータ値として list_value で渡されます。 次の REST サンプルは、コーパスの year フィールドと month フィールドを定義するメタデータ スキーマを一括で作成する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "year",
        "schema_details": {"type": "INTEGER"}
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "month",
        "schema_details": {"type": "STRING"}
      }
    }
  ]
}'

メタデータ スキーマを一覧表示する

次の REST サンプルは、コーパスに定義されているメタデータ スキーマを一覧表示する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas

メタデータ スキーマを削除する

次の REST サンプルは、コーパスからメタデータ スキーマを一括で削除する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
  • RAG_DATA_SCHEMA_KEY_1: 削除する最初のメタデータ スキーマのキー名。
  • RAG_DATA_SCHEMA_KEY_2: 削除する 2 番目のメタデータ スキーマのキー名。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_DATA_SCHEMA_KEY_1=RAG_DATA_SCHEMA_KEY_1
RAG_DATA_SCHEMA_KEY_2=RAG_DATA_SCHEMA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_2}"'"
  ]
}'

ファイル メタデータを管理する

ファイルをコーパスにアップロードまたはインポートしたら、それらのファイルに関連付けられたメタデータを添付、更新、表示、削除できます。

ファイルにメタデータを添付する

添付するメタデータは、コーパスに定義されたスキーマに準拠している必要があります。次の REST サンプルは、複数のメタデータ値をファイルに添付する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
  • RAG_FILE_ID: RAG ファイルの ID。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "year", "value": { "int_value": 2024 } }
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "month", "value": { "str_value": "May" } }
      }
    }
  ]
}'

ファイルのメタデータを一覧表示する

次の REST サンプルは、特定のファイルに添付されたメタデータを一覧表示する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
  • RAG_FILE_ID: RAG ファイルの ID。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata

メタデータを更新する

ファイルに添付されたメタデータ値を更新できます。次の REST サンプルは、year キーに関連付けられたメタデータ値を更新する方法を示しています。RAG_METADATA_KEY は、メタデータの作成時に使用した文字列です。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
  • RAG_FILE_ID: RAG ファイルの ID。
  • RAG_METADATA_KEY: 更新するメタデータのキー名。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY=RAG_METADATA_KEY
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata/${RAG_METADATA_KEY} \
-d '{
  "user_specified_metadata": { "key": "'"${RAG_METADATA_KEY}"'", "value": { "int_value": 2025 } }
}'

ファイルからメタデータを削除する

次の REST サンプルは、ファイルからメタデータ値を一括で削除する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
  • RAG_FILE_ID: RAG ファイルの ID。
  • RAG_METADATA_KEY_1: 削除する最初のメタデータ値のキー名。
  • RAG_METADATA_KEY_2: 削除する 2 番目のメタデータ値のキー名。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY_1=RAG_METADATA_KEY_1
RAG_METADATA_KEY_2=RAG_METADATA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_2}"'"
  ]
}'

メタデータでコンテキストをフィルタする

結果の関連性を高めるには、ファイル メタデータを使用して、コンテキストの取得時に検索スペースを絞り込みます。CEL（Common Expression Language）を使用して、metadata_filter 式を RetrieveContexts リクエストに追加します（例: year == 2024 && month == "May"）。フィルタ式に一致するメタデータを含むファイルのみが検索対象となります。

次の REST サンプルは、メタデータ フィルタを使用してコンテキストを取得する方法を示しています。

REST

次の変数を置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リクエストを処理するリージョン。
  • RAG_CORPUS_ID: RAG コーパスの ID。
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
QUERY="except share amounts"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}:retrieveContexts -d '{
    "vertex_rag_store": {
       "rag_resources": [
         {
           "rag_corpus": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'"
         }
       ]
    },    
    "query": {
      "text": "'"${QUERY}"'", 
      "rag_retrieval_config": {
         "top_k": 10,
         "filter": {
            "vector_distance_threshold": 0.5,
            "metadata_filter": "year == 2024 && month == \"May\""
         }
      }
    }
}'

次のステップ