Menggunakan RagManagedDb dengan Mesin RAG di Platform Agen Gemini Enterprise

Kontrol keamanan VPC-SC dan CMEK didukung oleh RAG Engine Platform Agen. Kontrol keamanan residensi data dan AXT tidak didukung.

Instance Spanner yang dikelola RAG Engine digunakan sebagai database vektor dan merupakan GA dengan penagihan diaktifkan. Untuk mengetahui informasi selengkapnya, lihat Penagihan RAG Engine di Gemini Enterprise Agent Platform.

Halaman ini menunjukkan cara RAG Engine di Gemini Enterprise Agent Platform menggunakan RagManagedDb, yang merupakan database vektor siap pakai untuk perusahaan yang digunakan untuk menyimpan dan mengelola representasi vektor dokumen Anda. Database vektor kemudian digunakan untuk mengambil dokumen yang relevan berdasarkan kemiripan semantik dokumen dengan kueri tertentu.

Selain itu, halaman ini menunjukkan cara menerapkan CMEK.

Penting: RagManagedDb digunakan secara default dan menggunakan Spanner. Pelanggan akan dikenai biaya untuk penggunaan instance Spanner yang dikelola Google yang disediakan dalam project tenant Google menggunakan SKU Spanner standar.

Mengelola strategi pengambilan

RagManagedDb menawarkan strategi pengambilan berikut untuk mendukung kasus penggunaan RAG Anda:

Strategi pengambilan	Deskripsi
k-Tetangga Terdekat (KNN) (Default)	Menemukan tetangga terdekat yang tepat dengan membandingkan semua titik data dalam korpus RAG Anda. Jika Anda tidak menentukan strategi selama pembuatan korpus RAG, KNN adalah strategi pengambilan default yang digunakan.	Memverifikasi perolehan sempurna (1.0) selama pengambilan. Cocok untuk aplikasi yang sensitif terhadap perolehan. Cocok untuk korpus RAG berukuran kecil hingga sedang, yang menyimpan kurang dari 10.000 file RAG. Memerlukan penelusuran di setiap titik data, sehingga latensi meningkat seiring dengan jumlah file RAG dalam korpus.
Perkiraan Tetangga Terdekat (ANN)	Menggunakan teknik perkiraan untuk menemukan tetangga serupa lebih cepat daripada teknik KNN.	Mengurangi latensi kueri secara signifikan pada korpus RAG yang besar. Perolehan sedikit diturunkan karena teknik perkiraan yang digunakan. Menjadi sangat efektif saat Anda memiliki korpus RAG yang besar, yang kira-kira lebih dari 10.000 file RAG. Jumlah kehilangan perolehan yang dapat Anda terima bergantung pada kasus penggunaan, tetapi dalam sebagian besar kasus skala besar, kehilangan sedikit perolehan sebagai imbalan untuk peningkatan performa kueri adalah kompromi yang dapat diterima.

Membuat korpus RAG dengan KNN RagManagedDb

Contoh kode ini menunjukkan cara membuat korpus RAG menggunakan KNN RagManagedDb.

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.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Ganti variabel berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region untuk memproses permintaan.
• CORPUS_DISPLAY_NAME: Nama tampilan korpus 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": {
        "ragManagedDb": {
          "knn": {}
        }
      }
    }'

Pratinjau

Beberapa fitur RAG adalah penawaran Pratinjau, yang tunduk pada "Persyaratan Penawaran Pra-GA" dari Persyaratan Khusus Layanan Google Cloud. Produk dan fitur pra-GA tersedia "apa adanya" dan mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran. Dengan menggunakan Gemini API di Gemini Enterprise Agent Platform, Anda menyetujui persyaratan dan ketentuan Pratinjau AI Generatif (Persyaratan Pratinjau).

Membuat korpus RAG dengan ANN RagManagedDb

Untuk menawarkan fitur ANN, RagManagedDb menggunakan struktur berbasis pohon untuk mempartisi data dan memfasilitasi penelusuran yang lebih cepat. Untuk mengaktifkan perolehan dan latensi terbaik, struktur pohon ini harus dikonfigurasi dengan eksperimen agar sesuai dengan ukuran dan distribusi data Anda. RagManagedDb memungkinkan Anda mengonfigurasi tree_depth dan leaf_count pohon.

tree_depth menentukan jumlah lapisan atau tingkat dalam pohon. Ikuti pedoman berikut:

• Jika Anda memiliki sekitar 10.000 file RAG dalam korpus RAG, tetapkan nilai ke 2.
• Jika Anda memiliki lebih banyak file RAG dari itu, tetapkan nilai ini ke 3.
• Jika tree_depth tidak ditentukan, RAG Engine akan menetapkan nilai default 2 untuk parameter ini.

The leaf_count menentukan jumlah node daun dalam struktur berbasis pohon. Setiap node daun berisi grup vektor yang terkait erat beserta centroid yang sesuai. Ikuti pedoman berikut:

• Nilai yang direkomendasikan adalah 10 * sqrt(num of RAG files in your RAG corpus).

