搭配 RAG 使用 Vector Search 2.0

本頁面說明 Gemini Enterprise Agent Platform 中的 RAG Engine 如何使用 Gemini Enterprise Agent Platform Vector Search 2.0。這項 Cloud de Confiance by S3NS 產品是全方位的儲存和檢索系統，可儲存及管理文件的向量表示法。接著，Gemini Enterprise Agent Platform 向量搜尋 2.0 會根據文件與指定查詢的語意相似度，檢索相關文件。

RAG 會為您管理 Vector Search 2.0 集合，您將具備專案中 Vector Search 2.0 集合的完整存取權。

選擇 RAG 後端

在 Gemini Enterprise Agent Platform 使用 RAG Engine 時，您可以為 RAG 語料庫選擇不同的後端儲存空間選項。下表概略說明主要差異：

後端選項 基礎技術 由 RAG Engine 管理 專案中的資料瀏覽權限 CMEK 支援
RagManagedVertexVectorSearch Gemini Enterprise Agent Platform Vector Search 2.0 由 Google 全代管。 在 Cloud de Confiance by S3NS 專案中顯示 否
VertexVectorSearch Gemini Enterprise Agent Platform Vector Search 1.0 使用者應設定、管理及清理 Vector Search 1.0 執行個體。 在 Cloud de Confiance by S3NS 專案中顯示 否
RagManagedDb Spanner 由 Google 全代管。 不會直接顯示在專案中 是

選擇 RagManagedVertexVectorSearch，即可享有最新功能、自動化管理，以及 Vector Search 2.0 資料的透明度。如果必須支援 CMEK，請考慮使用 RagManagedDb，但請注意，您無法直接查看後端資料庫。

啟用 Vector Search API

如要使用 RAG 代管型 Gemini Enterprise Agent Platform 向量搜尋，請先啟用 Vector Search API。

使用 RagManagedVertexVectorSearch 建立 RAG 語料庫

這個程式碼範例示範如何使用 RagManagedVertexVectorSearch 建立 RAG 語料庫。

Python

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))

REST

請替換下列變數：

  • PROJECT_ID：專案 ID。
  • LOCATION：處理要求的區域。
  • CORPUS_DISPLAY_NAME：RAG 語料庫的顯示名稱。
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 支援的資料來源」。

Python

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()

REST

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 會為每個語料庫建立 Vector Search 2.0 集合，但不會在該集合上建立索引。在建立索引之前，每次檢索都是暴力 KNN 掃描。

暴力掃描的速度比索引搜尋慢，而且 KNN 只能在最多 100,000 個資料物件的集合上執行。RAG Engine 會為每個資料物件儲存一個區塊，因此一旦語料庫超過該限制，在索引建立之前，檢索作業都會失敗。

請勿為每個語料庫建立索引。索引會在專屬的服務基礎架構上執行，只要索引存在，無論是否查詢，都會計費。如要決定哪些語料庫需要，請參閱「決定要建立索引的語料庫」。

建立索引後，檢索功能會自動使用索引。語料庫不會變更，您也不必再次匯入資料。

如要為多個語料庫建立索引，請編寫迴圈指令碼，因為沒有大量建立路徑。並行索引作業有配額限制，因此請逐一或分批建立索引。詳情請參閱「配額」。

事前準備

如要建立索引，您必須具備集合的 vectorsearch.indexes.create 權限，而計算資料物件數量則需要 vectorsearch.dataObjects.query。Vector Search 管理員 (roles/vectorsearch.admin) 角色包含這兩項權限；Vector Search 索引寫入者 (roles/vectorsearch.indexWriter) 則授予第一項權限。專案也必須啟用 向量搜尋 API。

找出語料庫 ID

在專案中，每個語料庫都只有一個名為 vertex-rag-RAG_CORPUS_ID 的集合。列出語料庫，取得 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
    }
  ]
}

符合下列任一條件時，請為該語料庫建立索引：

  • 數量接近或超過 10 萬。這項限制是以資料物件數量計算，而非檔案數量，因此即使語料庫只包含少量大型檔案，仍可能超過限制。
  • 以您的查詢頻率來說，檢索速度太慢。索引搜尋的速度比暴力掃描快，且隨著集合增大，差距會越來越大。

否則，請不要為語料庫建立索引，以免產生放送費用。如果資料量增加，可以稍後再新增索引。

查看 Collection 結構定義

RAG Engine 會使用下列結構定義建立各個集合。指定索引欄位和篩選器欄位時，請使用這些名稱。

欄位 種類 說明
text_embedding 稠密型向量 區塊嵌入。這是您要建立索引的欄位。維度數量與語料庫嵌入模型相符。
corpus_id 字串 RAG 語料庫的 ID。
file_id 字串 區塊來源 RAG 檔案的 ID。
chunk_id 字串 區塊的 ID。
chunk_data 字串 區塊文字。
chunk_data_type 字串 區塊資料的類型。
file_original_uri 字串 來源檔案的原始 URI。
rag_metadata 字串 使用者提供的區塊中繼資料。

選擇索引設定

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，因此索引預設會由兩個副本提供，且不會自動調度資源。詳情請參閱「集合索引」。

篩選器欄位：將 filter_fields 設為僅限 file_id。RAG Engine 在檢索時只會篩選這個欄位，而且只有在檢索要求限制搜尋特定檔案時，才會執行這項操作。具體來說，corpus_id 在特定集合中的每個資料物件都具有相同的值，因此篩選該欄位並無任何好處。

中繼資料篩選也不需要額外的篩選欄位。當檢索要求設定 ragRetrievalConfig.filter.metadataFilter 時，RAG Engine 會先根據檔案中繼資料解析篩選器，將結果轉換為一組相符的 RAG 檔案 ID，然後將該組 ID 傳送至向量搜尋，做為相同的 file_id 篩選器。將 rag_metadata 新增至 filter_fields 會增加索引大小，但不會變更檢索。

儲存欄位：將 store_fields 留空。RAG Engine 會在每次檢索時要求所有資料欄位，因此一律不符合內嵌提供條件，無論如何都會從支援資料庫讀取區塊資料。store_fields 中列出的欄位會推送至索引，並計入索引大小，因此設定這些欄位會增加費用，但不會改變檢索結果。

建立索引

Python

請替換下列變數：

  • PROJECT_ID：專案 ID。
  • RAG_CORPUS_ID：要建立索引的 RAG 語料庫 ID。
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()

REST

請替換下列變數：

  • PROJECT_ID：專案 ID。
  • RAG_CORPUS_ID：要建立索引的 RAG 語料庫 ID。
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

請替換下列變數：

  • PROJECT_ID：專案 ID。
  • RAG_CORPUS_ID：要建立索引的 RAG 語料庫 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

除非您傳遞 --async，否則指令會封鎖，直到作業完成。

輪詢完成

建立索引會傳回長時間執行的作業：

{
  "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

後續步驟