本頁面說明如何將 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 索引,請按照下列步驟操作:
請參閱 Pinecone 快速入門指南,瞭解必須在索引中指定的索引設定,以便讓索引與 RAG 語料庫相容。
您需要確保 Pinecone 索引的位置與您使用 Vertex AI RAG Engine 的位置相同或相近,原因如下:
- 您希望維持較低的延遲時間。
- 您想遵守適用法律規定的資料落地規定。
建立 Pinecone 索引時,請指定要與 Vertex AI RAG Engine 搭配使用的嵌入維度。下表列出維度大小或維度大小的位置:
模型 維度大小 第一方 Gecko 768 精細調整第一方 Gecko 768 E5 請參閱「使用 OSS 嵌入模型」。 請選擇下列支援的距離指標:
cosine
dotproduct
euclidean
選用:建立以 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,您必須採取下列做法:
將 API 金鑰儲存在 Secret Manager 中。
授予 Vertex AI RAG Engine 服務帳戶密鑰的權限,並在密鑰資源層級管理存取控制。
前往專案的權限。
啟用「包含 Google 提供的角色授予項目」選項。
找出服務帳戶,格式如下:
service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
編輯服務帳戶的使用者。
將
Secret Manager Secret Accessor
角色新增至服務帳戶。
在建立或更新 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
例如,假設使用者要求系統 將文字從英文翻譯成法文
準備 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 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
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}