Menggunakan RagManagedDb dengan Mesin RAG Vertex AI

Halaman ini menunjukkan cara Vertex AI RAG Engine 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.

Mengelola strategi pengambilan Anda

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

Membuat korpus RAG dengan KNN RagManagedDb

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

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Vertex AI 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))

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

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 berdasarkan 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 hierarki. 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 daripada itu, tetapkan ini ke 3.
• Jika tree_depth tidak ditentukan, Vertex AI RAG Engine akan menetapkan nilai default 2 untuk parameter ini.

leaf_count menentukan jumlah node daun dalam struktur berbasis pohon. Setiap node daun berisi kelompok vektor yang terkait erat bersama dengan sentroid yang sesuai. Ikuti pedoman berikut:

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

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

from vertexai 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 Vertex AI 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))

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

Mengimpor data Anda ke ANN RagManagedDb

Anda dapat menggunakan ImportRagFiles API atau UploadRagFile API untuk mengimpor data ke dalam 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 sejumlah besar data untuk mendapatkan recall yang optimal. Agar Vertex AI RAG Engine membangun ulang indeks ANN Anda, tetapkan rebuild_ann_index ke benar (true) dalam permintaan API ImportRagFiles Anda.

Hal-hal berikut penting:

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

Untuk mengupload file lokal ke dalam korpus RAG, lihat Mengupload file RAG. Untuk mengimpor data ke dalam 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.

from vertexai 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 Vertex AI 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()

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 Anda

Vertex AI RAG Engine menyediakan opsi yang andal untuk mengelola cara mengenkripsi data Anda dalam penyimpanan. 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, Vertex AI 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 Mesin RAG Vertex AI.

Siapkan kunci KMS dan berikan 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 Vertex AI RAG Engine untuk menggunakan kunci ini.

Prasyarat

Untuk melakukan langkah-langkah penyiapan berikut, pastikan akun pengguna Anda memiliki izin Pengelolaan Akses dan Identitas (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 KMS API, lakukan hal berikut:

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

Buat key ring dan kunci KMS Anda

Untuk membuat key ring, lakukan hal berikut:

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

   Masukkan:

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

2. Klik Buat.

Untuk membuat kunci dalam key ring, lakukan hal berikut:

1. Setelah key ring dibuat, Anda akan diminta, atau Anda dapat membuka Buat Kunci.

   Masukkan:

   • Nama kunci: Masukkan nama unik untuk kunci Anda, seperti my-rag-corpus-key.
   • Tingkat perlindungan: Pilih tingkat perlindungan (Software atau HSM). Jika Anda memerlukan kunci yang didukung hardware, pilih HSM.
   • Tujuan: Pilih Symmetric encrypt/decrypt. Ini diperlukan untuk CMEK.
   • Sumber materi utama: Pilih Kunci yang dibuat.
   • Periode rotasi: Opsional. Direkomendasikan. Konfigurasi jadwal rotasi kunci sesuai dengan kebijakan keamanan organisasi Anda, misalnya setiap 90 hari.

2. Klik Buat.

Untuk menyalin nama resource kunci, lakukan langkah-langkah 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.

3. Salin nama resource, lalu hapus bagian /cryptoKeyVersions/VERSION_NUMBER tersebut. 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 Vertex AI RAG Engine

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

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

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

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

3. Di kolom filter atau penelusuran untuk daftar prinsipal, telusuri agen layanan Vertex AI RAG Engine. Mengikuti pola service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.

   Ganti YOUR_PROJECT_NUMBER dengan nomor project Google Cloud Anda.

Jika agen layanan Vertex AI 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 Vertex AI RAG Engine telah dibuat.

Untuk memberikan izin pada kunci KMS, lakukan hal berikut:

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

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

3. Pilih kunci spesifik 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 Vertex AI 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 Simpan.

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:

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

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 Vertex AI, seperti Vertex AI RAG Engine, 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 tersebut akan menggunakan satu unit kuota ini. Unit kuota ini tidak dilepaskan meskipun resource yang menggunakan kunci tertentu tersebut dihapus.

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

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

Langkah berikutnya

• Untuk mempelajari RagManagedDb lebih lanjut, lihat Memahami RagManagedDb.
• Untuk mengimpor file dan folder dari Google Drive atau Cloud Storage, lihat Contoh mengimpor file RAG.
• Untuk mencantumkan file RAG, lihat contoh Mencantumkan file RAG.