搭配 Vertex AI RAG 引擎使用 Pinecone

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

您也可以使用這個 Notebook Vertex AI RAG 引擎搭配 Pinecone，跟著操作。

您可以使用 Pinecone 資料庫例項搭配 Vertex AI RAG Engine 建立索引，並執行以向量為基礎的相似度搜尋。相似度搜尋可用於找出與所尋找文字相似的文字片段，但必須使用嵌入模型。嵌入模型會針對每個要比較的文字片段產生向量資料。相似度搜尋可用於擷取依據的語意內容，以便從 LLM 傳回最準確的內容。

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

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

請查看下列資訊，判斷使用 Pinecone 資料庫是否為 RAG 應用程式的最佳選擇：

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

  • Vertex AI RAG Engine 會在索引中使用預設命名空間。請確認這個命名空間不會受到其他項目的修改。

  • 您必須提供 Pinecone API 金鑰，讓 Vertex AI RAG Engine 與 Pinecone 資料庫互動。Vertex AI RAG 引擎不會儲存及管理您的 Pinecone API 金鑰。而是必須採取以下做法：

    • 將金鑰儲存於 Google Cloud Secret Manager。
    • 授予專案服務帳戶存取密鑰的權限。
    • 讓 Vertex AI RAG Engine 存取您的機密資源名稱。
    • 您與 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 Engine 搭配使用的嵌入維度。下表列出維度大小或維度大小的位置：

    模型 維度大小
    第一方 Gecko 768
    精細調整第一方 Gecko 768
    E5 請參閱「使用 OSS 嵌入模型」。

  4. 請選擇下列支援的距離指標：

    • cosine
    • dotproduct
    • euclidean

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

建立 Pinecone API 金鑰

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

將 API 金鑰儲存在 Secret Manager 中

API 金鑰會儲存具敏感性的個人識別資訊 (SPII)，須遵守法律規定。如果 SPII 資料遭到盜用或濫用，使用者可能會面臨重大風險或傷害。為降低使用 Vertex AI RAG Engine 時對個人造成的風險，請勿儲存及管理 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 Engine 服務帳戶

在專案中建立第一個 RAG 語料庫時，Vertex AI RAG Engine 會建立專用服務帳戶。您可以在專案的「Identity and Access Management」頁面中找到服務帳戶。

服務帳戶的格式固定如下：

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

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

[email protected]

準備 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：這是用來建立與 RAG 語料庫搭配使用的 Pinecone 索引的名稱。您可以在 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 語料庫時不提供服務帳戶資訊的範例，請參閱「不使用索引名稱或 API 鍵建立 RAG 語料庫」。

Python

在試用這個範例之前，請先按照 Vertex AI 快速入門：使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 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}

不使用索引名稱或 API 金鑰建立 RAG 語料庫

如果這是您首次建立 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}

後續步驟