搭配 Vertex AI RAG 引擎使用 Pinecone

本頁說明如何將 RAG 語料庫連結至 Pinecone 資料庫。

您也可以使用這本筆記本 Vertex AI RAG Engine with Pinecone 逐步操作。

您可以將 Pinecone 資料庫執行個體與 Vertex AI RAG 引擎搭配使用，建立索引並執行向量相似度搜尋。相似度搜尋可找出與您要搜尋的文字相似的文字片段，這需要使用嵌入模型。嵌入模型會為每個要比較的文字片段產生向量資料。相似度搜尋用於擷取依據的語意脈絡，以便從 LLM 傳回最準確的內容。

使用 Vertex AI RAG 引擎時，您可以繼續使用全代管向量資料庫執行個體 (您負責佈建)。Vertex AI RAG Engine 會使用向量資料庫進行儲存、索引管理和搜尋。

考慮是否要搭配使用 Pinecone 與 Vertex AI RAG 引擎

請參閱下列內容，判斷使用 Pinecone 資料庫是否最適合您的 RAG 應用程式：

  • 您必須建立、設定及管理 Pinecone 資料庫執行個體的縮放作業。

  • Vertex AI RAG 引擎會使用索引的預設命名空間。請確保這個命名空間不會遭到其他項目修改。

  • 您必須提供 Pinecone API 金鑰，讓 Vertex AI RAG Engine 與 Pinecone 資料庫互動。Vertex AI RAG 引擎不會儲存及管理 Pinecone API 金鑰。請改用下列方法：

    • 將金鑰儲存在 Google Cloud Secret Manager。
    • 授予專案服務帳戶存取密鑰的權限。
    • 提供 Vertex AI RAG 引擎的存取權，以存取密鑰的資源名稱。
    • 與 RAG 語料庫互動時，Vertex AI RAG 引擎會使用服務帳戶存取機密資源。

  • RAG 語料庫和 Pinecone 索引會一一對應。這項關聯會在 CreateRagCorpus API 呼叫或 UpdateRagCorpus API 呼叫中建立。

建立 Pinecone 索引

如要建立 Pinecone 索引，請按照下列步驟操作：

  1. 請參閱 Pinecone 快速入門指南，取得索引設定，您必須在索引中指定這些設定，才能讓索引與 RAG 語料庫相容。

  2. 您要確保 Pinecone 索引的位置與使用 Vertex AI RAG Engine 的位置相同或相近，原因如下：

    • 您希望維持較低的延遲時間。
    • 您希望符合適用法律規定的資料落地規定。

  3. 建立 Pinecone 索引時，請指定要搭配 Vertex AI RAG 引擎使用的嵌入維度。下表提供維度大小或維度大小的位置：

    模型 尺寸
    第一方 Gecko 768
    微調過的第一方 Gecko 768
    E5 請參閱「使用 OSS 嵌入模型」。

  4. 選擇下列其中一種支援的距離指標：

    • cosine
    • dotproduct
    • euclidean

  5. 選用：建立以 Pod 為基礎的索引時，您必須在 pod.metadata_config.indexed 欄位中指定 file_id。詳情請參閱「選擇性中繼資料索引」。

建立 Pinecone API 金鑰

Vertex AI RAG 引擎只能使用 API 金鑰進行驗證和授權，才能連線至 Pinecone 索引。您必須按照 Pinecone 官方指南中的驗證步驟，在 Pinecone 專案中設定以 API 金鑰為基礎的驗證。

將 API 金鑰儲存在 Secret Manager 中

API 金鑰含有具敏感性的個人識別資訊 (SPII)，因此須遵守法律規定。如果 SPII 資料外洩或遭到濫用，可能會對個人造成重大風險或傷害。為盡量降低個人使用 Vertex AI RAG 引擎時的風險，請勿儲存及管理 API 金鑰，並避免分享未加密的 API 金鑰。

為保護 SPII，您必須採取下列做法：

  1. 將 API 金鑰儲存在 Secret Manager。

  2. 授予 Vertex AI RAG Engine 服務帳戶密鑰的權限，並在密鑰資源層級管理存取權控管。

    1. 前往專案權限。

    2. 啟用「包含 Google 提供的角色授權」選項。

    3. 找出格式如下的服務帳戶：

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

    4. 編輯服務帳戶主體。

    5. 將 Secret Manager Secret Accessor 角色新增至服務帳戶。

  3. 建立或更新 RAG 語料庫時，請將密鑰資源名稱傳遞至 Vertex AI RAG 引擎，並儲存密鑰資源名稱。

