搭配使用 Pinecone 與 RAG Engine

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

您也可以使用這個筆記本逐步操作：搭配 Pinecone 使用 RAG Engine。

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

使用 RAG Engine 時，您可以繼續使用完全代管的向量資料庫執行個體，但您必須負責佈建。RAG Engine 會使用向量資料庫進行儲存、索引管理和搜尋。

考慮是否要搭配使用 Pinecone 與 RAG Engine

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

  • 您必須建立、設定及管理 Pinecone 資料庫執行個體的資源配置。

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

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

    • 將金鑰儲存在 Google Cloud Secret Manager。
    • 授予專案的服務帳戶存取密鑰的權限。
    • 提供密鑰的資源名稱，讓 RAG Engine 能夠存取。

    • 與 RAG 語料庫互動時，RAG Engine 會使用服務帳戶存取密鑰資源。

    • RAG 語料庫和 Pinecone 索引會一一對應。這項關聯是在 ragCorpora.create 方法或 ragCorpora.patch 方法中建立。

建立 Pinecone 索引

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

  1. 請參閱 Pinecone 快速入門指南，瞭解索引設定，確保索引與 RAG 語料庫相容。

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

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

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

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

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

    • cosine
    • dotproduct
    • euclidean

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

建立 Pinecone API 金鑰

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

將 API 金鑰儲存在 Secret Manager

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

為保護 SPII，您必須採取下列措施：

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

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

    1. 前往專案的權限。

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

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

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

    4. 編輯服務帳戶主體。

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

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

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

佈建 RAG Engine 服務帳戶

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

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

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

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

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

準備 RAG 語料庫

如要搭配 RAG Engine 使用 Pinecone 索引，您必須在建立索引時將其與 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。

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


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}

後續步驟