RAG でベクトル検索 2.0 を使用する

このページでは、Gemini Enterprise Agent Platform の RAG Engine が Gemini Enterprise Agent Platform ベクトル検索 2.0 を使用する方法について説明します。これは、ドキュメントのベクトル表現を保存して管理するための包括的なストレージおよび検索システムとして機能する Cloud de Confiance by S3NS プロダクトです。次に、Gemini Enterprise Agent Platform ベクトル検索 2.0 を使用して、指定されたクエリに対するドキュメントの意味的な類似性に基づいて、関連するドキュメントを取得します。

RAG はベクトル検索 2.0 コレクションを管理し、プロジェクト内のベクトル検索 2.0 コレクションに完全にアクセスできます。

RAG バックエンドの選択

Gemini Enterprise Agent Platform で RAG Engine を使用する場合は、RAG コーパスに異なるバックエンド ストレージ オプションを選択できます。次の表は、主な違いをまとめたものです。

最新の機能、自動管理、ベクトル検索 2.0 データの透明性を実現するには、RagManagedVertexVectorSearch を選択します。CMEK のサポートが厳格な要件である場合は、バックエンド データベースを直接可視化できないことを考慮して、RagManagedDb を検討してください。

ベクトル検索 API を有効にする

RAG マネージド Gemini Enterprise Agent Platform ベクトル検索を使用するには、まず Vector Search API を有効にする必要があります。

RagManagedVertexVectorSearch を使用して RAG コーパスを作成する

このコードサンプルは、RagManagedVertexVectorSearch を使用して RAG コーパスを作成する方法を示しています。

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedVertexVectorSearch()
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

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 \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "rag_managed_vertex_vector_search": {}
      }
    }'

RagManagedVertexVectorSearch へのデータのインポート

ImportRagFiles API または UploadRagFile API を使用して、データを RagManagedVertexVectorSearch にインポートできます。

ローカル ファイルを RAG コーパスにアップロードするには、RAG ファイルをアップロードするをご覧ください。RAG コーパスにデータをインポートするには、Cloud Storage からインポートする方法を示す次のコードサンプルをご覧ください。サポートされているデータソースについては、RAG でサポートされるデータソースをご覧ください。

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
)

# Wait for the import to complete.
await response.result()

GCS_URI=GCS_URI

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/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
  }
}'

コーパスのインデックスを作成する

RAG Engine はコーパスごとにベクトル検索 2.0 コレクションを作成しますが、そのコレクションにインデックスは作成しません。インデックスを作成するまでは、すべての検索がブルートフォース KNN スキャンになります。

ブルート フォース スキャンはインデックス付き検索よりも時間がかかります。KNN は、最大 100,000 個のデータ オブジェクトのコレクションでのみ実行されます。RAG Engine はデータ オブジェクトごとに 1 つのチャンクを保存するため、コーパスがその上限を超えると、インデックスが存在するまで取得が失敗します。

すべてのコーパスをインデックスに登録しないでください。インデックスは独自のサービス インフラストラクチャで実行され、クエリの有無にかかわらず、存在する限り課金されます。どのコーパスにインデックスが必要かを判断するには、インデックスに登録するコーパスを決定するをご覧ください。

インデックスが存在すると、検索で自動的に使用されます。コーパスは変更されず、データを再度インポートする必要はありません。

複数のコーパスをインデックスに登録する場合は、ループをスクリプト化します。一括作成パスはありません。同時インデックス オペレーションには割り当て制限があるため、インデックスは連続して作成するか、小さなバッチで作成します。詳しくは、割り当てをご覧ください。

始める前に

インデックスを作成するには、コレクションに対する vectorsearch.indexes.create 権限が必要です。また、データ オブジェクトをカウントするには、vectorsearch.dataObjects.query が必要です。どちらの権限もベクトル検索管理者（roles/vectorsearch.admin）ロールに含まれています。ベクトル検索インデックス書き込み（roles/vectorsearch.indexWriter）は最初の権限を付与します。プロジェクトで ベクトル検索 API も有効にする必要があります。