向 Pinecone 索引提出 API 要求時，Vertex AI RAG Engine 會使用每個服務帳戶，從專案的 Secret Manager 讀取與密鑰資源對應的 API 金鑰。

佈建 Vertex AI RAG 引擎服務帳戶

在專案中建立第一個 RAG 語料庫時，Vertex AI RAG 引擎會建立專屬服務帳戶。您可以在專案的「身分與存取權管理」頁面中找到服務帳戶。

服務帳戶採用下列固定格式：

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

例如，假設使用者要求系統 將文字從英文翻譯成法文

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

準備 RAG 語料庫

如要將 Pinecone 索引與 Vertex AI RAG Engine 搭配使用，您必須在建立索引時，將索引與 RAG 語料庫建立關聯。建立關聯後，這項繫結在 RAG 語料庫的生命週期內將永久存在。您可以使用 CreateRagCorpus 或 UpdateRagCorpus API 建立關聯。

如要視為完成關聯，您必須在 RAG 語料庫中設定三個重要欄位：

  • rag_vector_db_config.pinecone：這個欄位可協助您設定要與 RAG 語料庫建立關聯的向量資料庫，且必須在 CreateRagCorpus API 呼叫期間設定。如果未設定，系統會將預設向量資料庫選項 RagManagedDb 指派給 RAG 語料庫。

  • rag_vector_db_config.pinecone.index_name：這是用於建立 Pinecone 索引的名稱，該索引會與 RAG 語料庫搭配使用。您可以在 CreateRagCorpus 呼叫期間設定名稱，也可以在呼叫 UpdateRagCorpus API 時指定名稱。

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version： 這是儲存在 Secret Manager 中的密鑰完整資源名稱，內含 Pinecone API 金鑰。您可以在 CreateRagCorpus 呼叫期間設定名稱，也可以在呼叫 UpdateRagCorpus API 時指定名稱。如未指定這個欄位，您就無法將資料匯入 RAG 語料庫。
    這個欄位的格式應為：
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

建立 RAG 語料庫

如果您有權存取 Pinecone 索引名稱和密鑰資源名稱，並已設定權限，就可以建立 RAG 語料庫，並將其與 Pinecone 索引建立關聯，如本範例程式碼所示。

首次建立 RAG 語料庫時，您不會有服務帳戶資訊。不過，這些欄位是選填欄位，可使用 UpdateRagCorpus API 與 RAG 語料庫建立關聯。

如要瞭解如何建立 RAG 語料庫，而不提供服務帳戶資訊，請參閱「建立 RAG 語料庫，但不提供索引名稱或 API 金鑰」。

Python

在試用這個範例之前，請先按照Python使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 Vertex AI Python API 參考說明文件。

如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。


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}

建立 RAG 語料庫，但沒有索引名稱或 API 金鑰

如果這是您的第一個 RAG 語料庫，且您無法存取服務帳戶詳細資料，或尚未完成 Pinecone 索引的佈建步驟，您仍可建立 RAG 語料庫。然後，您可以將 RAG 語料庫與空白的 Pinecone 設定建立關聯，稍後再新增詳細資料。

請務必考量下列事項：

  • 如果未提供索引名稱和 API 金鑰密鑰名稱，檔案就無法匯入 RAG 語料庫。
  • 如果選擇 Pinecone 做為 RAG 語料庫的向量資料庫，之後就無法切換至其他資料庫。

這個程式碼範例說明如何使用 Pinecone 建立 RAG 語料庫，而不需提供 Pinecone 索引名稱或 API 密鑰名稱。使用 UpdateRagCorpus API 稍後指定缺少的資訊。

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}

更新 RAG 語料庫

UpdateRagCorpus API 可讓您更新向量資料庫設定。 如果先前未設定 Pinecone 索引名稱和 API 金鑰密鑰版本，可以使用 Pinecone API 更新這些欄位。向量資料庫一經選定就無法更新。API 金鑰密鑰為選填項目。不過，如果您未指定 API 金鑰密鑰，仍可將資料匯入 RAG 語料庫。

欄位 可變動性 必要或選用
rag_vector_db_config.vector_db 選擇後即無法變更。 必填
rag_vector_db_config.pinecone.index_name 在 RAG 語料庫中設定欄位後，即無法變更。 必填
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version 可變動。設定 API 金鑰後，就無法捨棄金鑰。 選用

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}

後續步驟