Menggunakan Pinecone dengan Mesin RAG Platform Agen Gemini Enterprise

Halaman ini menunjukkan cara menghubungkan korpus RAG ke database Pinecone Anda.

Anda juga dapat mengikuti menggunakan notebook ini Mesin RAG Platform Agen Gemini Enterprise dengan Pinecone.

Anda dapat menggunakan instance database Pinecone dengan Mesin RAG Platform Agen Gemini Enterprise untuk mengindeks, dan melakukan penelusuran kesamaan berbasis vektor. Penelusuran kesamaan adalah cara untuk menemukan potongan teks yang mirip dengan teks yang Anda cari, yang memerlukan penggunaan model embedding. Model embedding menghasilkan data vektor untuk setiap bagian teks yang dibandingkan. Penelusuran kemiripan digunakan untuk mengambil konteks semantik untuk perujukan guna menampilkan konten yang paling akurat dari LLM Anda.

Dengan Mesin RAG Platform Agen Gemini Enterprise, Anda dapat terus menggunakan instance database vektor yang dikelola sepenuhnya, yang penyediaannya menjadi tanggung jawab Anda. Mesin RAG Platform Agen Gemini Enterprise menggunakan database vektor Anda untuk penyimpanan, pengelolaan indeks, dan penelusuran.

Mempertimbangkan apakah akan menggunakan Pinecone dengan Mesin RAG Platform Agen Gemini Enterprise

Pertimbangkan apakah penggunaan database Pinecone adalah pilihan terbaik untuk aplikasi RAG Anda dengan meninjau hal berikut:

  • Anda harus membuat, mengonfigurasi, dan mengelola penskalaan instance database Pinecone.

  • Mesin RAG Platform Agen Gemini Enterprise menggunakan namespace default di indeks Anda. Pastikan namespace ini tidak dapat diubah oleh hal lain.

  • Anda harus memberikan kunci API Pinecone, yang memungkinkan Mesin RAG Platform Agen Gemini Enterprise berinteraksi dengan database Pinecone. Mesin RAG Platform Agen Gemini Enterprise tidak menyimpan dan mengelola kunci API Pinecone Anda. Sebagai gantinya, Anda harus melakukan hal berikut:

    • Simpan kunci Anda di Google Cloud Secret Manager.
    • Beri akun layanan project Anda izin untuk mengakses secret Anda.
    • Memberikan akses Mesin RAG Platform Agen Gemini Enterprise ke nama resource rahasia Anda.

    • Saat Anda berinteraksi dengan korpus RAG Anda, Mesin RAG Platform Agen Gemini Enterprise mengakses resource rahasia Anda menggunakan akun layanan Anda.

    • Korpus RAG dan indeks Pinecone memiliki pemetaan satu-ke-satu. Asosiasi ini dibuat sebagai bagian dari metode ragCorpora.create atau metode ragCorpora.patch.

Buat indeks Pinecone Anda

Untuk membuat indeks Pinecone, Anda harus mengikuti langkah-langkah berikut:

  1. Lihat panduan memulai cepat Pinecone untuk mendapatkan konfigurasi indeks yang harus ditentukan pada indeks Anda agar indeks kompatibel dengan korpus RAG.

  2. Anda ingin memastikan bahwa lokasi indeks Pinecone sama dengan atau dekat dengan lokasi Anda menggunakan Mesin RAG Platform Agen Gemini Enterprise karena alasan berikut:

    • Anda ingin mempertahankan latensi yang lebih rendah.
    • Anda ingin memenuhi persyaratan residensi data yang ditetapkan oleh hukum yang berlaku.

  3. Selama pembuatan indeks Pinecone, tentukan dimensi penyematan yang akan digunakan dengan Mesin RAG Platform Agen Gemini Enterprise. Tabel ini memberikan ukuran dimensi atau lokasi ukuran dimensi:

    Model Ukuran dimensi
    Gecko Pihak Pertama 768
    Gecko pihak pertama yang dioptimalkan 768
    E5 Lihat Menggunakan model embedding OSS.

  4. Pilih salah satu metrik jarak yang didukung berikut:

    • cosine
    • dotproduct
    • euclidean

  5. Opsional: Saat membuat indeks berbasis pod, Anda harus menentukan file_id di kolom pod.metadata_config.indexed. Untuk mengetahui informasi selengkapnya, lihat Pengindeksan metadata selektif.

Buat kunci API Pinecone Anda

Mesin RAG Platform Agen Gemini Enterprise hanya dapat terhubung ke indeks Pinecone Anda menggunakan kunci API Anda untuk autentikasi dan otorisasi. Anda harus mengikuti panduan resmi Pinecone untuk autentikasi guna mengonfigurasi autentikasi berbasis kunci API di project Pinecone Anda.

Menyimpan kunci API Anda di Secret Manager

Kunci API menyimpan Informasi Identitas Pribadi Sensitif (SPII), yang tunduk pada persyaratan hukum. Jika data SPII disusupi atau disalahgunakan, individu dapat mengalami risiko atau bahaya yang signifikan. Untuk meminimalkan risiko bagi individu saat menggunakan Mesin RAG Platform Agen Gemini Enterprise, jangan menyimpan dan mengelola kunci API Anda, serta hindari membagikan kunci API yang tidak dienkripsi.