コーパス ID を確認する

プロジェクトでは、各コーパスに vertex-rag-RAG_CORPUS_ID という名前のコレクションが 1 つだけあります。コーパスを一覧表示して ID を取得します。

PROJECT_ID は、プロジェクト ID に置き換えます。

PROJECT_ID=PROJECT_ID
LOCATION=us-central1

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora?pageSize=100"

各コーパス name の末尾にある数値部分は RAG_CORPUS_ID です。各コーパスは、vectorDbConfig.ragManagedVertexVectorSearch.collectionName で完全な Collection リソース名も報告します。

レスポンスには最大 100 個のコーパスがリストされます。pageSize を省略した場合は最大 25 個です。レスポンスに nextPageToken が含まれている場合は、その値を pageToken として渡して次のページを取得します。

インデックスに登録する RAG_CORPUS_ID がすでにわかっている場合は、代わりにそのコーパスを取得します。レスポンスには同じ collectionName が含まれます。

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"

インデックスに登録するコーパスを決定する

コーパスごとに、コレクション内のデータ オブジェクトをカウントします。空の filter を渡して、コレクション全体をカウントします。

COLLECTION_ID=vertex-rag-RAG_CORPUS_ID

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/dataObjects:aggregate" \
-d '{"aggregate": "COUNT", "filter": {}}'

カウントは aggregateResults で返されます。

{
  "aggregateResults": [
    {
      "count": 95217
    }
  ]
}

次のいずれかに該当する場合は、そのコーパスのインデックスを作成します。

• 数が 100,000 に近いか、それを超えている。この上限は、ファイルではなくデータ オブジェクトをカウントするため、少数の大きなファイルを含むコーパスでも、上限を大幅に超える可能性があります。
• クエリレートに対して取得が遅すぎる。インデックス付き検索はブルート フォース スキャンよりも高速で、コレクションが大きくなるにつれてその差は広がります。

それ以外の場合は、コーパスをインデックスに登録せず、（広告）配信費用を回避します。データが増えたら、後でインデックスを追加できます。

コレクション スキーマを確認する

RAG Engine は、次のスキーマを使用して各コレクションを作成します。これらの名前は、インデックス フィールドとフィルタ フィールドを指定するときに使用します。

インデックス設定を選択する

UpdateIndex は、表示名、説明、ラベル、レプリカ数のみを変更します。このセクションの設定を変更するには、インデックスを削除して新しいインデックスを作成する必要があります。

インデックス フィールド: コレクション スキーマの唯一のベクトル フィールドである text_embedding に設定します。

距離指標: コサインに設定します。RAG Engine は常に取得リクエストで COSINE_DISTANCE を送信します。ベクトル検索 2.0 は、指標がインデックスと一致しない取得リクエストを拒否します。この指標を省略すると、デフォルトで DOT_PRODUCT になります。そのため、この指標を指定せずに作成されたインデックスでは、そのコーパスの取得が機能しなくなります。RAG Engine は、失敗を FAILED_PRECONDITION として報告し、メッセージ Failed to process Rag Managed Vertex Vector Search response. を表示します。このメッセージでは、指標が原因として特定されません。スペルはサーフェスによって異なります。REST 本文は COSINE_DISTANCE を受け取り、gcloud CLI フラグは cosine-distance を受け取ります。

インフラストラクチャ: コサイン距離はストレージ最適化インフラストラクチャではサポートされていないため、インデックスはデフォルトのパフォーマンス最適化インフラストラクチャのままにします。インデックスは専用のサービング インフラストラクチャで実行され、存在する限り課金されます。v1 では、min_replica_count と max_replica_count の両方がデフォルトで 2 に設定されているため、デフォルトではインデックスは 2 つのレプリカによって提供され、自動スケーリングは行われません。詳細については、コレクション インデックスをご覧ください。

