搭配 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 語料庫的整個生命週期中持續存在。您可以使用 CreateRagCorpusUpdateRagCorpus 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}

後續步驟