Menggunakan Vector Search 2.0 dengan RAG

Halaman ini menunjukkan cara Mesin RAG di Gemini Enterprise Agent Platform menggunakan Penelusuran Vektor 2.0 Gemini Enterprise Agent Platform, yang merupakan produk Cloud de Confiance by S3NS yang berfungsi sebagai sistem penyimpanan dan pengambilan yang komprehensif untuk menyimpan dan mengelola representasi vektor dokumen Anda. Kemudian, Gemini Enterprise Agent Platform Penelusuran Vektor 2.0 digunakan untuk mengambil dokumen yang relevan berdasarkan kemiripan semantik dokumen dengan kueri tertentu.

RAG akan mengelola koleksi Penelusuran Vektor 2.0 untuk Anda dan Anda akan memiliki akses penuh ke koleksi Penelusuran Vektor 2.0 di project Anda.

Memilih backend RAG

Saat menggunakan RAG Engine di Gemini Enterprise Agent Platform, Anda dapat memilih di antara berbagai opsi penyimpanan backend untuk korpus RAG Anda. Tabel berikut merangkum perbedaan utamanya:

Pilih RagManagedVertexVectorSearch untuk mendapatkan fitur terbaru, pengelolaan otomatis, dan transparansi data Penelusuran Vektor 2.0 Anda. Jika dukungan CMEK merupakan persyaratan ketat, pertimbangkan RagManagedDb, dengan mengingat kurangnya visibilitas langsung ke database backend.

Mengaktifkan Vector Search API

Untuk menggunakan Penelusuran Vektor Gemini Enterprise Agent Platform Terkelola RAG, Anda harus mengaktifkan Vector Search API terlebih dahulu.

Membuat korpus RAG dengan RagManagedVertexVectorSearch

Contoh kode ini menunjukkan cara membuat korpus RAG menggunakan RagManagedVertexVectorSearch.

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": {}
      }
    }'

Mengimpor data Anda ke RagManagedVertexVectorSearch

Anda dapat menggunakan ImportRagFiles API atau UploadRagFile API untuk mengimpor data ke RagManagedVertexVectorSearch.

Untuk mengupload file lokal ke korpus RAG, lihat Mengupload file RAG. Untuk mengimpor data ke korpus RAG, lihat contoh kode berikut yang menunjukkan cara mengimpor dari Cloud Storage. Untuk mempelajari sumber data yang didukung, lihat Sumber data yang didukung untuk 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}"\"',
      },
  }
}'

Membuat Indeks untuk korpus Anda

RAG Engine membuat Koleksi Penelusuran Vektor 2.0 untuk setiap korpus, tetapi tidak membuat Indeks pada Koleksi tersebut. Sebelum Anda membuatnya, setiap pengambilan adalah pemindaian KNN brute-force.

Pemindaian brute-force lebih lambat daripada penelusuran yang diindeks, dan KNN hanya berjalan pada Koleksi hingga 100.000 Objek Data. RAG Engine menyimpan satu potongan per Objek Data, jadi setelah korpus melewati batas tersebut, pengambilan akan gagal hingga Indeks ada.

Jangan mengindeks setiap korpus. Indeks berjalan di infrastruktur penyajiannya sendiri dan ditagih selama indeks tersebut ada, baik saat dikueri maupun tidak. Untuk memutuskan korpus mana yang memerlukan indeks, lihat Memutuskan korpus mana yang akan diindeks.

Setelah Indeks ada, pengambilan akan menggunakannya secara otomatis. Korpus tidak berubah dan data Anda tidak perlu diimpor lagi.

Jika Anda mengindeks beberapa korpus, buat skrip loop: tidak ada jalur pembuatan massal. Operasi indeks serentak dibatasi kuota, jadi buat indeks secara serial atau dalam batch kecil. Untuk mengetahui informasi selengkapnya, lihat Kuota.

Sebelum memulai

Membuat Indeks memerlukan izin vectorsearch.indexes.create pada Koleksi, dan menghitung Objek Data-nya memerlukan vectorsearch.dataObjects.query. Kedua izin tersebut disertakan dalam peran Admin Penelusuran Vektor (roles/vectorsearch.admin); Penulis Indeks Penelusuran Vektor (roles/vectorsearch.indexWriter) memberikan izin yang pertama. Vector Search API juga harus diaktifkan di project.

Menemukan ID korpus Anda

Dalam project Anda, setiap korpus memiliki tepat satu Koleksi, bernama vertex-rag-RAG_CORPUS_ID. Buat daftar korpus Anda untuk mendapatkan ID-nya.

Ganti PROJECT_ID dengan project ID Anda:

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"

Bagian numerik di akhir setiap korpus name adalah RAG_CORPUS_ID. Setiap korpus juga melaporkan nama resource Koleksi lengkap di vectorDbConfig.ragManagedVertexVectorSearch.collectionName.

Respons mencantumkan maksimal 100 korpus, dan maksimal 25 jika Anda menghilangkan pageSize. Jika respons menyertakan nextPageToken, teruskan nilai tersebut sebagai pageToken untuk mengambil halaman berikutnya.

Jika Anda sudah mengetahui RAG_CORPUS_ID yang ingin diindeks, ambil korpus tersebut. Respons membawa collectionName yang sama:

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"

Memutuskan korpus yang akan diindeks

Untuk setiap korpus, hitung Objek Data dalam Koleksinya. Teruskan filter kosong untuk menghitung seluruh Koleksi:

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": {}}'

Jumlahnya akan ditampilkan dalam aggregateResults:

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

Buat Indeks untuk korpus tersebut jika salah satu kondisi berikut terpenuhi:

• Jumlahnya mendekati atau di atas 100.000. Batas ini menghitung Objek Data, bukan file, sehingga korpus yang berisi sejumlah kecil file besar masih dapat melebihi batas tersebut.
• Pengambilan terlalu lambat pada rasio kueri Anda. Penelusuran yang diindeks lebih cepat daripada pemindaian brute-force, dan kesenjangannya melebar seiring bertambahnya Koleksi.

Jika tidak, biarkan korpus tidak diindeks dan hindari biaya penayangan. Anda dapat menambahkan Indeks nanti jika jumlahnya bertambah.

Meninjau skema Koleksi

RAG Engine membuat setiap Koleksi dengan skema berikut. Gunakan nama ini saat Anda menentukan kolom indeks dan kolom filter.

Pilih setelan Indeks

UpdateIndex hanya mengubah nama tampilan, deskripsi, label, dan jumlah replika, jadi untuk mengubah setelan apa pun di bagian ini, Anda harus menghapus Indeks dan membuat yang baru.

Kolom indeks: Tetapkan ke text_embedding, satu-satunya kolom vektor dalam skema Koleksi.

Metrik jarak: Tetapkan ke kosinus. RAG Engine selalu mengirim COSINE_DISTANCE pada permintaan pengambilannya, dan Penelusuran Vektor 2.0 menolak permintaan pengambilan yang metriknya tidak cocok dengan Indeks. Metrik ini ditetapkan secara default ke DOT_PRODUCT jika Anda menghilangkannya, sehingga Indeks yang dibuat tanpa metrik tersebut akan merusak pengambilan untuk korpus tersebut. RAG Engine melaporkan kegagalan sebagai FAILED_PRECONDITION dengan pesan Failed to process Rag Managed Vertex Vector Search response., yang tidak mengidentifikasi metrik sebagai penyebabnya. Ejaannya berbeda menurut platform: isi REST menggunakan COSINE_DISTANCE, dan flag gcloud CLI menggunakan cosine-distance.

Infrastructure: Biarkan Indeks pada infrastruktur default yang dioptimalkan untuk performa, karena jarak kosinus tidak didukung pada infrastruktur yang dioptimalkan untuk penyimpanan. Indeks berjalan di infrastruktur penyajian khusus dan ditagih selama indeks tersebut ada. Di v1, min_replica_count dan max_replica_count keduanya ditetapkan secara default ke 2, sehingga secara default Indeks disajikan oleh dua replika dan tidak diskalakan secara otomatis. Untuk mengetahui informasi selengkapnya, lihat Indeks Koleksi.

Kolom filter: Tetapkan filter_fields ke file_id saja. Ini adalah satu-satunya kolom yang difilter oleh RAG Engine pada waktu pengambilan, dan hanya dilakukan saat permintaan pengambilan membatasi penelusuran ke file tertentu. Secara khusus, corpus_id menyimpan nilai yang sama untuk setiap Objek Data dalam Koleksi tertentu, sehingga pemfilteran tidak memberikan manfaat.

Pemfilteran metadata juga tidak memerlukan kolom filter tambahan. Saat permintaan pengambilan menetapkan ragRetrievalConfig.filter.metadataFilter, RAG Engine akan menyelesaikan filter terhadap metadata file Anda terlebih dahulu, mengonversi hasilnya menjadi kumpulan ID file RAG yang cocok, dan mengirimkan kumpulan tersebut ke Penelusuran Vektor sebagai filter file_id yang sama. Menambahkan rag_metadata ke filter_fields akan meningkatkan ukuran Indeks tanpa mengubah pengambilan.

Kolom toko: Biarkan store_fields tidak disetel. RAG Engine meminta semua kolom data pada setiap pengambilan, yang tidak pernah memenuhi syarat untuk penyajian inline, sehingga data potongan dibaca dari database pendukung. Kolom yang tercantum dalam store_fields akan dimasukkan ke dalam Indeks dan dihitung dalam ukurannya, sehingga menetapkannya akan menambah biaya tanpa mengubah pengambilan.

Membuat Indeks

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

Polling untuk penyelesaian

Membuat Indeks akan menampilkan operasi yang berjalan lama:

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

Lakukan polling pada operasi menggunakan nama dari respons tersebut:

OPERATION_NAME=OPERATION_NAME

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

Jika done adalah true, kolom response berarti Indeks berhasil dibuat, dan kolom error memberikan alasan kegagalannya. Pembuatan Indeks memerlukan waktu beberapa menit, dan lebih lama untuk korpus yang besar.

Untuk mencantumkan operasi dalam project dan lokasi, jalankan perintah berikut:

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

Untuk memeriksa Indeks yang ada, jalankan perintah berikut:

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

Untuk menghapus Indeks, yang harus Anda lakukan untuk mengubah setelan permanennya, jalankan perintah berikut. Pengambilan akan beralih kembali ke pemindaian KNN brute-force hingga Indeks pengganti dibuat, dan akan gagal sepenuhnya jika korpus melebihi 100.000 potongan.

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

Langkah berikutnya

• Untuk mengimpor file dan folder dari Google Drive atau Cloud Storage, lihat Contoh mengimpor file RAG.

• Untuk menampilkan daftar file RAG, lihat Contoh menampilkan daftar file RAG.

• Untuk menggunakan reranker dalam pengambilan, lihat Memberi peringkat ulang untuk RAG Engine Gemini Enterprise Agent Platform

• Untuk menyesuaikan infrastruktur Indeks, metrik jarak, dan parameter ScaNN, lihat Indeks Koleksi.