Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

搭配使用 Pinecone 與 RAG Engine

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

您也可以使用這個筆記本：RAG Engine with Pinecone。

您可以搭配使用 Pinecone 資料庫執行個體與 RAG Engine，建立索引並執行向量相似度搜尋。相似度搜尋是一種尋找與您要尋找的文字相似的文字片段的方法，這需要使用嵌入模型。嵌入模型會為要比較的每段文字產生向量資料。相似度搜尋用於擷取基準的語意背景資訊，以便從 LLM 傳回最準確的內容。

有了 RAG Engine，您就能繼續使用全代管向量資料庫執行個體，但必須自行佈建。RAG Engine 會使用向量資料庫進行儲存、索引管理和搜尋。

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

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

您必須建立、設定及管理 Pinecone 資料庫執行個體的資源調度。
RAG Engine 會使用索引的預設命名空間。請確保這個命名空間不會遭到其他任何項目修改。
您必須提供 Pinecone API 金鑰，RAG Engine 才能與 Pinecone 資料庫互動。RAG Engine 不會儲存及管理 Pinecone API 金鑰。請改為執行下列操作：
- 將金鑰儲存在 Google Cloud Secret Manager。
- 授予專案服務帳戶存取 Secret 的權限。
- 提供 RAG Engine 密鑰資源名稱的存取權。
- 與 RAG 語料庫互動時，RAG Engine 會使用您的服務帳戶存取 Secret 資源。
- RAG 語料庫和 Pinecone 索引有一對一對應關係。這項關聯是透過 ragCorpora.create 方法或 ragCorpora.patch 方法建立。

建立 Pinecone 索引

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

請參閱 Pinecone 快速入門指南，瞭解必須在索引中指定的索引設定，讓索引與 RAG 語料庫相容。
基於下列原因，請務必確保 Pinecone 索引的位置與使用 RAG Engine 的位置相同或相近：
- 您希望維持較低的延遲時間。
- 您希望符合適用法律規定的資料落地要求。
建立 Pinecone 索引時，請指定要與 RAG Engine 搭配使用的嵌入維度。下表提供維度大小或維度大小的位置：

模型維度大小

第一方 Gecko 768

經過微調的第一方 Gecko 768

E5 請參閱「使用 OSS 嵌入模型」。
選擇下列其中一種支援的距離指標：
- cosine
- dotproduct
- euclidean
選用：建立以 Pod 為基礎的索引時，必須在 pod.metadata_config.indexed 欄位中指定 file_id。詳情請參閱「選擇性中繼資料索引」。

模型	維度大小
第一方 Gecko	768
經過微調的第一方 Gecko	768
E5	請參閱「使用 OSS 嵌入模型」。

建立 Pinecone API 金鑰

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

將 API 金鑰儲存在 Secret Manager

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

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

將 API 金鑰儲存在 Secret Manager。
將密鑰權限授予 RAG Engine 服務帳戶，並在密鑰資源層級管理存取控管機制。
1. 前往專案權限。
2. 啟用「包含 Google 提供的角色授予項目」選項。
3. 找出服務帳戶，格式如下：
  
  service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
4. 編輯服務帳戶的主體。
5. 將 Secret Manager Secret Accessor 角色新增至服務帳戶。
建立或更新 RAG 語料庫時，請將 Secret 資源名稱傳遞至 RAG Engine，並儲存 Secret 資源名稱。

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

佈建 RAG Engine 服務帳戶

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

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

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：這個名稱用於建立與 RAG 語料庫搭配使用的 Pinecone 索引。您可以在 CreateRagCorpus 呼叫期間設定名稱，也可以在呼叫 UpdateRagCorpus API 時指定名稱。
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version：儲存在 Secret Manager 中的 Secret 完整資源名稱，其中包含 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

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

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


import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfig(
    pinecone=types.RagVectorDbConfigPinecone(
        index_name=pinecone_index_name,
    ),
    api_auth=types.ApiAuth(
        api_key_config=types.ApiAuthApiKeyConfig(
            api_key_secret_version=pinecone_api_key_secret_manager_version
        )
    ),
    rag_embedding_model_config=embedding_model_config,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=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 金鑰 Secret，您仍可將資料匯入 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}

後續步驟

搭配使用 Gemini Enterprise Agent Platform 向量搜尋和 RAG Engine

搭配使用 Pinecone 與 RAG Engine 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

建立 Pinecone 索引

建立 Pinecone API 金鑰

將 API 金鑰儲存在 Secret Manager

佈建 RAG Engine 服務帳戶

準備 RAG 語料庫

建立 RAG 語料庫

Python

REST

建立 RAG 語料庫，不指定索引名稱或 API 金鑰

Python

REST

更新 RAG 語料庫

Python

REST

後續步驟

搭配使用 Pinecone 與 RAG Engine