Untuk melindungi SPII, Anda harus melakukan hal berikut:

  1. Simpan kunci API Anda di Secret Manager.

  2. Beri akun layanan Mesin RAG Platform Agen Gemini Enterprise Anda izin ke rahasia Anda, dan kelola kontrol akses di tingkat resource rahasia.

    1. Buka izin project Anda.

    2. Aktifkan opsi Sertakan pemberian peran yang disediakan Google.

    3. Temukan akun layanan, yang memiliki format:

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. Edit akun utama akun layanan.

    5. Tambahkan peran Secret Manager Secret Accessor ke akun layanan.

  3. Selama pembuatan atau pembaruan korpus RAG, teruskan nama resource secret ke Mesin RAG Platform Agen Gemini Enterprise, dan simpan nama resource secret.

Saat membuat permintaan API ke indeks Pinecone Anda, Mesin RAG Platform Agen Gemini Enterprise menggunakan setiap akun layanan untuk membaca kunci API yang sesuai dengan resource rahasia Anda di Secret Manager dari project Anda.

Menyediakan akun layanan Mesin RAG Platform Agen Gemini Enterprise

Saat Anda membuat korpus RAG pertama di project, Mesin RAG Platform Agen Gemini Enterprise akan membuat akun layanan khusus. Anda dapat menemukan akun layanan dari halaman Identity and Access Management project Anda.

Akun layanan mengikuti format tetap ini:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Misalnya,

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

Menyiapkan korpus RAG

Untuk menggunakan indeks Pinecone dengan Mesin RAG Platform Agen Gemini Enterprise, Anda harus mengaitkan indeks dengan korpus RAG selama tahap pembuatannya. Setelah asosiasi dibuat, pengikatan ini bersifat permanen selama masa aktif korpus RAG. Pengaitan dapat dilakukan menggunakan CreateRagCorpus atau UpdateRagCorpus API.

Agar asosiasi dianggap selesai, Anda harus menetapkan tiga kolom utama pada korpus RAG:

  • rag_vector_db_config.pinecone: Kolom ini membantu Anda menetapkan pilihan database vektor yang ingin dikaitkan dengan korpus RAG, dan harus ditetapkan selama panggilan API CreateRagCorpus. Jika tidak ditetapkan, pilihan database vektor default RagManagedDb akan ditetapkan ke korpus RAG Anda.

  • rag_vector_db_config.pinecone.index_name: Ini adalah nama yang digunakan untuk membuat indeks Pinecone yang digunakan dengan korpus RAG. Anda dapat menetapkan nama selama panggilan CreateRagCorpus, atau Anda dapat menentukan nama saat memanggil API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Ini adalah nama lengkap resource secret yang disimpan di Secret Manager, yang berisi kunci API Pinecone Anda. Anda dapat menetapkan nama selama panggilan CreateRagCorpus, atau Anda dapat menentukan nama saat memanggil API UpdateRagCorpus. Sebelum menentukan kolom ini, Anda tidak dapat mengimpor data ke dalam korpus RAG.

    Kolom ini harus memiliki format berikut:

    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Membuat set data RAG Anda

Jika Anda memiliki akses ke nama indeks Pinecone dan nama resource rahasia dengan setelan izin Anda, Anda dapat membuat korpus RAG dan mengaitkannya dengan indeks Pinecone, yang ditunjukkan dalam contoh kode ini.

Saat pertama kali membuat korpus RAG, Anda belum menyiapkan informasi akun layanan. Namun, kolom bersifat opsional dan dapat dikaitkan dengan korpus RAG menggunakan API UpdateRagCorpus.

Untuk contoh cara membuat korpus RAG tanpa memberikan informasi akun layanan, lihat Membuat korpus RAG tanpa nama indeks atau kunci API.

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=embedding_model_config,
        vector_db=vector_db,
    ),
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Membuat korpus RAG tanpa nama indeks atau kunci API

Jika ini adalah korpus RAG pertama Anda dan Anda tidak memiliki akses ke detail akun layanan Anda, atau Anda belum menyelesaikan langkah-langkah penyediaan untuk indeks Pinecone, Anda tetap dapat membuat korpus RAG. Kemudian, Anda dapat mengaitkan korpus RAG dengan konfigurasi Pinecone kosong, dan menambahkan detailnya nanti.

Hal berikut harus dipertimbangkan:

  • Jika Anda tidak memberikan nama indeks dan nama secret kunci API, file tidak dapat diimpor ke dalam korpus RAG.

  • Jika Anda memilih Pinecone sebagai database vektor untuk korpus RAG, database tersebut tidak dapat dialihkan ke database lain di kemudian hari.

Contoh kode ini menunjukkan cara membuat korpus RAG dengan Pinecone tanpa memberikan nama indeks Pinecone atau nama rahasia API. Gunakan UpdateRagCorpus API untuk menentukan informasi yang tidak ada nanti.

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Memperbarui korpus RAG Anda

UpdateRagCorpus API memungkinkan Anda memperbarui konfigurasi database vektor. Jika nama indeks Pinecone dan versi rahasia kunci API belum ditetapkan sebelumnya, Anda dapat menggunakan Pinecone API untuk memperbarui kolom. Pilihan database vektor tidak dapat diperbarui. Anda dapat memberikan rahasia kunci API, tetapi tidak wajib. Namun, jika Anda tidak menentukan rahasia kunci API, Anda dapat mengimpor data ke korpus RAG.

Kolom Dapat Berubah Wajib Diisi atau Opsional
rag_vector_db_config.vector_db Tidak dapat diubah setelah Anda membuat pilihan. Wajib
rag_vector_db_config.pinecone.index_name Tidak dapat diubah setelah Anda menyetel kolom pada korpus RAG. Wajib
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Dapat berubah. Setelah menetapkan kunci API, Anda tidak dapat menghapus kunci. Opsional

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Langkah berikutnya