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

このページでは、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 で定義されているキーに対応している必要があります。1 つのファイルに複数の RagMetadata リソースを接続できます。

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

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)(例: year == 2024 && month == "May")を使用して、RetrieveContexts リクエストに metadata_filter 式を追加します。フィルタ式に一致するメタデータを持つファイルのみが取得対象となります。

次の 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\""
         }
      }
    }
}'

次のステップ