フィルタ フィールド: filter_fields を file_id のみに設定します。これは、RAG Engine が取得時にフィルタする唯一のフィールドです。これは、取得リクエストが検索を特定のファイルに制限する場合にのみ行われます。特に、corpus_id は特定のコレクション内のすべてのデータ オブジェクトに対して同じ値を保持するため、フィルタしてもメリットはありません。

メタデータ フィルタリングでは、追加のフィルタ フィールドも必要ありません。取得リクエストで ragRetrievalConfig.filter.metadataFilter が設定されると、RAG Engine はまずファイル メタデータに対してフィルタを解決し、結果を一致する RAG ファイル ID のセットに変換して、そのセットを同じ file_id フィルタとしてベクトル検索に送信します。rag_metadata を filter_fields に追加すると、取得を変更せずにインデックス サイズが増加します。

ストア フィールド: store_fields は設定しないままにします。RAG Engine は、取得ごとにすべてのデータ フィールドをリクエストします。これはインライン サービングの対象にならないため、チャンクデータはバックアップ データベースから読み取られます。store_fields にリストされているフィールドはインデックスに push され、サイズにカウントされるため、設定すると取得を変更せずに費用が増加します。

インデックスを作成する

from google.cloud import vectorsearch_v1

client = vectorsearch_v1.VectorSearchServiceClient()

index = vectorsearch_v1.Index(
    index_field="text_embedding",
    distance_metric=vectorsearch_v1.DistanceMetric.COSINE_DISTANCE,
    filter_fields=["file_id"],
)
request = vectorsearch_v1.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID",
    index_id="vertex-rag-RAG_CORPUS_ID-index",
    index=index,
)

operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes).
operation.result()

PROJECT_ID=PROJECT_ID
RAG_CORPUS_ID=RAG_CORPUS_ID
LOCATION=us-central1
COLLECTION_ID=vertex-rag-${RAG_CORPUS_ID}
INDEX_ID=${COLLECTION_ID}-index

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/indexes?indexId=${INDEX_ID}" \
-d '{
      "index_field": "text_embedding",
      "distance_metric": "COSINE_DISTANCE",
      "filter_fields": ["file_id"]
    }'

gcloud vector-search collections indexes create vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --index-field=text_embedding \
  --distance-metric=cosine-distance \
  --filter-fields=file_id \
  --location=us-central1 \
  --project=PROJECT_ID

完了をポーリングする

インデックスを作成すると、長時間実行オペレーションが返されます。

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID/indexes/vertex-rag-RAG_CORPUS_ID-index",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

そのレスポンスの名前を使用してオペレーションをポーリングします。

OPERATION_NAME=OPERATION_NAME

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/${OPERATION_NAME}"

done が true の場合、response フィールドはインデックスが正常に作成されたことを意味し、error フィールドは失敗した理由を示します。インデックスの作成には数分かかります。大規模なコーパスの場合はさらに時間がかかります。

プロジェクトとロケーションのオペレーションを一覧表示するには、次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/operations"

既存のインデックスを検査するには、次のコマンドを実行します。

gcloud vector-search collections indexes describe vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

インデックスを削除するには、次のコマンドを実行します。これは、永続的な設定を変更するために必要です。置換インデックスが構築されるまで、取得はブルートフォース KNN スキャンにフォールバックします。コーパスが 100,000 チャンクを超えると、完全に失敗します。

gcloud vector-search collections indexes delete vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

次のステップ

• Google ドライブまたは Cloud Storage からファイルとフォルダをインポートするには、RAG ファイルのインポートの例をご覧ください。

• RAG ファイルを一覧表示するには、RAG ファイルのリストの例をご覧ください。

• 取得に再ランキングを使用するには、Gemini Enterprise Agent Platform RAG Engine の再ランキングをご覧ください。

• インデックス インフラストラクチャ、距離指標、ScaNN パラメータをチューニングするには、コレクション インデックスをご覧ください。