このページでは、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リソースを接続できます。
- RagMetadata:
- RagDataSchema:
メタデータ スキーマを管理
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\""
}
}
}
}'
次のステップ
- ファイルのアップロードと管理の詳細については、RAG ナレッジベースを管理するをご覧ください。
- RAG の標準ベクトル検索の詳細については、RAG でベクトル検索を使用するをご覧ください。