• Jika tidak ditentukan, RAG Engine akan menetapkan nilai default 500 untuk parameter ini.

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
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

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

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Ganti variabel berikut:

• PROJECT_ID: Project ID Anda.
• LOCATION: Region untuk memproses permintaan.
• CORPUS_DISPLAY_NAME: Nama tampilan korpus RAG.
• TREE_DEPTH: Kedalaman pohon Anda.
• LEAF_COUNT: Jumlah daun Anda.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

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": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

Pratinjau

Beberapa fitur RAG adalah penawaran Pratinjau, yang tunduk pada "Persyaratan Penawaran Pra-GA" dari Persyaratan Khusus Layanan Google Cloud. Produk dan fitur pra-GA tersedia "apa adanya" dan mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran. Dengan menggunakan Gemini API di Gemini Enterprise Agent Platform, Anda menyetujui persyaratan dan ketentuan Pratinjau AI Generatif (Persyaratan Pratinjau).

Mengimpor data ke ANN RagManagedDb

Anda dapat menggunakan ImportRagFiles API atau UploadRagFile API untuk mengimpor data ke ANN RagManagedDb. Namun, tidak seperti strategi pengambilan KNN, pendekatan ANN mengharuskan indeks berbasis pohon yang mendasarinya dibangun ulang setidaknya sekali dan secara opsional setelah mengimpor data dalam jumlah besar untuk perolehan yang optimal. Agar RAG Engine membangun ulang indeks ANN Anda, tetapkan rebuild_ann_index ke benar (true) dalam permintaan ImportRagFiles API Anda.

Berikut adalah hal-hal penting:

1. Sebelum mengkueri korpus RAG, Anda harus membangun ulang indeks ANN setidaknya sekali.
2. Hanya satu pembangunan ulang indeks serentak yang didukung di project di setiap lokasi.

Untuk mengupload file lokal ke korpus RAG, lihat Mengupload file RAG file. Untuk mengimpor data ke korpus RAG dan memicu pembangunan ulang indeks ANN, lihat contoh kode berikut yang menunjukkan cara mengimpor dari Cloud Storage. Untuk mempelajari sumber data yang didukung, lihat Sumber data yang didukung untuk 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"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

# 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,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

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

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

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}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

Mengelola enkripsi

RAG Engine menyediakan opsi yang kuat untuk mengelola cara data dalam penyimpanan dienkripsi. Secara default, semua data pengguna dalam RagManagedDb dienkripsi menggunakan Google-owned and Google-managed encryption key, yang merupakan setelan default. Setelan default ini membantu Anda memverifikasi bahwa data Anda aman tanpa memerlukan konfigurasi tertentu.

Jika Anda memerlukan kontrol lebih besar atas kunci yang digunakan untuk enkripsi, RAG Engine mendukung Kunci Enkripsi yang Dikelola Pelanggan (CMEK). Dengan CMEK, Anda dapat menggunakan kunci kriptografi, yang dikelola dalam Cloud Key Management Service (KMS), untuk melindungi data korpus RAG Anda.

Untuk mengetahui informasi tentang batasan CMEK untuk korpus RAG, lihat Batasan CMEK untuk RAG Engine di Gemini Enterprise Agent Platform.

Menyiapkan kunci KMS dan memberikan izin

Sebelum dapat membuat korpus RAG yang dienkripsi dengan CMEK, Anda harus menyiapkan kunci kriptografi di Google Cloud KMS, dan memberikan izin yang diperlukan kepada akun layanan RAG Engine untuk menggunakan kunci ini.

Prasyarat

Untuk melakukan langkah-langkah penyiapan berikut, pastikan akun pengguna Anda memiliki izin Identity and Access Management (IAM) yang sesuai di Google Cloud project tempat Anda ingin membuat kunci KMS dan korpus RAG. Biasanya, peran seperti peran Admin Cloud KMS (roles/cloudkms.admin) diperlukan.

Mengaktifkan API

Untuk mengaktifkan Cloud Key Management Service API, lakukan hal berikut:

1. Buka Google Cloud konsol.
2. Pilih project tempat Anda ingin mengelola kunci, dan buat korpus RAG Anda.
3. Di kotak penelusuran, ketik "Key Management", lalu pilih layanan "Key Management".
4. Jika API tidak diaktifkan, klik Enable. Anda mungkin perlu menunggu beberapa menit hingga API disediakan sepenuhnya.

Membuat key ring dan kunci KMS

Untuk membuat key ring, lakukan hal berikut:

1. Di bagian Key Management, klik Create Key Ring.

   Masukkan:

   • Nama key ring: Masukkan nama unik untuk key ring Anda seperti rag-engine-cmek-keys.
   • Location type: Pilih Region. Key ring Cloud Key Management Service harus berada di region yang sama dengan endpoint RAG Engine yang Anda gunakan saat mengenkripsi korpus RAG dengan CMEK.
   • Lokasi: Pilih region yang dipilih seperti us-central1. Idealnya, region ini harus cocok dengan region tempat resource RAG Engine Anda akan berada.

2. Klik Create.

Untuk membuat kunci dalam key ring, lakukan hal berikut:

1. Setelah key ring dibuat, Anda akan diminta, atau Anda dapat membuka Create Key.

   Masukkan:

   • Nama kunci: Masukkan nama unik untuk kunci Anda seperti my-rag-corpus-key.
   • Tingkat perlindungan: Pilih tingkat perlindungan (Perangkat Lunak atau HSM). Jika Anda memerlukan kunci yang didukung hardware, pilih HSM.
   • Tujuan: Pilih Symmetric encrypt/decrypt. Hal ini diperlukan untuk CMEK.
   • Key material source: Pilih Generated key.
   • Rotation period: Opsional. Direkomendasikan. Konfigurasi jadwal rotasi kunci sesuai dengan kebijakan keamanan organisasi Anda seperti setiap 90 hari.

2. Klik Create.

Untuk menyalin nama resource kunci, lakukan hal berikut:

1. Setelah kunci dibuat, buka halaman detailnya.

2. Temukan nama resource. Formatnya adalah projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

   Penting: Untuk EncryptionSpec di korpus RAG Anda, Anda harus menggunakan nama resource kunci tanpa nomor versi.

3. Salin nama resource, dan hapus bagian /cryptoKeyVersions/VERSION_NUMBER. Nama resource yang diformat dengan benar adalah projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Memberikan Izin ke agen layanan RAG Engine

Agar RAG Engine dapat mengenkripsi dan mendekripsi data menggunakan kunci KMS Anda, agen layanannya memerlukan izin yang sesuai pada kunci tertentu tersebut.

Untuk mengidentifikasi agen layanan RAG Engine Anda, lakukan hal berikut:

1. Buka halaman IAM & Admin > IAM di Google Cloud konsol untuk project Anda.

2. Di halaman Identity and Access Management, centang kotak Include Google-provided role grants.

3. Di kotak penelusuran atau filter untuk daftar akun utama, telusuri agen layanan RAG Engine. Ini mengikuti pola [e-mail].

   Ganti YOUR_PROJECT_NUMBER dengan nomor Google Cloud project Anda.

Jika agen layanan RAG Engine Anda belum ada, lakukan hal berikut untuk memicu pembuatan agen layanan:

1. Aktifkan Resource Manager API.

2. Jalankan perintah ini di Cloud Shell atau command line:

   gcloud beta services identity create --service=aiplatform.googleapis.com \
       --projects=PROJECT_ID
   

   Atau, kirim panggilan REST API:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"
   

3. Pastikan agen layanan RAG Engine telah dibuat.

Untuk memberikan izin pada kunci KMS, lakukan hal berikut:

1. Kembali ke layanan Key Management di Google Cloud konsol.

2. Pilih key ring yang berisi kunci yang Anda buat.

3. Pilih kunci tertentu yang Anda buat.

4. Di halaman detail kunci, buka tab Permissions.

5. Klik Add Principal.

6. Di kolom New principals, ketik alamat email agen layanan RAG Engine.

7. Di menu drop-down Select a role, pilih peran Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter). Peran ini memberikan izin yang diperlukan kepada agen layanan untuk menggunakan kunci bagi operasi enkripsi dan dekripsi.

8. Klik Save.

Membuat korpus RAG dengan enkripsi yang dikelola pelanggan

Contoh kode ini menunjukkan cara membuat korpus RAG yang dienkripsi dengan Kunci Enkripsi yang Dikelola Pelanggan (CMEK).

Ganti variabel dalam contoh kode berikut:

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "encryption_spec" : {
        "kms_key_name" : '\""${KMS_KEY_NAME}"\"'
      }
    }'

Kuota

Saat Anda menggunakan CMEK dengan layanan Gemini Enterprise Agent Platform, seperti RAG Engine di Gemini Enterprise Agent Platform, ada kuota untuk jumlah kunci Cloud KMS unik yang dapat digunakan per project per region. Kuota ini dilacak oleh metrik aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Setiap kali Anda menggunakan kunci KMS baru yang unik untuk membuat resource seperti korpus RAG dalam project dan region, kunci KMS akan menggunakan satu unit kuota ini. Unit kuota ini tidak dirilis meskipun resource yang menggunakan kunci tertentu tersebut dihapus.

Jika Anda memerlukan lebih banyak kunci unik daripada batas saat ini, Anda harus meminta peningkatan kuota untuk aiplatform.googleapis.com/in_use_customer_managed_encryption_keys untuk region yang dipilih.

Untuk mengetahui informasi selengkapnya tentang cara meminta peningkatan kuota, lihat Melihat dan mengedit kuota di Google Cloud konsol.

Langkah berikutnya

• Untuk mempelajari RagManagedDb lebih lanjut, lihat Mode deployment.
• Untuk mengimpor file dan folder dari Google Drive atau Cloud Storage, lihat Contoh mengimpor file RAG example.
• Untuk mencantumkan file RAG, lihat Contoh mencantumkan file RAG.